@gpzhang2001/sharpkit-proxy 0.2.1

package/src/index.ts

@@ -0,0 +1,598 @@
+/**
+ * Caido proxy tools — TS port of strix tools/proxy/tools.py (schemas and
+ * output shaping verbatim; the client half lives in client.ts, replay pure
+ * helpers in replay.ts). Five tools: list_requests / view_request /
+ * repeat_request / list_sitemap / view_sitemap_entry. The client resolves
+ * lazily from the sandbox session's Caido bootstrap (concurrent with scan
+ * start; the first tool call pays the login wait — strix lazy parity).
+ * @module @gpzhang2001/sharpkit-proxy
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type Schema from '@deepseek-ai/schemastery'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { CaidoClient, type SortBy } from './client.ts'
+
+/** Deployment-tunable configuration. */
+export interface Config {
+  /** Sandbox session cache key shared with the other tool packages. */
+  readonly scanId?: string
+  /** list_requests page size default (strix first=50). */
+  readonly listPageSize?: number
+  /** Replay dispatch deadline (strix 30s). */
+  readonly replayTimeoutMs?: number
+  /** Client-level per-call timeout (strix @function_tool timeout=60/120). */
+  readonly caidoTimeoutMs?: number
+  /** Ask-approval gate on repeat_request (fail-closed without an approval service). */
+  readonly requireApproval?: boolean
+  /** Authorized target hosts/values; repeat_request refuses hosts outside this list (exact or dot-suffix subdomain). */
+  readonly authorizedTargets?: string[]
+}
+
+export const name = 'pentest-tool-proxy'
+
+export const inject = ['tools', 'pentestSandbox']
+
+export const Config: Schema<Config> = z.object({
+  scanId: z.string().default('pentest'),
+  listPageSize: z.number().default(50),
+  replayTimeoutMs: z.number().default(30_000),
+  caidoTimeoutMs: z.number().default(60_000),
+  requireApproval: z.boolean().default(true),
+  authorizedTargets: z.array(z.string()),
+})
+
+/**
+ * Whether a repeat target host is inside the authorized list. Entries may be
+ * bare hosts (`example.com`), wildcard subdomains (`*.example.com`), or full
+ * URLs (hostname taken); a candidate matches on exact host or a dot-suffix
+ * subdomain. An empty list allows everything (fail-open; warned once).
+ * @param host - the replay target hostname.
+ * @param authorized - the configured target entries.
+ */
+export function targetHostAllowed(host: string, authorized: readonly string[]): boolean {
+  if (authorized.length === 0) return true
+  const candidate = host.toLowerCase()
+  return authorized.some(entry => {
+    let allowed = entry.trim().toLowerCase()
+    if (allowed === '') return false
+    if (allowed.includes('://')) {
+      try {
+        allowed = new URL(allowed).hostname
+      } catch {
+        // keep the raw entry
+      }
+    }
+    allowed = allowed.replace(/^\*\./, '').replace(/\/.*$/, '')
+    return allowed !== '' && (candidate === allowed || candidate.endsWith(`.${allowed}`))
+  })
+}
+
+/**
+ * Resolve the replay target hostname: an explicit url modification wins;
+ * otherwise the stored request's host.
+ */
+export function resolveRepeatTargetHost(storedHost: string, modifications: Readonly<Record<string, unknown>> | undefined): string {
+  const override = modifications?.['url']
+  if (typeof override === 'string' && override !== '') {
+    try {
+      return new URL(override).hostname
+    } catch {
+      // fall through to the stored host
+    }
+  }
+  return storedHost
+}
+
+/** Sitemap page size (strix parity: 30 entries per page). */
+export const SITEMAP_PAGE_SIZE = 30
+
+/**
+ * Slice one sitemap connection payload to a 1-indexed page of edges (the
+ * total count is preserved). Payloads without a recognized connection pass
+ * through untouched.
+ */
+export function pageSitemapPayload(payload: Record<string, unknown>, page: number): Record<string, unknown> {
+  for (const key of ['sitemapRootEntries', 'sitemapDescendantEntries']) {
+    const connection = payload[key]
+    if (typeof connection !== 'object' || connection === null) continue
+    const edges = (connection as { edges?: unknown }).edges
+    if (!Array.isArray(edges)) continue
+    const start = Math.max(0, (page - 1) * SITEMAP_PAGE_SIZE)
+    const sliced = edges.slice(start, start + SITEMAP_PAGE_SIZE)
+    return { ...payload, [key]: { ...(connection as Record<string, unknown>), edges: sliced, page, page_size: SITEMAP_PAGE_SIZE, has_more: start + SITEMAP_PAGE_SIZE < edges.length } }
+  }
+  return payload
+}
+
+/** strix view_request search hits: ≤20 matches with ±40 chars of context. */
+interface SearchHit {
+  readonly match: string
+  readonly position: number
+  readonly before: string
+  readonly after: string
+}
+
+/**
+ * Compact regex hits over raw content (strix `_format_search_hits`).
+ * @param content - the raw text.
+ * @param pattern - the model-supplied regex.
+ * @returns the hits payload, or an error entry when the regex is invalid.
+ */
+export function formatSearchHits(content: string, pattern: string): { readonly hits: SearchHit[]; readonly totalHits: number; readonly error?: string } {
+  let regex: RegExp
+  try {
+    regex = new RegExp(pattern, 'g')
+  } catch (error) {
+    return { hits: [], totalHits: 0, error: `Invalid regex: ${String(error)}` }
+  }
+  const hits: SearchHit[] = []
+  for (const match of content.matchAll(regex)) {
+    const start = match.index ?? 0
+    const end = start + match[0].length
+    hits.push({ match: match[0], position: start, before: content.slice(Math.max(0, start - 40), start), after: content.slice(end, end + 40) })
+    if (hits.length >= 20) break
+  }
+  return { hits, totalHits: hits.length }
+}
+
+/**
+ * Line-paginated raw content page (strix `_format_text_page`).
+ * @param content - the raw text.
+ * @param page - 1-indexed page number.
+ * @param pageSize - lines per page.
+ */
+export function formatTextPage(content: string, page: number, pageSize: number): {
+  readonly content: string
+  readonly page: number
+  readonly pageSize: number
+  readonly totalLines: number
+  readonly hasMore: boolean
+} {
+  const lines = content.split('\n')
+  const start = Math.max(0, (page - 1) * pageSize)
+  const end = start + pageSize
+  return { content: lines.slice(start, end).join('\n'), page, pageSize, totalLines: lines.length, hasMore: end < lines.length }
+}
+
+/** Strip undefined values so an object satisfies the JsonValue index contract. */
+function structuredToPlain(value: Record<string, unknown>): { [key: string]: JsonValueLike } {
+  const plain: { [key: string]: JsonValueLike } = JSON.parse(JSON.stringify(value)) as { [key: string]: JsonValueLike }
+  return plain
+}
+
+/** Local structural twin of the tool-runtime JsonValue (type-only import). */
+type JsonValueLike = string | number | boolean | null | JsonValueLike[] | { [key: string]: JsonValueLike }
+
+interface ToolRunContextLike {
+  readonly signal: AbortSignal
+}
+
+/** Unwrap the GraphQL envelope for one scope row. */
+function plainScope(envelope: unknown): Record<string, unknown> {
+  const record = envelope as Record<string, unknown>
+  for (const key of ['scope', 'createScope', 'updateScope']) {
+    const inner = record[key]
+    if (typeof inner === 'object' && inner !== null) {
+      const scope = (inner as Record<string, unknown>)['scope']
+      if (typeof scope === 'object' && scope !== null) return scope as Record<string, unknown>
+    }
+  }
+  return record
+}
+
+/** Unwrap a scopes list envelope. */
+function plainScopes(rows: unknown[]): Record<string, unknown>[] {
+  return rows.filter((row): row is Record<string, unknown> => typeof row === 'object' && row !== null)
+}
+
+/** Canonical value of view_request (oneOf the two modes + error). */
+type ViewRequestValue = {
+  readonly kind: 'hits'
+  readonly hits: SearchHit[]
+  readonly total_hits: number
+} | {
+  readonly kind: 'page'
+  readonly content: string
+  readonly page: number
+  readonly page_size: number
+  readonly total_lines: number
+  readonly has_more: boolean
+} | {
+  readonly kind: 'error'
+  readonly error: string
+}
+
+export function apply(ctx: Context, config: Config = {}): void {
+  const scanId = config.scanId ?? 'pentest'
+  const listPageSize = config.listPageSize ?? 50
+  const replayTimeoutMs = config.replayTimeoutMs ?? 30_000
+  const caidoTimeoutMs = config.caidoTimeoutMs ?? 60_000
+  let clientPromise: Promise<CaidoClient> | undefined
+  let warnedNoAllowlist = false
+
+  /** Authorized targets: Config first, else the preset's scan targets. Empty = fail-open (warned once). */
+  const authorizedTargets = (): string[] => {
+    if (config.authorizedTargets !== undefined) return config.authorizedTargets
+    const preset = ctx.get('pentestPreset') as { authorizedTargets?: Array<{ value: string }> } | undefined
+    const values = preset?.authorizedTargets?.map(target => target.value) ?? []
+    if (values.length === 0 && !warnedNoAllowlist) {
+      warnedNoAllowlist = true
+      ctx.logger.warn('pentest-proxy: no authorizedTargets configured; repeat_request target enforcement is inactive (fail-open)')
+    }
+    return values
+  }
+
+  /** Lazy client: resolves the session's Caido bootstrap on first use (strix parity). */
+  const client = (signal: AbortSignal): Promise<CaidoClient> => {
+    // A failed bootstrap stays failed (strix caido_handle parity: every caller
+    // sees the same degraded state); the wording is stable so the model gets
+    // consistent guidance instead of the raw exception.
+    clientPromise ??= (async () => {
+      const session = await ctx.pentestSandbox.createSession({ scanId })
+      const endpoint = await session.caidoEndpoint()
+      return new CaidoClient({ baseUrl: endpoint.baseUrl, token: endpoint.token })
+    })().catch(error => {
+      throw new Error(`Caido client not available in run context: ${String(error instanceof Error ? error.message : error)}`)
+    })
+    const settled = clientPromise
+    if (settled === undefined) throw new Error('unreachable: client promise just assigned')
+    const timeout = new Promise<never>((_resolve, reject) => {
+      signal.addEventListener('abort', () => reject(new Error('caido call aborted')), { once: true })
+      const timer = setTimeout(() => reject(new Error(`caido call timed out after ${String(caidoTimeoutMs)}ms`)), caidoTimeoutMs)
+      void settled.then(() => clearTimeout(timer), () => clearTimeout(timer))
+    })
+    return Promise.race([settled, timeout])
+  }
+
+  if (config.requireApproval !== false) {
+    void ctx.on('tools/pre-execute', async (exec, next) => {
+      if (exec.name === 'repeat_request') return { kind: 'ask' as const, reason: 'pentest: replay a captured request against the target' }
+      return next()
+    })
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'list_requests',
+    description: `List captured HTTP requests from the Caido proxy with HTTPQL filtering. HTTPQL: integer fields (resp.code, req.port, id, roundtrip) use eq/gt/gte/lt/lte/ne e.g. 'resp.code.gte:400'; text fields (req.method, req.host, req.path, req.query, req.ext, req.raw) use regex/cont/eq e.g. 'req.path.cont:"/api/"'; dates use gt/lt with ISO e.g. 'req.created_at.gt:"2024-01-01T00:00:00Z"'; combine with AND/OR; no NOT — use ne/ncont/nregex. String values MUST be quoted, integers MUST NOT. A bare quoted string searches req.raw and resp.raw. Pagination: pass page_info.end_cursor as after.`,
+    parameters: {
+      httpql_filter: { type: 'string', description: 'Caido HTTPQL query (optional).' },
+      first: { type: 'integer', description: `Entries per page (default ${String(listPageSize)}).` },
+      after: { type: 'string', description: "Cursor from a previous response's page_info.end_cursor." },
+      sort_by: { type: 'string', enum: ['timestamp', 'host', 'method', 'path', 'status_code', 'response_time', 'response_size', 'source'], description: 'Sort key (default timestamp).' },
+      sort_order: { type: 'string', enum: ['asc', 'desc'], description: 'Sort order (default desc).' },
+      scope_id: { type: 'string', description: 'Restrict to a Caido scope.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          entries: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } },
+          page_info: { type: 'object', properties: {}, additionalProperties: true },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; entries: unknown[]; error?: string }
+        if (!result.success) return [{ type: 'text', text: `list_requests failed: ${result.error ?? 'unknown'}` }]
+        return [{ type: 'text', text: `${String(result.entries.length)} entries (cursor pagination via page_info)` }]
+      },
+    },
+    execute: async (args, exec) => {
+      try {
+        const caido = await client(exec.signal)
+        const connection = await caido.listRequests({
+          httpqlFilter: args.httpql_filter,
+          first: args.first ?? listPageSize,
+          after: args.after,
+          sortBy: args.sort_by as SortBy | undefined,
+          sortOrder: args.sort_order,
+          scopeId: args.scope_id,
+        }, exec.signal)
+        return {
+          success: true,
+          entries: connection.entries.map(entry => ({
+            cursor: entry.cursor,
+            request: {
+              id: entry.request.id,
+              host: entry.request.host,
+              port: entry.request.port,
+              method: entry.request.method,
+              path: entry.request.path,
+              query: entry.request.query,
+              is_tls: entry.request.tls,
+              created_at: entry.request.createdAt,
+            },
+            response: entry.response === null ? null : {
+              id: entry.response.id,
+              status_code: entry.response.statusCode,
+              length: entry.response.length,
+              created_at: entry.response.createdAt,
+            },
+          })),
+          page_info: {
+            has_next_page: connection.pageInfo.hasNextPage,
+            has_previous_page: connection.pageInfo.hasPreviousPage,
+            start_cursor: connection.pageInfo.startCursor,
+            end_cursor: connection.pageInfo.endCursor,
+          },
+        }
+      } catch (error) {
+        return { success: false, entries: [], page_info: {}, error: String(error instanceof Error ? error.message : error) }
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'view_request',
+    description: `View a captured request or its response raw content, optionally regex-searched. With search_pattern: up to 20 compact hits with before/after context (hunting reflections, leaked URLs, hidden parameters). Without: full content line-paginated (page, page_size). Patterns like '/api/[a-zA-Z0-9._/-]+' (endpoints), 'https?://[^\\s<>"]+' (URLs), '[?&][a-zA-Z0-9_]+=([^&\\s]+)' (query params).`,
+    parameters: {
+      request_id: { type: 'string', required: true, description: 'Request ID from list_requests.' },
+      part: { type: 'string', enum: ['request', 'response'], description: 'Which raw half to view (default request).' },
+      search_pattern: { type: 'string', description: 'Optional regex; switches to compact hits mode.' },
+      page: { type: 'integer', description: '1-indexed page (only without search_pattern).' },
+      page_size: { type: 'integer', description: 'Lines per page (default 50).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          kind: { type: 'string', required: true, enum: ['hits', 'page', 'error'] },
+          hits: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } },
+          total_hits: { type: 'integer' },
+          content: { type: 'string' },
+          page: { type: 'integer' },
+          page_size: { type: 'integer' },
+          total_lines: { type: 'integer' },
+          has_more: { type: 'boolean' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as ViewRequestValue
+        if (result.kind === 'error') return [{ type: 'text', text: `view_request failed: ${result.error}` }]
+        if (result.kind === 'hits') return [{ type: 'text', text: `${String(result.total_hits)} regex hit(s)` }]
+        return [{ type: 'text', text: `page ${String(result.page)}/${String(Math.ceil(result.total_lines / Math.max(1, result.page_size)))} of ${String(result.total_lines)} lines` }]
+      },
+    },
+    execute: async (args, exec) => {
+      try {
+        const caido = await client(exec.signal)
+        const stored = await caido.getRequest(args.request_id, exec.signal)
+        if (stored === null) return { kind: 'error' as const, error: `Request ${args.request_id} not found` }
+        const raw = args.part === 'response' ? stored.responseRaw : stored.requestRaw
+        if (raw === null) return { kind: 'error' as const, error: `No raw ${args.part === 'response' ? 'response' : 'request'} for ${args.request_id}` }
+        if (args.search_pattern !== undefined && args.search_pattern !== '') {
+          const hits = formatSearchHits(raw, args.search_pattern)
+          if (hits.error !== undefined) return { kind: 'error' as const, error: hits.error }
+          return {
+            kind: 'hits' as const,
+            hits: hits.hits.map(hit => ({ match: hit.match, position: hit.position, before: hit.before, after: hit.after })),
+            total_hits: hits.totalHits,
+          }
+        }
+        const textPage = formatTextPage(raw, args.page ?? 1, args.page_size ?? 50)
+        return {
+          kind: 'page' as const,
+          content: textPage.content,
+          page: textPage.page,
+          page_size: textPage.pageSize,
+          total_lines: textPage.totalLines,
+          has_more: textPage.hasMore,
+        }
+      } catch (error) {
+        return { kind: 'error' as const, error: String(error instanceof Error ? error.message : error) }
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'repeat_request',
+    description: `Repeat a captured request, optionally patching fields — the browse→capture→modify→test flow. modifications keys: url (replace), params (query additions), headers (additions), body (replace), cookies (additions). Inherits everything else from the original.`,
+    parameters: {
+      request_id: { type: 'string', required: true, description: 'ID of the original request (from list_requests).' },
+      modifications: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'Replace the URL.' },
+          params: { type: 'object', properties: {}, additionalProperties: true, description: 'Query-string keys to add/update.' },
+          headers: { type: 'object', properties: {}, additionalProperties: true, description: 'Headers to add/update.' },
+          body: { type: 'string', description: 'Replace the body.' },
+          cookies: { type: 'object', properties: {}, additionalProperties: true, description: 'Cookies to add/update.' },
+        },
+        additionalProperties: false,
+        description: 'Patch dict overlaying the original request.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          status: { type: 'string' },
+          session_id: { type: 'string' },
+          elapsed_ms: { type: 'integer' },
+          response: { type: 'object', properties: {}, additionalProperties: true },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; status?: string; error?: string; response?: { status_code?: number } | null }
+        if (!result.success) return [{ type: 'text', text: `repeat_request failed: ${result.error ?? result.status ?? 'unknown'}` }]
+        return [{ type: 'text', text: `replay ${result.status ?? 'DONE'}${result.response?.status_code === undefined ? '' : ` → HTTP ${String(result.response.status_code)}`}` }]
+      },
+    },
+    execute: async (args, exec) => {
+      try {
+        const caido = await client(exec.signal)
+        const stored = await caido.getRequest(args.request_id, exec.signal)
+        if (stored === null) return { success: false, status: 'ERROR', error: `Request ${args.request_id} not found` }
+        // Scope enforcement (beyond strix parity): the replay target must be
+        // inside the authorized target list before anything is dispatched.
+        const allowlist = authorizedTargets()
+        const targetHost = resolveRepeatTargetHost(stored.host, args.modifications as Readonly<Record<string, unknown>> | undefined)
+        if (!targetHostAllowed(targetHost, allowlist)) {
+          return { success: false, status: 'ERROR', error: `repeat_request refused: target host '${targetHost}' is outside this scan's authorized targets` }
+        }
+        const replay = await caido.replayRequest(args.request_id, args.modifications, exec.signal, { dispatchTimeoutMs: replayTimeoutMs, pollIntervalMs: 500 })
+        if (replay === null) return { success: false, status: 'ERROR', error: `Request ${args.request_id} not found` }
+        return {
+          success: replay.status === 'DONE',
+          status: replay.status,
+          session_id: replay.sessionId,
+          elapsed_ms: replay.elapsedMs,
+          response: replay.response === null ? {} : {
+            status_code: replay.response.statusCode,
+            length: replay.response.length,
+            headers: replay.response.headers,
+            body: replay.response.body,
+            body_truncated: replay.response.bodyTruncated,
+          },
+          ...(replay.error !== undefined ? { error: replay.error } : {}),
+        }
+      } catch (error) {
+        return { success: false, status: 'ERROR', error: String(error instanceof Error ? error.message : error) }
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'list_sitemap',
+    description: `Browse Caido's hierarchical sitemap: DOMAIN → DIRECTORY → REQUEST → REQUEST_BODY/REQUEST_QUERY. Start with no parent_id for root domains (optionally scope-filtered); drill in by passing an entry's id as parent_id (depth DIRECT or ALL). Pair with view_sitemap_entry.`,
+    parameters: {
+      scope_id: { type: 'string', description: 'Limit roots to a Caido scope (only without parent_id).' },
+      parent_id: { type: 'string', description: 'Entry ID to expand; omit for root domains.' },
+      depth: { type: 'string', enum: ['DIRECT', 'ALL'], description: 'DIRECT children or the full subtree (default DIRECT).' },
+      page: { type: 'integer', description: '1-indexed page (30 entries per page, strix parity).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          payload: { type: 'object', properties: {}, additionalProperties: true },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'sitemap payload returned' : `list_sitemap failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: async (args, exec) => {
+      try {
+        const caido = await client(exec.signal)
+        const payload = await caido.listSitemap({ scopeId: args.scope_id, parentId: args.parent_id, depth: args.depth }, exec.signal) as Record<string, unknown>
+        return { success: true as const, payload: structuredToPlain(pageSitemapPayload(payload, args.page ?? 1)) }
+      } catch (error) {
+        return { success: false as const, payload: {}, error: String(error instanceof Error ? error.message : error) }
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'scope_rules',
+    description: "Manage Caido scope rules: get/list/create/update/delete. Glob patterns (*, ?, [abc], [a-z], [^abc]); an EMPTY allowlist ALLOWS ALL; the denylist overrides the allowlist. Scopes feed list_requests' scope_id.",
+    parameters: {
+      action: { type: 'string', required: true, enum: ['get', 'list', 'create', 'update', 'delete'], description: 'Scope action.' },
+      allowlist: { type: 'array', items: { type: 'string' }, description: 'Allow glob patterns (create/update).' },
+      denylist: { type: 'array', items: { type: 'string' }, description: 'Deny glob patterns; overrides the allowlist (create/update).' },
+      scope_id: { type: 'string', description: 'Target scope id (get/update/delete).' },
+      scope_name: { type: 'string', description: 'Scope name (create/update).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          scopes: { type: 'array', items: { type: 'object', properties: {}, additionalProperties: true } },
+          scope: { type: 'object', properties: {}, additionalProperties: true },
+          deleted: { type: 'string' },
+          message: { type: 'string' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'scope action succeeded' : `scope_rules failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: (async (rawArgs: never, rawExec: never) => {
+      const args = rawArgs as never as { action: string; allowlist?: string[]; denylist?: string[]; scope_id?: string; scope_name?: string }
+      const exec = rawExec as never as ToolRunContextLike
+      try {
+        const caido = await client(exec.signal)
+        const allowlist = args.allowlist ?? []
+        const denylist = args.denylist ?? []
+        switch (args.action) {
+          case 'list': {
+            const payload = await caido.scopeList(exec.signal) as { scopes?: unknown[] }
+            return { success: true, scopes: plainScopes(payload.scopes ?? []) }
+          }
+          case 'get': {
+            if (args.scope_id === undefined || args.scope_id === '') return { success: false, error: "Scope_id is required for action='get'" }
+            return { success: true, scope: plainScope(await caido.scopeGet(args.scope_id, exec.signal)) }
+          }
+          case 'create': {
+            if (args.scope_name === undefined || args.scope_name === '') return { success: false, error: "Scope_name is required for action='create'" }
+            return { success: true, scope: plainScope(await caido.scopeCreate(args.scope_name, allowlist, denylist, exec.signal)) }
+          }
+          case 'update': {
+            if (args.scope_id === undefined || args.scope_id === '' || args.scope_name === undefined || args.scope_name === '') {
+              return { success: false, error: "Scope_id and scope_name are required for action='update'" }
+            }
+            return { success: true, scope: plainScope(await caido.scopeUpdate(args.scope_id, args.scope_name, allowlist, denylist, exec.signal)) }
+          }
+          case 'delete': {
+            if (args.scope_id === undefined || args.scope_id === '') return { success: false, error: "Scope_id is required for action='delete'" }
+            const payload = await caido.scopeDelete(args.scope_id, exec.signal) as { deleteScope?: { deletedId?: string } }
+            return { success: true, deleted: payload.deleteScope?.deletedId ?? args.scope_id, message: `Scope ${args.scope_id} deleted` }
+          }
+          default:
+            return { success: false, error: `Unknown action: ${String(args.action)}` }
+        }
+      } catch (error) {
+        return { success: false, error: `scope_rules failed: ${String(error instanceof Error ? error.message : error)}` }
+      }
+    }) as never,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'view_sitemap_entry',
+    description: "Full detail for a sitemap entry plus its most recent 30 related requests. Pick entry_id from list_sitemap.",
+    parameters: {
+      entry_id: { type: 'string', required: true, description: 'ID from list_sitemap (or any nested entry).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', required: true },
+          payload: { type: 'object', properties: {}, additionalProperties: true },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        const result = value as { success: boolean; error?: string }
+        return [{ type: 'text', text: result.success ? 'sitemap entry payload returned' : `view_sitemap_entry failed: ${result.error ?? 'unknown'}` }]
+      },
+    },
+    execute: async (args, exec) => {
+      try {
+        const caido = await client(exec.signal)
+        const payload = await caido.viewSitemapEntry(args.entry_id, exec.signal) as Record<string, unknown>
+        return { success: true as const, payload: structuredToPlain(payload) }
+      } catch (error) {
+        return { success: false as const, payload: {}, error: String(error instanceof Error ? error.message : error) }
+      }
+    },
+  }))
+}