@pensar/apex 2.5.0 → 2.6.1-canary.0cc77dcc

package/build/lib/core/agents/specialized/attackSurface/grpcSchema.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+export declare const EndpointTransportEnum: z.ZodEnum<{
+    http: "http";
+    grpc: "grpc";
+    grpc_web: "grpc_web";
+    connect: "connect";
+}>;
+export declare const GrpcStreamingTypeEnum: z.ZodEnum<{
+    unary: "unary";
+    server_stream: "server_stream";
+    client_stream: "client_stream";
+    bidi: "bidi";
+}>;
+export declare const GrpcEndpointMetadataSchema: z.ZodObject<{
+    serviceFqn: z.ZodString;
+    method: z.ZodString;
+    streamingType: z.ZodDefault<z.ZodEnum<{
+        unary: "unary";
+        server_stream: "server_stream";
+        client_stream: "client_stream";
+        bidi: "bidi";
+    }>>;
+    reflectionAvailable: z.ZodOptional<z.ZodBoolean>;
+    schemaSource: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        proto: "proto";
+        reflection: "reflection";
+        protoset: "protoset";
+        js_bundle: "js_bundle";
+        gateway_derived: "gateway_derived";
+    }>>;
+    host: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    frontingGatewayOperation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        gatewayType: z.ZodEnum<{
+            rest: "rest";
+            connect: "connect";
+            graphql: "graphql";
+        }>;
+        operation: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type EndpointTransport = z.infer<typeof EndpointTransportEnum>;
+export type GrpcEndpointMetadata = z.infer<typeof GrpcEndpointMetadataSchema>;
+export declare const GrpcPentestContextSchema: z.ZodObject<{
+    transport: z.ZodEnum<{
+        grpc: "grpc";
+        grpc_web: "grpc_web";
+        connect: "connect";
+    }>;
+    serviceFqn: z.ZodString;
+    method: z.ZodString;
+    streamingType: z.ZodOptional<z.ZodEnum<{
+        unary: "unary";
+        server_stream: "server_stream";
+        client_stream: "client_stream";
+        bidi: "bidi";
+    }>>;
+    reflectionAvailable: z.ZodOptional<z.ZodBoolean>;
+    schemaSource: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        proto: "proto";
+        reflection: "reflection";
+        protoset: "protoset";
+        js_bundle: "js_bundle";
+        gateway_derived: "gateway_derived";
+    }>>;
+    host: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    frontingGatewayOperation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        gatewayType: z.ZodEnum<{
+            rest: "rest";
+            connect: "connect";
+            graphql: "graphql";
+        }>;
+        operation: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type GrpcPentestContext = z.infer<typeof GrpcPentestContextSchema>;
+/**
+ * Build a {@link GrpcPentestContext} from an endpoint's `transport` + `grpc`
+ * metadata (as produced by whitebox discovery / `document_endpoint`). Returns
+ * `undefined` for plain HTTP endpoints, so callers can attach the result to a
+ * target unconditionally. When `transport` is a gRPC variant but the `grpc`
+ * object is missing, `serviceFqn` / `method` are derived from the wire `path`
+ * so the target is still tested as gRPC.
+ */
+export declare function toGrpcPentestContext(transport: EndpointTransport | undefined, grpc: GrpcEndpointMetadata | undefined, path?: string): GrpcPentestContext | undefined;
+/**
+ * When a gRPC method's authority (`grpc.host`) differs from the app domain,
+ * build the `grpc://<authority>/<wire-path>` target so the method's real
+ * authority reaches the pentest agent. Returns `undefined` when there is no
+ * host override, so callers fall back to their default target construction.
+ */
+export declare function grpcAuthorityTarget(grpc: GrpcPentestContext | undefined, path: string): string | undefined;

package/build/lib/core/agents/specialized/attackSurface/jsExtraction.d.ts

@@ -0,0 +1,42 @@
+/**
+ * JavaScript endpoint extraction utilities
+ */
+import type { ToolContext } from "../../offSecAgent/tools/types";
+export interface ExtractJavascriptEndpointsParams {
+    url: string;
+    sessionCookie?: string;
+    includeExternalJS?: boolean;
+    /** Routes the page fetch through the caller's tool backend — no bare `fetch`. */
+    ctx: ToolContext;
+}
+export interface EndpointInfo {
+    endpoint: string;
+    pattern: string;
+    source: string;
+}
+export interface ExtractJavascriptEndpointsResult {
+    success: boolean;
+    url?: string;
+    endpoints?: EndpointInfo[];
+    parameterizedPatterns?: string[];
+    totalAjaxCalls?: number;
+    externalJSFiles?: string[];
+    filesAnalyzed?: number;
+    message: string;
+}
+/**
+ * Extract endpoint URLs from JavaScript code in a page using pattern matching.
+ *
+ * Uses regex patterns to find:
+ * - AJAX calls ($.ajax, $.get, $.post)
+ * - Fetch API calls
+ * - Axios requests
+ * - XMLHttpRequest calls
+ * - URL assignments
+ */
+export declare function extractJavascriptEndpoints(params: ExtractJavascriptEndpointsParams): Promise<ExtractJavascriptEndpointsResult>;
+/**
+ * Pure HTML variant of {@link extractJavascriptEndpoints} for callers that
+ * already hold the page body — no second fetch of the page.
+ */
+export declare function extractJavascriptEndpointsFromHtml(html: string, url: string, includeExternalJS?: boolean): ExtractJavascriptEndpointsResult;

package/build/lib/core/agents/specialized/attackSurface/prompts.d.ts

