dex-analysis: add WARP diag analysis tools and reader D.O.

Author: theruther4d

apps/dex-analysis/README.md

@@ -20,6 +20,8 @@ Currently available tools:
 | **Remote Captures**                  | `dex_list_remote_capture_eligible_devices` | Retrieve a list of devices eligible for remote captures like packet captures or WARP diagnostics.                                                      |
 |                                      | `dex_create_remote_capture`                | Initiate a remote capture on a specific device by id.                                                                                                  |
 |                                      | `dex_list_remote_captures`                 | Retrieve a list of previously created remote captures along with their details and status.                                                             |
+|                                      | `dex_list_remote_warp_diag_contents`       | List the filenames included in a remote WARP diag capture returned by `dex_list_remote_captures`.                                                      |
+|                                      | `dex_explore_remote_warp_diag_output`      | Retreive remote WARP diag file contents by filepath returned by `dex_list_remote_warp_diag_contents`.                                                  |
 | **Fleet Status**                     | `dex_fleet_status_live`                    | View live metrics for your fleet of zero trust devices for up to the past 1 hour.                                                                      |
 |                                      | `dex_fleet_status_over_time`               | View historical metrics for your fleet of zero trust devices over time.                                                                                |
 |                                      | `dex_fleet_status_logs`                    | View historical logs for your fleet of zero trust devices for up to the past 7 days.                                                                   |
@@ -37,6 +39,7 @@ This MCP server is still a work in progress, and we plan to add more tools in th
 - `Capture a WARP diag for [email protected] and make sure to test all routes`
 - `Which users have toggled off WARP recently?`
 - `Which Cloudflare colo is most used by my users in the EU running DEX application tests?`
+- `Look at the latest WARP diag for [email protected] and tell me if you see anything notable in dns logs`
 
 ## Access the remote MCP server from any MCP Client
 

apps/dex-analysis/package.json

@@ -21,6 +21,7 @@
 		"agents": "0.0.100",
 		"cloudflare": "4.2.0",
 		"hono": "4.7.6",
+		"jszip": "3.10.1",
 		"zod": "3.24.2"
 	},
 	"devDependencies": {

apps/dex-analysis/src/dex-analysis.app.ts

@@ -19,6 +19,7 @@ import type { AuthProps } from '@repo/mcp-common/src/cloudflare-oauth-handler'
 import type { Env } from './dex-analysis.context'
 
 export { UserDetails }
+export { WarpDiagReader } from './warp_diag_reader'
 
 const env = getEnv<Env>()
 

apps/dex-analysis/src/dex-analysis.context.ts

@@ -1,5 +1,6 @@
 import type { UserDetails } from '@repo/mcp-common/src/durable-objects/user_details.do'
 import type { CloudflareDEXMCP } from './dex-analysis.app'
+import type { WarpDiagReader } from './warp_diag_reader'
 
 export interface Env {
 	OAUTH_KV: KVNamespace
@@ -10,6 +11,7 @@ export interface Env {
 	CLOUDFLARE_CLIENT_SECRET: string
 	MCP_OBJECT: DurableObjectNamespace<CloudflareDEXMCP>
 	USER_DETAILS: DurableObjectNamespace<UserDetails>
+	WARP_DIAG_READER: DurableObjectNamespace<WarpDiagReader>
 	MCP_METRICS: AnalyticsEngineDataset
 	DEV_DISABLE_OAUTH: string
 	DEV_CLOUDFLARE_API_TOKEN: string

apps/dex-analysis/src/tools/dex-analysis.tools.ts

@@ -1,11 +1,17 @@
 import { z } from 'zod'
 
 import { fetchCloudflareApi } from '@repo/mcp-common/src/cloudflare-api'
+import { getEnv } from '@repo/mcp-common/src/env'
+
+import { getReader } from '../warp_diag_reader'
 
 import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js'
 import type { ZodRawShape, ZodTypeAny } from 'zod'
 import type { CloudflareDEXMCP } from '../dex-analysis.app'
+import type { Env } from '../dex-analysis.context'
+
+const env = getEnv<Env>()
 
 export function registerDEXTools(agent: CloudflareDEXMCP) {
 	registerTool({
@@ -478,6 +484,48 @@ export function registerDEXTools(agent: CloudflareDEXMCP) {
 			})
 		},
 	})
+
+	registerTool({
+		name: 'dex_list_remote_warp_diag_contents',
+		description:
+			'Given a WARP diag remote capture download url, returns a list of the files contained in the archive.',
+		schema: {
+			download: z
+				.string()
+				.describe(
+					'The `filename` url from the dex_list_remote_captures response for successful WARP diag captures.'
+				),
+		},
+		llmContext:
+			'Use the dex_explore_remote_warp_diag_output tool for specific file paths to explore the file contents for analysis. ' +
+			'Hint: you can call dex_explore_remote_warp_diag_output multiple times in parallel if necessary to take advantage of in-memory caching for best performance.',
+		agent,
+		callback: async ({ accessToken, download }) => {
+			const reader = await getReader(env, accessToken, download)
+			return await reader.list(accessToken, download)
+		},
+	})
+
+	registerTool({
+		name: 'dex_explore_remote_warp_diag_output',
+		description:
+			'Explore the contents of remote capture WARP diag archive filepaths returned by the dex_list_remote_warp_diag_contents tool for analysis.',
+		schema: {
+			download: z
+				.string()
+				.describe(
+					'The `filename` url from the dex_list_remote_captures response for successful WARP diag captures.'
+				),
+			filepath: z.string().describe('The file path from the archive to retrieve contents for.'),
+		},
+		llmContext:
+			'To avoid hitting conversation and memory limits, avoid outputting the whole contents of these files to the user unless specifically asked to. Instead prefer to show relevant snippets only.',
+		agent,
+		callback: async ({ accessToken, download, filepath }) => {
+			const reader = await getReader(env, accessToken, download)
+			return await reader.read(accessToken, download, filepath)
+		},
+	})
 }
 
 // Helper to simplify tool registration by reducing boilerplate for accountId and accessToken

apps/dex-analysis/src/warp_diag_reader.ts

@@ -0,0 +1,76 @@
+import { DurableObject } from 'cloudflare:workers'
+import JSZip from 'jszip'
+
+import type { Env } from './dex-analysis.context'
+
+// Helper for reading large WARP diag zip archives.
+// Holds the contents in memory between requests from the agent for specific files
+// instead of having the worker download the zip on every request.
+//
+// Each DO represents one remote capture zip
+export class WarpDiagReader extends DurableObject<Env> {
+	#cache?: { files: string[]; zip: JSZip }
+
+	// List the files in the zip for the agent
+	async list(accessToken: string, url: string) {
+		const { files } = await this.#getZip(accessToken, url)
+		return files
+	}
+
+	// Return the contents of a file by path
+	async read(accessToken: string, url: string, filepath: string) {
+		const { zip } = await this.#getZip(accessToken, url)
+		const file = zip.file(filepath)
+		const content = await file?.async('text')
+		return content
+	}
+
+	async #getZip(accessToken: string, url: string) {
+		if (this.#cache) {
+			return this.#cache
+		}
+
+		console.log(`WarpDiagReader fetching `, url)
+
+		const res = await fetch(url, {
+			headers: {
+				Authorization: `Bearer ${accessToken}`,
+			},
+		})
+
+		if (res.status !== 200) {
+			throw new Error(`failed to download zip, non-200 status code: ${res.status}`)
+		}
+
+		const zip = await new JSZip().loadAsync(await res.arrayBuffer())
+		const files: string[] = []
+		for (const [relativePath, file] of Object.entries(zip.files)) {
+			if (!file.dir) {
+				files.push(relativePath)
+			}
+		}
+
+		const cache = { files, zip }
+		this.#cache = cache
+		return cache
+	}
+}
+
+async function hashToken(accessToken: string) {
+	const hashArr = Array.from(
+		new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(accessToken)))
+	)
+	return hashArr.map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+// Create unique name based on accessToken hash and download url. In order to read cached zip from memory
+// you need to have the same access token that was used to fetch it.
+async function readerName(accessToken: string, url: string) {
+	return (await hashToken(accessToken)) + url
+}
+
+export async function getReader(env: Env, accessToken: string, download: string) {
+	const name = await readerName(accessToken, download)
+	const id = env.WARP_DIAG_READER.idFromName(name)
+	return env.WARP_DIAG_READER.get(id)
+}

apps/dex-analysis/wrangler.jsonc

@@ -11,6 +11,10 @@
 		{
 			"new_sqlite_classes": ["CloudflareDEXMCP"],
 			"tag": "v1"
+		},
+		{
+			"new_sqlite_classes": ["WarpDiagReader"],
+			"tag": "v2"
 		}
 	],
 	"observability": {
@@ -25,6 +29,10 @@
 			{
 				"class_name": "UserDetails",
 				"name": "USER_DETAILS"
+			},
+			{
+				"class_name": "WarpDiagReader",
+				"name": "WARP_DIAG_READER"
 			}
 		]
 	},
@@ -65,6 +73,10 @@
 						"class_name": "UserDetails",
 						"name": "USER_DETAILS",
 						"script_name": "mcp-cloudflare-workers-observability-staging"
+					},
+					{
+						"class_name": "WarpDiagReader",
+						"name": "WARP_DIAG_READER"
 					}
 				]
 			},
@@ -98,6 +110,10 @@
 						"class_name": "UserDetails",
 						"name": "USER_DETAILS",
 						"script_name": "mcp-cloudflare-workers-observability-production"
+					},
+					{
+						"class_name": "WarpDiagReader",
+						"name": "WARP_DIAG_READER"
 					}
 				]
 			},