@@ -0,0 +1 @@
+export declare const SYSTEM = "You are an autonomous attack surface analysis agent. Your mission is to comprehensively map the attack surface of a target and produce a structured report of all discovered assets and pentest objectives.\n\nYou operate completely autonomously \u2014 never ask for permission, never wait for user input, never stop prematurely. Execute each phase below in order, make decisions based on findings, and explain your reasoning as you go.\n\n# \u26A0\uFE0F MANDATORY FIRST ACTION \u2014 READ THIS BEFORE DOING ANYTHING ELSE\n\n**If authentication credentials or login instructions are provided in the user prompt, your VERY FIRST tool call MUST be to start the login process. Do NOT run curl, nmap, dig, or any other reconnaissance command first. Log in FIRST, then do everything else.**\n\nThis is non-negotiable. Authenticated discovery reveals far more attack surface than unauthenticated probing. Every command you run before logging in wastes time and misses authenticated endpoints.\n\n# CORE PRINCIPLE\n\n**Discovery only. No exploitation.** You identify assets, endpoints, services, and authentication flows. You do NOT attempt to exploit vulnerabilities \u2014 that is delegated to pentest agents downstream. Focus entirely on breadth of discovery and accurate documentation.\n\n# TARGET SCOPE \u2014 WHAT TO DOCUMENT vs WHAT TO SKIP\n\nYour job is to map the attack surface of the **target application**, not the entire internet. Only document assets that are part of the target's own infrastructure.\n\n**DO document:**\n- The target web application itself and its pages/routes\n- API endpoints served by the target (e.g., /api/users, /api/auth, /graphql)\n- Admin panels or dashboards that are part of the target\n- Subdomains that host the target's own services (if subdomain enumeration is enabled)\n\n**DO NOT document as separate applications or endpoints:**\n- Third-party authentication providers (e.g., WorkOS, Auth0, Okta, Cognito, Firebase Auth) \u2014 these are external services, not part of the target's attack surface\n- CDN or reverse proxy infrastructure (e.g., CloudFront distributions, Cloudflare, Akamai, Fastly) \u2014 these serve the target but are not separate applications\n- Third-party SaaS dependencies (e.g., Stripe, Sentry, Datadog, Analytics)\n- OAuth/OIDC provider endpoints (e.g., authkit.app, accounts.google.com)\n\nWhen you encounter these external services during recon, note them in `keyFindings` as observations (e.g., \"[LOW] Application uses WorkOS for authentication via OAuth/OIDC\") but do NOT call `document_app` or `document_endpoint` for them.\n\n**Two-step documentation:** Use `document_app` first to register each discovered application (web app, API, admin panel), then use `document_endpoint` for each individual endpoint within that application. This enables incremental creation of apps and endpoints.\n\n**Endpoint format:** When documenting endpoints with `document_endpoint`, the `routePath` field should be the HTTP route (e.g., `/api/users`, `/auth/login`, `/dashboard`), NOT a full URL or a source-file path. The target domain is already known. If you discover an endpoint at `https://example.com/api/users`, document it as `/api/users`.\n\n**Method consolidation:** Do NOT create separate endpoints for different HTTP methods on the same path. If `/api/users` accepts GET, POST, and DELETE, document it as ONE endpoint with `method: [\"GET\", \"POST\", \"DELETE\"]` and include pentest objectives that cover all methods. This prevents inflated endpoint counts and ensures pentest agents test the endpoint holistically rather than treating each method as isolated.\n\n# EVIDENCE-BASED FINDINGS \u2014 NO HALLUCINATIONS\n\nEvery discovery MUST come from actual tool output:\n- NEVER report endpoints, subdomains, or status codes without running a command to verify them\n- NEVER infer technology stacks without direct evidence (headers, error pages, fingerprints)\n- If a command returns 404 or no results, do NOT fabricate findings\n- ALWAYS follow ALL redirects (HTTP and client-side) \u2014 document only final destinations\n- If a page returns 200, check for client-side redirects (NEXT_REDIRECT, window.location, meta refresh) before documenting\n\n# PHASE 1 \u2014 AUTHENTICATION (MUST BE FIRST WHEN CREDENTIALS ARE PROVIDED)\n\n**Goal:** Establish an authenticated session so all subsequent discovery sees the full attack surface.\n\n**CRITICAL: When credentials are provided, this phase is your FIRST action. Do not skip ahead to recon.**\n\n## Step 1: Follow provided authentication instructions\n\nIf the user prompt contains `<authentication_instructions>`, follow those instructions exactly. They may specify a custom login flow (API call, specific URL, token exchange, etc.). Execute them now.\n\n## Step 2: If no explicit instructions exist but credentials are provided, perform browser login\n\nYour first tool calls should be exactly this sequence:\n1. `browser_navigate` \u2192 go to the target URL (or the login URL if one was provided in credentials)\n2. `browser_snapshot` \u2192 identify the login form fields and submit button\n3. `browser_screenshot` \u2192 capture the login page before filling credentials\n4. `browser_fill` \u2192 fill the username/email field with the provided username\n5. `browser_fill` \u2192 fill the password field with the provided password\n6. `browser_click` \u2192 click the login/submit button\n7. `browser_snapshot` \u2192 confirm login succeeded (look for dashboard content, user menu, redirect away from /login)\n8. `browser_screenshot` \u2192 capture the post-login state for evidence\n\n## Step 3: After login, extract and save session state\n\n7. `browser_get_cookies` \u2192 capture all session cookies\n8. `browser_evaluate` with `document.cookie` \u2192 backup cookie extraction\n9. Save the cookie values \u2014 you will need to include them as `-b \"cookie=value\"` in curl commands for authenticated recon later\n\n**Only after completing login do you proceed to Phase 2 (or Phase 3 if subdomains are disabled).**\n\n## If NO credentials are provided:\n\n- Skip this phase entirely\n- Proceed directly to Phase 2 (or Phase 3 if subdomains are disabled)\n- Note any login pages you find during discovery as assets and flag them for pentest agents\n\n## Session expiry:\n\nIf you start getting 401/403 on endpoints that previously returned 200, re-authenticate using the same browser login flow. If re-authentication fails on the same endpoint immediately, it is a permissions issue \u2014 document it and move on.\n\n# PHASE 2 \u2014 SUBDOMAIN ENUMERATION\n\n**This phase only runs if subdomain enumeration is ENABLED in the session config.** If disabled, skip entirely and move to Phase 3.\n\n**Goal:** Discover all subdomains of the target domain using command-line techniques.\n\nUse `execute_command` for each technique below:\n\n## 2a. DNS brute-force with dig\n\nQuery common subdomain prefixes against the target domain:\n\n```bash\n# Test subdomains in batch \u2014 verify each resolves\nfor sub in www api admin dev staging test app portal login mail ftp vpn cdn static assets blog docs wiki help support status monitor grafana jenkins git gitlab ci cd beta alpha demo sandbox internal intranet partner shop store api-v1 api-v2 m mobile sso oauth auth accounts dashboard panel manage backup old legacy archive v1 v2 v3 db mysql postgres redis elastic search; do\n  result=$(dig +short \"$sub.DOMAIN\" A 2>/dev/null)\n  if [ -n \"$result\" ]; then\n    echo \"[FOUND] $sub.DOMAIN -> $result\"\n  fi\ndone\n```\n\nSplit into multiple `execute_command` calls if the list is long to avoid timeouts.\n\n## 2b. Certificate transparency logs\n\n```bash\n# Query crt.sh for certificate transparency records\ncurl -s \"https://crt.sh/?q=%25.DOMAIN&output=json\" | jq -r '.[].name_value' 2>/dev/null | sort -u\n```\n\n## 2c. Reverse DNS on discovered IPs\n\n```bash\ndig -x IP_ADDRESS\n```\n\n## 2d. DNS zone transfer attempt\n\n```bash\n# Get nameservers then attempt zone transfer\ndig NS DOMAIN +short | while read ns; do dig axfr @\"$ns\" DOMAIN; done\n```\n\n**For every discovered subdomain:**\n- Resolve it to an IP with `dig +short SUBDOMAIN A`\n- Check if it serves HTTP(S) with `curl -L -I --max-time 5 https://SUBDOMAIN` and `curl -L -I --max-time 5 http://SUBDOMAIN`\n- Document it using `document_app` (for the subdomain as an application)\n\n# PHASE 3 \u2014 ENDPOINT EXTRACTION FROM JAVASCRIPT\n\n**Goal:** Systematically extract API endpoints, routes, and URLs from JavaScript source code.\n\n## 3a. Find JavaScript files\n\n```bash\n# Download the page and extract all JS file URLs\ncurl -s TARGET_URL | grep -oE 'src=\"[^\"]*\\.js[^\"]*\"' | sed 's/src=\"//;s/\"//'\n```\n\nAlso use the browser:\n- `browser_navigate` to the target URL\n- `browser_evaluate` with: `Array.from(document.querySelectorAll('script[src]')).map(s => s.src)`\n\n## 3b. Download and analyze each JS bundle\n\nFor each discovered JS file:\n\n```bash\n# Download the JS file and extract endpoint patterns\ncurl -s JS_FILE_URL | grep -oE '\"(/[a-zA-Z0-9_/-]+)\"' | sort -u\ncurl -s JS_FILE_URL | grep -oE \"'(/[a-zA-Z0-9_/-]+)'\" | sort -u\ncurl -s JS_FILE_URL | grep -oE 'fetch\\(\"[^\"]*\"\\)' | sort -u\ncurl -s JS_FILE_URL | grep -oE 'axios\\.[a-z]+\\(\"[^\"]*\"' | sort -u\ncurl -s JS_FILE_URL | grep -oE '\\$\\.ajax\\({[^}]*url:[^}]*}' | sort -u\n```\n\n## 3c. Extract framework-specific routes via browser\n\nUse `browser_evaluate` to check for:\n\n```javascript\n// Next.js (very common)\nJSON.stringify(window.__NEXT_DATA__)\n\n// React/Redux state\nJSON.stringify(window.__INITIAL_STATE__ || window.__PRELOADED_STATE__)\n\n// Generic API config\nJSON.stringify(window.API_URL || window.API_BASE_URL || window.config || window.ENV)\n\n// All links on the page (including JS-generated)\nArray.from(document.querySelectorAll('a[href]')).map(a => a.href)\n\n// All form actions\nArray.from(document.querySelectorAll('form[action]')).map(f => f.action)\n```\n\n## 3d. Check for API documentation endpoints\n\n```bash\nfor path in /swagger.json /swagger.yaml /openapi.json /openapi.yaml /api-docs /api/docs /docs /swagger-ui /redoc /graphql; do\n  status=$(curl -o /dev/null -s -w \"%{http_code}\" -L --max-time 5 \"TARGET_URL$path\")\n  if [ \"$status\" != \"404\" ] && [ \"$status\" != \"000\" ]; then\n    echo \"[FOUND] $path -> HTTP $status\"\n  fi\ndone\n```\n\nIf swagger/openapi is found, download and parse it for all endpoint paths.\n\n# PHASE 4 \u2014 BROWSER-BASED ATTACK SURFACE DISCOVERY\n\n**Goal:** Use the browser to explore the application as a real user would, discovering attack surface that curl and static analysis miss.\n\n## 4a. Initial page exploration\n\n1. `browser_navigate` to the target URL\n2. `browser_snapshot` to understand the page structure\n3. `browser_screenshot` to document what the main page looks like\n\n## 4b. Navigate key areas\n\nFor each discovered link, admin panel, dashboard, or functional area:\n1. `browser_navigate` to the URL\n2. `browser_snapshot` to identify interactive elements (forms, buttons, inputs)\n3. `browser_screenshot` to capture the page \u2014 a human will review your run, so screenshots provide essential visual evidence of what you found\n4. Look for:\n   - Forms with URL/file/redirect input parameters (SSRF candidates)\n   - File upload forms\n   - Search forms\n   - User profile / settings pages\n   - Admin or management interfaces\n   - API playground or GraphQL explorer pages\n\n## 4c. Extract hidden data from the browser context\n\nUse `browser_evaluate` to probe for:\n```javascript\n// Service worker routes\nnavigator.serviceWorker?.controller ? 'SW active' : 'No SW'\n\n// WebSocket endpoints\nperformance.getEntriesByType('resource').filter(r => r.name.includes('ws://')).map(r => r.name)\n\n// Embedded JSON data (common in SSR apps)\nArray.from(document.querySelectorAll('script[type=\"application/json\"]')).map(s => s.textContent?.substring(0, 200))\n```\n\n## 4d. Check console for leaked information\n\nUse `browser_console` to look for:\n- Leaked API keys or tokens\n- Debug messages referencing internal endpoints\n- Error messages revealing stack traces or internal URLs\n\n## 4e. Collect cookies\n\nUse `browser_get_cookies` to document all cookies set by the application \u2014 note HttpOnly, Secure, and SameSite flags for each.\n\n# PHASE 5 \u2014 ASSET IDENTIFICATION & PENTEST OBJECTIVES\n\n**Goal:** Consolidate all discoveries into documented assets and define pentest objectives for each.\n\n## 5a. Document applications first, then endpoints\n\n**Step 1: Document each application** using `document_app`:\n- `web_application` \u2014 the target web application (usually one per target domain)\n- `api` \u2014 API services hosted by the target (REST, GraphQL, WebSocket)\n- `full_stack` \u2014 applications serving both UI and API (e.g. Next.js, Django with templates)\n- `domain` / `subdomain` \u2014 only subdomains that host the target's own services\n- `database` / `cloud_resource` / `storage` \u2014 owned infrastructure (databases, S3 buckets, etc.)\n\n**Step 2: Document each endpoint** using `document_endpoint`:\n- `api-endpoint` \u2014 individual API routes (e.g., /api/users, /auth/login, /graphql)\n- `web-endpoint` \u2014 web pages and views (e.g., /dashboard, /settings)\n- `asset` \u2014 other discoverable resources\n\nEach `document_endpoint` call MUST specify the `appName` of the parent application.\n\n**DO NOT document external/third-party services** \u2014 only target-owned apps and endpoints.\n\nFor each endpoint, include:\n- HTTP route in `routePath` (e.g., `/api/users`, `/dashboard`) \u2014 this is the URL path, NOT a file path\n- HTTP method(s) in `method` (e.g., `[\"GET\", \"POST\"]`; use `\"PAGE\"` for web pages)\n- Authentication requirements in `authRequired`\n- Risk level (LOW / MEDIUM / HIGH / CRITICAL)\n## 5b. Include authentication info with every target\n\nIf credentials or auth cookies were obtained, include them with every target that requires authentication:\n```\nauthenticationInfo: {\n  method: \"cookie-based session after browser login\",\n  details: \"Navigate to /login, fill username+password, submit form\",\n  credentials: \"user:pass\",\n  cookies: \"session=abc123...\",\n  headers: \"Authorization: Bearer xyz...\"\n}\n```\n\n# PHASE 6 \u2014 GENERATE THE REPORT\n\n**Goal:** Produce the final attack surface report using the `create_attack_surface_report` tool.\n\nBefore calling the tool, verify:\n- [ ] All discovered target-owned subdomains are documented\n- [ ] All discovered target-owned endpoints are documented\n- [ ] All discovered target-owned services and ports are documented\n- [ ] Every target has a specific pentest objective\n- [ ] Authentication info is included with authenticated targets\n- [ ] External/third-party services are NOT documented as assets (mentioned in keyFindings only)\n\nCall `create_attack_surface_report` with:\n\n- **summary**: `{ totalAssets, totalDomains, analysisComplete: true }`\n- **discoveredAssets**: Array of strings, one per asset. Format: `\"asset.example.com - Description (technology) - Ports/services\"`\n- **targets**: Array of objects, each with:\n  - `target`: The URL or host\n  - `objective`: Specific vulnerability classes to test (see table above)\n  - `rationale`: Why this target warrants testing\n- **keyFindings**: Array of strings. Format: `\"[SEVERITY] Description\"`\n\nInclude every target-owned asset and target. Do not summarize or skip assets that belong to the target \u2014 the orchestrator needs the full picture. Do NOT include external/third-party services as assets or targets (mention them in keyFindings instead).\n\nThis tool call MUST be the final action you take.\n\n# TOOL REFERENCE\n\n## execute_command\nRun shell commands for reconnaissance. Use for: dig, curl, nmap, whois, and all command-line recon.\n\n## document_app\nRecord a discovered target-owned application (web app, API, admin panel, subdomain service). Use for top-level application entities.\n\n## document_endpoint\nRecord a discovered endpoint within an application. Must specify `appName` to link to the parent app. For API endpoints, consolidate all HTTP methods on the same path into a single entry using `method` (e.g., `[\"GET\", \"POST\"]`).\n\n## create_attack_surface_report\nSubmit the final structured report. Call this ONCE at the very end with complete results. This ends the run.\n\n## Browser tools\n- `browser_navigate` \u2014 Load a URL in the browser\n- `browser_snapshot` \u2014 Get the page's accessibility tree (structure and interactive elements)\n- `browser_screenshot` \u2014 Capture a screenshot for evidence\n- `browser_click` \u2014 Click an element on the page\n- `browser_fill` \u2014 Fill a form field with a value\n- `browser_evaluate` \u2014 Execute JavaScript in the browser context and return the result\n- `browser_console` \u2014 Retrieve console messages (errors, warnings, debug info)\n- `browser_get_cookies` \u2014 Get all cookies for the current page\n\n# IMPORTANT RULES\n\n1. **Act, don't ask.** Never say \"Would you like me to...\" \u2014 just do it.\n2. **Verify everything.** Every finding must have a command and output backing it.\n3. **Follow redirects.** Use `curl -L -I` and check for client-side redirects before documenting any endpoint.\n4. **Breadth over depth.** Find everything; test nothing deeply.\n5. **Document as you go.** Call `document_app` / `document_endpoint` after every verified target-owned discovery, not in bulk at the end.\n6. **End with the report.** Your final action must be `create_attack_surface_report`.\n7. **No follow-up requests.** The user cannot respond. Do not end with questions or suggestions.\n8. **Screenshot liberally.** A human reviews your run after it completes. Every time you navigate to a new page, submit a form, complete a login step, or discover something notable in the browser, call `browser_screenshot` so the reviewer can see exactly what you saw. Aim for at least one screenshot per distinct page or state change. Screenshots are cheap \u2014 missing visual context is not.\n\nIf resuming from a previous run, review the assets already in the session assets folder and continue where you left off.";

package/build/lib/core/agents/specialized/attackSurface/schemas.d.ts

@@ -0,0 +1,284 @@
+import { z } from "zod";
+import { RiskScoreBreakdownSchema, RiskScoreSchema } from "../whiteboxAttackSurface";
+export type { RiskScore, RiskScoreBreakdown } from "../whiteboxAttackSurface";
+export { RiskScoreBreakdownSchema, RiskScoreSchema };
+/**
+ * Shared schemas for attack surface agent tools.
+ * These schemas are exported for use by external consumers (e.g., Console integration)
+ * to validate and type persistence callbacks without duplicating schema definitions.
+ */
+/**
+ * Risk level enum
+ */
+export declare const RiskLevelEnum: z.ZodEnum<{
+    CRITICAL: "CRITICAL";
+    HIGH: "HIGH";
+    MEDIUM: "MEDIUM";
+    LOW: "LOW";
+}>;
+/**
+ * Schema for pentest target in attack surface report
+ */
+export declare const PentestTargetSchema: z.ZodObject<{
+    target: z.ZodString;
+    objective: z.ZodString;
+    rationale: z.ZodString;
+    authenticationInfo: z.ZodOptional<z.ZodObject<{
+        method: z.ZodString;
+        details: z.ZodString;
+        credentials: z.ZodOptional<z.ZodString>;
+        cookies: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Schema for attack surface summary
+ */
+export declare const AttackSurfaceSummarySchema: z.ZodObject<{
+    totalAssets: z.ZodNumber;
+    totalDomains: z.ZodNumber;
+    analysisComplete: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Schema for create_attack_surface_report tool input
+ */
+export declare const AttackSurfaceReportSchema: z.ZodObject<{
+    summary: z.ZodObject<{
+        totalAssets: z.ZodNumber;
+        totalDomains: z.ZodNumber;
+        analysisComplete: z.ZodBoolean;
+    }, z.core.$strip>;
+    discoveredAssets: z.ZodArray<z.ZodString>;
+    targets: z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        objective: z.ZodString;
+        rationale: z.ZodString;
+        authenticationInfo: z.ZodOptional<z.ZodObject<{
+            method: z.ZodString;
+            details: z.ZodString;
+            credentials: z.ZodOptional<z.ZodString>;
+            cookies: z.ZodOptional<z.ZodString>;
+            headers: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    keyFindings: z.ZodPreprocess<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Application types for document_app tool
+ */
+export declare const AppTypeEnum: z.ZodEnum<{
+    web_application: "web_application";
+    api: "api";
+    full_stack: "full_stack";
+    database: "database";
+    cloud_resource: "cloud_resource";
+    storage: "storage";
+    domain: "domain";
+    subdomain: "subdomain";
+}>;
+/**
+ * Endpoint types for document_endpoint tool
+ */
+export declare const EndpointTypeEnum: z.ZodEnum<{
+    "api-endpoint": "api-endpoint";
+    "web-endpoint": "web-endpoint";
+    asset: "asset";
+}>;
+export type { EndpointTransport, GrpcEndpointMetadata, } from "./grpcSchema";
+export { EndpointTransportEnum, GrpcEndpointMetadataSchema, GrpcStreamingTypeEnum, } from "./grpcSchema";
+/**
+ * Schema for document_app tool input
+ */
+export declare const DocumentAppSchema: z.ZodObject<{
+    appName: z.ZodString;
+    appType: z.ZodEnum<{
+        web_application: "web_application";
+        api: "api";
+        full_stack: "full_stack";
+        database: "database";
+        cloud_resource: "cloud_resource";
+        storage: "storage";
+        domain: "domain";
+        subdomain: "subdomain";
+    }>;
+    description: z.ZodString;
+    framework: z.ZodOptional<z.ZodString>;
+    technology: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Schema for document_app record (includes metadata added during documentation)
+ */
+export declare const DocumentedAppRecordSchema: z.ZodObject<{
+    appName: z.ZodString;
+    appType: z.ZodEnum<{
+        web_application: "web_application";
+        api: "api";
+        full_stack: "full_stack";
+        database: "database";
+        cloud_resource: "cloud_resource";
+        storage: "storage";
+        domain: "domain";
+        subdomain: "subdomain";
+    }>;
+    description: z.ZodString;
+    framework: z.ZodOptional<z.ZodString>;
+    technology: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authentication: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodString>;
+    discoveredAt: z.ZodString;
+    sessionId: z.ZodString;
+    target: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Schema for document_endpoint tool input
+ */
+export declare const DocumentEndpointSchema: z.ZodObject<{
+    appName: z.ZodString;
+    routePath: z.ZodString;
+    endpointType: z.ZodEnum<{
+        "api-endpoint": "api-endpoint";
+        "web-endpoint": "web-endpoint";
+        asset: "asset";
+    }>;
+    transport: z.ZodOptional<z.ZodEnum<{
+        http: "http";
+        grpc: "grpc";
+        grpc_web: "grpc_web";
+        connect: "connect";
+    }>>;
+    grpc: z.ZodOptional<z.ZodObject<{
+        serviceFqn: z.ZodString;
+        method: z.ZodString;
+        streamingType: z.ZodDefault<z.ZodEnum<{
+            unary: "unary";
+            server_stream: "server_stream";
+            client_stream: "client_stream";
+            bidi: "bidi";
+        }>>;
+        reflectionAvailable: z.ZodOptional<z.ZodBoolean>;
+        schemaSource: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            proto: "proto";
+            reflection: "reflection";
+            protoset: "protoset";
+            js_bundle: "js_bundle";
+            gateway_derived: "gateway_derived";
+        }>>;
+        host: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frontingGatewayOperation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            gatewayType: z.ZodEnum<{
+                rest: "rest";
+                connect: "connect";
+                graphql: "graphql";
+            }>;
+            operation: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    description: z.ZodString;
+    method: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    handler: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodNumber>;
+    authRequired: z.ZodOptional<z.ZodBoolean>;
+    authentication: z.ZodOptional<z.ZodString>;
+    riskLevel: z.ZodPreprocess<z.ZodEnum<{
+        CRITICAL: "CRITICAL";
+        HIGH: "HIGH";
+        MEDIUM: "MEDIUM";
+        LOW: "LOW";
+    }>>;
+    notes: z.ZodOptional<z.ZodString>;
+    pentestObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    businessLogic: z.ZodOptional<z.ZodString>;
+    threatModel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Schema for document_endpoint record (includes metadata added during documentation)
+ */
+export declare const DocumentedEndpointRecordSchema: z.ZodObject<{
+    appName: z.ZodString;
+    routePath: z.ZodString;
+    endpointType: z.ZodEnum<{
+        "api-endpoint": "api-endpoint";
+        "web-endpoint": "web-endpoint";
+        asset: "asset";
+    }>;
+    transport: z.ZodOptional<z.ZodEnum<{
+        http: "http";
+        grpc: "grpc";
+        grpc_web: "grpc_web";
+        connect: "connect";
+    }>>;
+    grpc: z.ZodOptional<z.ZodObject<{
+        serviceFqn: z.ZodString;
+        method: z.ZodString;
+        streamingType: z.ZodDefault<z.ZodEnum<{
+            unary: "unary";
+            server_stream: "server_stream";
+            client_stream: "client_stream";
+            bidi: "bidi";
+        }>>;
+        reflectionAvailable: z.ZodOptional<z.ZodBoolean>;
+        schemaSource: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            proto: "proto";
+            reflection: "reflection";
+            protoset: "protoset";
+            js_bundle: "js_bundle";
+            gateway_derived: "gateway_derived";
+        }>>;
+        host: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frontingGatewayOperation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            gatewayType: z.ZodEnum<{
+                rest: "rest";
+                connect: "connect";
+                graphql: "graphql";
+            }>;
+            operation: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    description: z.ZodString;
+    method: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    handler: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodNumber>;
+    authRequired: z.ZodOptional<z.ZodBoolean>;
+    authentication: z.ZodOptional<z.ZodString>;
+    riskLevel: z.ZodPreprocess<z.ZodEnum<{
+        CRITICAL: "CRITICAL";
+        HIGH: "HIGH";
+        MEDIUM: "MEDIUM";
+        LOW: "LOW";
+    }>>;
+    notes: z.ZodOptional<z.ZodString>;
+    pentestObjectives: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    businessLogic: z.ZodOptional<z.ZodString>;
+    threatModel: z.ZodOptional<z.ZodString>;
+    discoveredAt: z.ZodString;
+    sessionId: z.ZodString;
+    target: z.ZodString;
+    riskScore: z.ZodOptional<z.ZodObject<{
+        score: z.ZodNumber;
+        explanation: z.ZodString;
+        breakdown: z.ZodObject<{
+            exposure: z.ZodNumber;
+            dataSensitivity: z.ZodNumber;
+            functionCriticality: z.ZodNumber;
+            securityIndicators: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AppType = z.infer<typeof AppTypeEnum>;
+export type EndpointType = z.infer<typeof EndpointTypeEnum>;
+export type RiskLevel = z.infer<typeof RiskLevelEnum>;
+export type DocumentAppInput = z.infer<typeof DocumentAppSchema>;
+export type DocumentedAppRecord = z.infer<typeof DocumentedAppRecordSchema>;
+export type DocumentEndpointInput = z.infer<typeof DocumentEndpointSchema>;
+export type DocumentedEndpointRecord = z.infer<typeof DocumentedEndpointRecordSchema>;
+export type PentestTarget = z.infer<typeof PentestTargetSchema>;
+export type AttackSurfaceSummary = z.infer<typeof AttackSurfaceSummarySchema>;
+export type AttackSurfaceReport = z.infer<typeof AttackSurfaceReportSchema>;

package/build/lib/core/agents/specialized/attackSurface/schemas.js

@@ -0,0 +1,144 @@
+import"../../../../chunk-7gjdygcx.js";
+import"../../../../chunk-3w05jmk6.js";
+import"../../../../chunk-jdjagvgr.js";
+import"../../../../chunk-2njv7wz3.js";
+import"../../../../chunk-3502z798.js";
+import"../../../../chunk-8vhr65w3.js";
+import"../../../../chunk-g8d2x00m.js";
+import"../../../../chunk-fy3bbbqy.js";
+import"../../../../chunk-mv74mq5n.js";
+import"../../../../chunk-517rf135.js";
+import"../../../../chunk-b8eq85d2.js";
+import"../../../../chunk-02awpt3c.js";
+import"../../../../chunk-f04pr76h.js";
+import"../../../../chunk-t5bt5vn1.js";
+import"../../../../chunk-wr6ke041.js";
+import"../../../../chunk-eb4h4k1f.js";
+import {
+  EndpointTransportEnum2,
+  GrpcStreamingTypeEnum2,
+  GrpcEndpointMetadataSchema2
+} from "../../../../chunk-vx228eeq.js";
+import"../../../../chunk-bx94rwt5.js";
+import"../../../../chunk-ja7j565c.js";
+import"../../../../chunk-3q89v4xv.js";
+import"../../../../chunk-zrbqn62x.js";
+import"../../../../chunk-q5e23acz.js";
+import"../../../../chunk-k5m5rasy.js";
+import {
+  RiskScoreBreakdownSchema2,
+  RiskScoreSchema2
+} from "../../../../chunk-xpfg2fbk.js";
+import"../../../../chunk-vt9spgd1.js";
+
+// src/core/agents/specialized/attackSurface/schemas.ts
+import { z } from "zod";
+var RiskLevelEnum = z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]);
+var PentestTargetSchema = z.object({
+  target: z.string().describe("Target URL, IP, or domain"),
+  objective: z.string().describe("Pentest objective for this target"),
+  rationale: z.string().describe("Why this target needs deep testing"),
+  authenticationInfo: z.object({
+    method: z.string(),
+    details: z.string(),
+    credentials: z.string().optional(),
+    cookies: z.string().optional(),
+    headers: z.string().optional()
+  }).optional()
+});
+var AttackSurfaceSummarySchema = z.object({
+  totalAssets: z.number(),
+  totalDomains: z.number(),
+  analysisComplete: z.boolean()
+});
+var AttackSurfaceReportSchema = z.object({
+  summary: AttackSurfaceSummarySchema.describe("Summary statistics"),
+  discoveredAssets: z.array(z.string()).describe("List of discovered assets with descriptions. Format: 'example.com - Web server (nginx) - Ports 80,443'"),
+  targets: z.array(PentestTargetSchema).describe("ALL targets for deep penetration testing"),
+  keyFindings: z.preprocess((val) => Array.isArray(val) ? val : [val], z.array(z.string()).describe("Key findings from reconnaissance. Format: '[SEVERITY] Finding description'"))
+});
+var AppTypeEnum = z.enum([
+  "web_application",
+  "api",
+  "full_stack",
+  "domain",
+  "subdomain",
+  "database",
+  "cloud_resource",
+  "storage"
+]);
+var EndpointTypeEnum = z.enum([
+  "api-endpoint",
+  "web-endpoint",
+  "asset"
+]);
+var DocumentAppSchema = z.object({
+  appName: z.string().describe("Unique name for the application (e.g., 'Main Web App', 'Admin API', 'api.example.com')"),
+  appType: AppTypeEnum.describe("Type of application discovered"),
+  description: z.string().describe("Detailed description of the application including what it is and why it's relevant"),
+  framework: z.string().optional().describe("Technology framework or stack (e.g., 'Next.js', 'Express + React', 'Django')"),
+  technology: z.array(z.string()).optional().describe("Technology stack (e.g., ['Node.js', 'Express', 'MongoDB'])"),
+  authentication: z.string().optional().describe("Authentication type if known"),
+  notes: z.string().optional().describe("Additional notes or observations"),
+  domain: z.string().optional().describe("Base URL / domain this application is associated with (e.g., 'https://example.com'). " + "Used to map applications to monitored domains. " + "For cloud resources set this to the canonical resource URL " + "(e.g., 'https://bucket-name.s3.amazonaws.com').")
+});
+var DocumentedAppRecordSchema = DocumentAppSchema.extend({
+  discoveredAt: z.string().describe("ISO timestamp when app was discovered"),
+  sessionId: z.string().describe("Session ID where app was discovered"),
+  target: z.string().describe("Target being analyzed when app was found")
+});
+var DocumentEndpointSchema = z.object({
+  appName: z.string().describe("Name of the parent application this endpoint belongs to. " + "Must match the appName used in a prior document_app call."),
+  routePath: z.string().describe("The endpoint's unique identity — its HTTP route or access pattern. " + "This is the URL path a client requests, NOT a source-file path. " + "Examples: '/api/users', '/dashboard', '/auth/login', " + "'/{objectKey}?X-Amz-Signature=...', 'arn:aws:s3:::bucket-name'. " + "For cloud-resource endpoints (endpointType 'asset') use the specific " + "access pattern, not the base domain URL (which is stored on the parent " + "application). The route path is the endpoint's display identity — there " + "is no separate name field."),
+  endpointType: EndpointTypeEnum.describe("Type of endpoint: 'api-endpoint' for REST/GraphQL APIs, " + "'web-endpoint' for pages/views, 'asset' for other resources. " + "A gRPC method is still 'api-endpoint' — set `transport` to mark it gRPC."),
+  transport: EndpointTransportEnum2.optional().describe("Wire transport. Omit or 'http' for normal endpoints. Set 'grpc' " + "(or 'grpc_web' / 'connect') for a gRPC method and populate `grpc`."),
+  grpc: GrpcEndpointMetadataSchema2.optional().describe("gRPC attributes — required when transport is a gRPC variant. Put the " + "wire path '/package.Service/Method' in `routePath`; do not glue on a host."),
+  description: z.string().describe("Detailed description of the endpoint including what it does"),
+  method: z.union([z.string(), z.array(z.string())]).optional().describe("HTTP method(s) supported (e.g., 'GET', 'POST', or ['GET', 'POST', 'DELETE']). " + "Use 'PAGE' for web pages/views."),
+  handler: z.string().optional().describe("Handler function or component name (whitebox analysis)"),
+  file: z.string().optional().describe("Source-code file where this endpoint is defined, e.g. 'src/routes/users.ts'. " + "This is the source-code location, NOT the HTTP route — the HTTP route " + "belongs in 'routePath'."),
+  line: z.number().optional().describe("Line number in the source file (whitebox analysis)"),
+  authRequired: z.boolean().optional().describe("Whether authentication appears to be required"),
+  authentication: z.string().optional().describe("Authentication details if known"),
+  riskLevel: z.preprocess((val) => {
+    if (typeof val === "string") {
+      const upper = val.toUpperCase();
+      if (upper.includes("CRITICAL"))
+        return "CRITICAL";
+      if (upper.includes("HIGH"))
+        return "HIGH";
+      if (upper.includes("MEDIUM"))
+        return "MEDIUM";
+      if (upper.includes("LOW"))
+        return "LOW";
+    }
+    return val;
+  }, RiskLevelEnum).describe("Risk level: LOW-CRITICAL (exposed/sensitive)"),
+  notes: z.string().optional().describe("Additional notes or observations about the endpoint"),
+  pentestObjectives: z.array(z.string()).optional().describe("Flattened markdown strings — one per adversarial test objective — derived from the " + "endpoint analysis. Each objective embeds title, hypothesis, prerequisites, setup, " + "procedure, and success signal in a single block."),
+  businessLogic: z.string().optional().describe("Comprehensive business-logic model describing what the endpoint does, its actors, " + "data flow, invariants, trust boundaries, and analysis gaps."),
+  threatModel: z.string().optional().describe("Comprehensive threat model grounded in the business logic, covering attacker profiles, " + "attack vectors (with entry points, mechanisms, signals, likelihood, and impact), and " + "risk assessment.")
+});
+var DocumentedEndpointRecordSchema = DocumentEndpointSchema.extend({
+  discoveredAt: z.string().describe("ISO timestamp when endpoint was discovered"),
+  sessionId: z.string().describe("Session ID where endpoint was discovered"),
+  target: z.string().describe("Target being analyzed when endpoint was found"),
+  riskScore: RiskScoreSchema2.optional().describe("Computed risk score with breakdown")
+});
+export {
+  AppTypeEnum,
+  AttackSurfaceReportSchema,
+  AttackSurfaceSummarySchema,
+  DocumentAppSchema,
+  DocumentEndpointSchema,
+  DocumentedAppRecordSchema,
+  DocumentedEndpointRecordSchema,
+  EndpointTransportEnum2 as EndpointTransportEnum,
+  EndpointTypeEnum,
+  GrpcEndpointMetadataSchema2 as GrpcEndpointMetadataSchema,
+  GrpcStreamingTypeEnum2 as GrpcStreamingTypeEnum,
+  PentestTargetSchema,
+  RiskLevelEnum,
+  RiskScoreBreakdownSchema2 as RiskScoreBreakdownSchema,
+  RiskScoreSchema2 as RiskScoreSchema
+};

package/build/lib/core/agents/specialized/attackSurface/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Type definitions for Attack Surface Analysis results
+ * These types match the simplified answer tool schema
+ */
+export interface AttackSurfaceAnalysisResults {
+    summary: AttackSurfaceSummary;
+    discoveredAssets: string[];
+    targets: PentestTarget[];
+    keyFindings: string[];
+}
+export interface AttackSurfaceSummary {
+    totalAssets: number;
+    totalDomains: number;
+    highValueTargets: number;
+    analysisComplete: boolean;
+}
+export interface PentestTarget {
+    target: string;
+    objective: string;
+    rationale: string;
+    authenticationInfo?: {
+        method: string;
+        details: string;
+        credentials?: string;
+        cookies?: string;
+        headers?: string;
+    };
+}
+/**
+ * Helper function to load attack surface results from a session
+ */
+export declare function loadAttackSurfaceResults(resultsPath: string): AttackSurfaceAnalysisResults;