@pensar/apex 2.5.0 → 2.6.1-canary.025b1ecf

package/src/core/agents/offSecAgent/tools/spawnPentestAgent.ts

@@ -0,0 +1,266 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { parseTargetUrl } from "../../../../util/url";
+import { FindingsRegistry } from "../../../findings/registry";
+// Type-only (erased) — the value is constructed inside the spawner registry.
+import type { GrpcPentestContext } from "../../specialized/attackSurface/grpcSchema";
+import type { PentestResult } from "../../specialized/pentest/agent";
+import { assertUrlInScope, ScopeViolationError } from "./scopeGuard";
+import type { ToolContext } from "./types";
+
+// Cap the wait on a finished worker's background drain so it can't hang the slot.
+const WORKER_DRAIN_GRACE_MS = 30_000;
+
+const ORIGIN_AUTH_FAILURE_GUIDANCE = `A 401/403 from one resource does not by itself prove authentication failure. Verify the session against a known protected or session endpoint and re-authenticate on the assigned origin only if needed. Call report_error with reason "authentication_failed" only if required authentication cannot be established and this blocks the assigned objective or all further testing; otherwise continue any reachable testing.`;
+
+/**
+ * Factory for the `spawn_pentest_agent` tool.
+ *
+ * Spawns a single focused {@link TargetedPentestAgent} sub-agent and waits
+ * for it to complete. Unlike `spawn_pentest_swarm` (which fans out N agents
+ * in parallel), this tool dispatches one worker at a time so the parent
+ * orchestrator can react to each result before deciding what to spawn next.
+ *
+ * The spawned worker runs with `role: "worker"` so it never recursively
+ * spawns further pentest sub-agents. It writes findings to the shared
+ * findings registry that the parent / siblings can read.
+ *
+ * Event bus wiring follows the same pattern as `spawn_coding_agent`:
+ *   - A child {@link AgentEventBus} is created for the worker
+ *   - {@link AgentEventBus.attachChild} bubbles the worker's events to the
+ *     parent bus, auto-injecting `subagentId` (and `parentSubagentId` on
+ *     lifecycle events) so console persistence / UI render the worker
+ *     under the right parent
+ *   - `subagent-spawn` and `subagent-complete` lifecycle events are emitted
+ *     directly on the parent bus
+ */
+export function spawnPentestAgent(ctx: ToolContext) {
+  const targetScopeGuidance =
+    ctx.systemScope && ctx.systemScope.memberHosts.length > 0
+      ? `For a cross-service follow-up, you may instead use a full URL on one of these authorized System Scope members: ${ctx.systemScope.memberHosts.join(", ")}.`
+      : "No structured System Scope is present, so keep the assigned host unchanged.";
+
+  return tool({
+    description: `Spawn a single focused pentest sub-agent (worker) to test ONE objective at a time.
+
+Use this AFTER stating your plan and performing light reconnaissance. Call this tool ONCE PER OBJECTIVE — do not batch objectives into a single spawn, because the UI surfaces each spawn as its own timeline.
+
+CRITICAL — \`target\` must be a FULL URL including the endpoint path the caller wants tested (e.g. https://example.com/api/users/{id}), not a bare domain. Use the orchestrator's assigned URL by default. Recon-supported sibling endpoints are allowed for a follow-up objective. ${targetScopeGuidance} Never invent a host or endpoint.
+
+Authentication state is origin-specific. Before spawning a cross-service worker that needs authentication, establish and verify a session on its target origin and describe that status in \`context\`. The worker must verify protected access on its assigned origin. ${ORIGIN_AUTH_FAILURE_GUIDANCE}
+
+Each spawn produces an independent TargetedPentestAgent that:
+1. Tests the assigned objective(s) deeply (execute_command, http_request, browser tools)
+2. Confirms vulnerabilities with POC scripts
+3. Documents findings to the shared findings registry only when the exploit path and material security impact are proven
+
+Cloned browser session — the worker gets its OWN isolated Chromium instance, but it is seeded at spawn time with a snapshot of your current cookies and localStorage. If you've already authenticated in your browser (or recon set up useful state), the worker starts already authenticated for the same origins. Critically, the worker's browser is a COPY: its navigations, form fills, \`localStorage.setItem\`, alerts, and any other browser-side mutations stay inside the worker's own browser and do NOT leak back to you or to sibling workers. If you want state to be visible to the next worker, set it up in YOUR browser before spawning.
+
+The worker has no further spawn capability — it cannot recursively spawn other pentest agents.
+
+After fanning out one worker per objective, call this tool ONE MORE TIME for a final "exploratory" worker. Pass it the URLs of any suspicious behaviors discovered by earlier workers and ask it to chain findings together and probe for additional, unspecified vulnerabilities.
+
+False-positive discipline: workers should not call document_vulnerability for public/unauthenticated behavior, missing best-practice controls, generic errors, local HTTP deployment context, or other low-signal observations unless they prove a material abuse path such as non-public data access, credentialed cross-origin abuse, state change, denial of service, account takeover, or another concrete exploit chain.
+
+Returns the worker's summary, objective results, and finding count — but NOT the findings themselves (those land in the shared registry).`,
+    inputSchema: z.object({
+      name: z
+        .string()
+        .describe(
+          "Short human-readable label for this sub-agent shown in the UI (e.g. 'SQLi /api/users', 'IDOR orders', 'Final chain & explore').",
+        ),
+      target: z
+        .string()
+        .describe(
+          `Full target URL INCLUDING the endpoint path you want this worker to focus on (e.g. 'https://example.com/api/users/{id}', 'https://example.com/login'). Use the orchestrator's assigned URL by default and never strip it to a bare domain. A recon-supported sibling endpoint is allowed when it belongs to the objective. ${targetScopeGuidance} Never invent a host or endpoint.`,
+        ),
+      objectives: z
+        .array(z.string())
+        .min(1)
+        .describe(
+          "Testing objectives for this worker. For per-objective fan-out, pass exactly one objective. For the final exploratory pass, pass a single composite objective describing chaining + exploration.",
+        ),
+      context: z
+        .string()
+        .optional()
+        .describe(
+          "Additional grounding context for the worker — e.g. summaries of what earlier workers found, suspicious endpoints to chain, or application-specific guidance. Treated as guidance, not as code to read.",
+        ),
+      toolCallDescription: z
+        .string()
+        .describe(
+          "Concise, human-readable description of what this spawn is doing (shown in the UI).",
+        ),
+    }),
+    execute: async ({ name, target, objectives, context }, { toolCallId }) => {
+      if (!ctx.model) {
+        return {
+          success: false,
+          message: "spawn_pentest_agent requires a model in the tool context.",
+        };
+      }
+
+      // Fail closed on the child target BEFORE minting a child session id or
+      // emitting `subagent-spawn`. `target` is security-sensitive: it becomes
+      // the child's scope root, so an invalid or out-of-scope value must never
+      // spawn a worker. There is NO fallback/default — we never substitute
+      // localhost, a session target, or any other value for a bad target.
+      if (typeof target !== "string" || parseTargetUrl(target) === null) {
+        return {
+          success: false,
+          message:
+            `spawn_pentest_agent rejected: "target" is not a valid full URL (received ${JSON.stringify(target)}). ` +
+            `Pass a valid full URL authorized by the assigned target or structured System Scope — do NOT invent, default, or substitute a target.`,
+        };
+      }
+
+      // Enforce the PARENT scope against the model-supplied child target. Using
+      // `ctx` (not a context rebased onto `target`) means the child can narrow
+      // to a same-host path or an already-authorized sibling host, but can
+      // never broaden the immutable root/session allowed-host set.
+      try {
+        assertUrlInScope(target, ctx);
+      } catch (error) {
+        if (error instanceof ScopeViolationError) {
+          return { success: false, message: error.message };
+        }
+        throw error;
+      }
+
+      const findingsRegistry =
+        ctx.findingsRegistry ??
+        FindingsRegistry.fromDirectory(ctx.session.findingsPath, {
+          model: ctx.model,
+          authConfig: ctx.authConfig,
+          abortSignal: ctx.abortSignal,
+          sessionId: ctx.session.id,
+        });
+
+      // Share the orchestrator's browser session with the worker instead of
+      // cloning it into a second Camoufox — one Camoufox per endpoint (workers
+      // run one at a time while the orchestrator is blocked on this tool call).
+      // The worker does NOT own the session, so it never disconnects it; the
+      // orchestrator tears it down at run end. Remote-sandbox mode (ctx.sandbox)
+      // has no host session and shares state via the sandbox user-data dir.
+      const sharedBrowserSession = ctx.sandbox ? undefined : ctx.browserSession;
+
+      const enrichedContext = sharedBrowserSession
+        ? buildSharedBrowserSessionContext(context)
+        : context;
+
+      const spawner = ctx.subagentSpawner;
+      let subagentId = "";
+      try {
+        const { findings, objectiveResults } =
+          await spawner.spawn<PentestResult>({
+            spec: {
+              type: "pentest",
+              target,
+              // Inherit the orchestrator's gRPC context ONLY when this worker's
+              // target is the same gRPC method — a sibling/exploratory URL must
+              // not be mis-tested as this method.
+              grpc: workerInheritsGrpc(target, ctx.grpc, ctx.target)
+                ? ctx.grpc
+                : undefined,
+              systemScope: ctx.systemScope,
+              objectives,
+              context: enrichedContext,
+              role: "worker",
+              findingsRegistry,
+              browserSession: sharedBrowserSession,
+            },
+            runtime: {
+              session: ctx.session,
+              model: ctx.model,
+              authConfig: ctx.authConfig,
+              abortSignal: ctx.abortSignal,
+              onStepFinish: ctx.onStepFinish,
+              onCacheMetrics: ctx.onCacheMetrics,
+              sandbox: ctx.sandbox,
+              backends: ctx.backends,
+              display: ctx.display,
+              secretValues: ctx.secretValues,
+              enableThinking: ctx.enableThinking,
+              thinkingEffort: ctx.thinkingEffort,
+              openAIReasoningEffort: ctx.openAIReasoningEffort,
+              languageModelMiddleware: ctx.languageModelMiddleware,
+              usageRecorder: ctx.usageRecorder,
+              streamIdFactory: ctx.streamIdFactory,
+            },
+            parentBus: ctx.eventBus,
+            subagentName: name,
+            lifecycleInput: { target, objectives },
+            parentSubagentId: ctx.subagentId,
+            parentSessionId: ctx.subagentId ?? ctx.session.id,
+            parentToolCallId: toolCallId,
+            stampChildSessionId: true,
+            drainGraceMs: WORKER_DRAIN_GRACE_MS,
+            onSpawned: (id) => {
+              subagentId = id;
+            },
+          });
+
+        return {
+          success: true,
+          subagentId,
+          findingsCount: findings.length,
+          objectiveResults,
+          message: `Worker '${name}' complete. Documented ${findings.length} finding(s).`,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          success: false,
+          subagentId,
+          message: `Worker '${name}' failed: ${message}`,
+        };
+      }
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether a spawned worker should inherit the orchestrator's gRPC
+ * context. Only true when the worker's `target` is the same gRPC method the
+ * orchestrator is testing — either the exact orchestrator target, or a target
+ * carrying the method's wire path `serviceFqn/method`. Sibling or exploratory
+ * targets (plain HTTP, or a different rpc on the same authority) return false
+ * so they are not forced through the gRPC battery for the wrong method.
+ */
+function workerInheritsGrpc(
+  target: string,
+  grpc: GrpcPentestContext | undefined,
+  orchestratorTarget: string | undefined,
+): boolean {
+  if (!grpc) return false;
+  if (orchestratorTarget && target === orchestratorTarget) return true;
+  return target.includes(`${grpc.serviceFqn}/${grpc.method}`);
+}
+
+/**
+ * Inject a "Shared Browser Session" note at the top of the worker's `context`
+ * block so the LLM driving the worker knows it is driving the orchestrator's
+ * live browser (already authenticated) and that its browser-side mutations
+ * persist. Without this hint the worker would either (a) waste turns
+ * re-authenticating from scratch, or (b) wrongly assume its browser state is
+ * throwaway.
+ */
+function buildSharedBrowserSessionContext(
+  existingContext: string | undefined,
+): string {
+  const note = `## Shared Browser Session
+You are driving the orchestrator's live Playwright browser (NOT a private copy):
+- You inherit authentication only for origins where the orchestrator established it. Verify protected access on your assigned origin first. ${ORIGIN_AUTH_FAILURE_GUIDANCE}
+- Only one agent uses this browser at a time — the orchestrator is paused while you run — so you have exclusive control during your run.
+- Your navigations, \`browser_evaluate\` mutations, cookies, and \`localStorage\`/\`sessionStorage\` writes PERSIST in this browser and are visible to the orchestrator and to workers spawned after you. Leave the session in a reasonable state (avoid logging out or wedging the page) when you finish.`;
+
+  if (!existingContext || existingContext.trim().length === 0) {
+    return note;
+  }
+
+  return `${note}\n\n${existingContext}`;
+}

package/src/core/agents/offSecAgent/tools/spawnPentestSwarm.ts

@@ -0,0 +1,146 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { FindingsRegistry } from "../../../findings/registry";
+import { createLogger } from "../../../logger/structured";
+import { scopedLogger } from "../../../util/lazyLogger";
+import { GrpcPentestContextSchema } from "../../specialized/attackSurface/grpcSchema";
+import type { ToolContext } from "./types";
+
+const log = scopedLogger(() => createLogger("spawn-pentest-swarm"));
+
+/**
+ * Factory for the `spawn_pentest_swarm` tool.
+ *
+ * Launches a swarm of {@link TargetedPentestAgent} instances — one per
+ * target/objective pair — and runs them in parallel with bounded
+ * concurrency. Each sub-agent performs deep vulnerability testing
+ * (execute_command, http_request, document_vulnerability) on
+ * its assigned target.
+ *
+ * This is the key orchestration tool for the {@link PentestOrchestrator}:
+ * after recon, it calls this tool to fan-out testing to sub-agents.
+ */
+export function spawnPentestSwarm(ctx: ToolContext) {
+  return tool({
+    description: `Launch a swarm of targeted pentest sub-agents to test multiple targets in parallel.
+
+Call this AFTER completing attack surface discovery. Each entry in 'targets' spawns an independent TargetedPentestAgent that will:
+1. Test the specified target for the given objectives
+2. Create POC scripts for confirmed vulnerabilities
+3. Document findings with evidence and remediation
+
+All findings are written to the shared session directory.
+
+Pass every target you want tested — the swarm handles concurrency automatically.`,
+    inputSchema: z.object({
+      targets: z
+        .array(
+          z.object({
+            name: z
+              .string()
+              .optional()
+              .describe(
+                "Short human-readable label for this agent shown in the UI (e.g. 'SQLi /api/users', 'IDOR orders')",
+              ),
+            target: z
+              .string()
+              .describe("Full target URL including endpoint to test"),
+            objectives: z
+              .array(z.string())
+              .describe(
+                "Testing objectives for this target (e.g., 'Test for SQL injection on /api/users', 'Check IDOR on /api/orders/{id}')",
+              ),
+            grpc: GrpcPentestContextSchema.optional().describe(
+              "gRPC method context for gRPC/Connect targets — pass through the `grpc` object from run_attack_surface so the agent runs the gRPC test battery instead of HTTP tests.",
+            ),
+          }),
+        )
+        .describe("Array of targets with their testing objectives"),
+      toolCallDescription: z
+        .string()
+        .describe(
+          "A concise, human-readable description of what this tool call is doing",
+        ),
+    }),
+    execute: async ({ targets }) => {
+      // Lazy import to break circular dependency:
+      // tools/index.ts → spawnPentestSwarm → pentest.ts → agent classes → tools/index.ts
+      const { runPentestSwarm, DEFAULT_CONCURRENCY } = await import(
+        "../../../workflows/pentest"
+      );
+
+      if (!ctx.model) {
+        return {
+          success: false,
+          message: "spawn_pentest_swarm requires a model in the tool context.",
+        };
+      }
+
+      const findingsRegistry =
+        ctx.findingsRegistry ??
+        FindingsRegistry.fromDirectory(ctx.session.findingsPath, {
+          model: ctx.model!,
+          authConfig: ctx.authConfig,
+          abortSignal: ctx.abortSignal,
+          sessionId: ctx.session.id,
+        });
+
+      const total = targets.length;
+
+      log.info(
+        `Spawning pentest swarm: ${total} agents (concurrency: ${DEFAULT_CONCURRENCY})`,
+      );
+
+      const swarmResults = await runPentestSwarm({
+        targets,
+        model: ctx.model!,
+        session: ctx.session,
+        authConfig: ctx.authConfig,
+        abortSignal: ctx.abortSignal,
+        findingsRegistry,
+        eventBus: ctx.eventBus,
+        onStepFinish: ctx.onStepFinish,
+        onCacheMetrics: ctx.onCacheMetrics,
+        concurrency: DEFAULT_CONCURRENCY,
+        enableThinking: ctx.enableThinking,
+        thinkingEffort: ctx.thinkingEffort,
+        openAIReasoningEffort: ctx.openAIReasoningEffort,
+        display: ctx.display,
+        hooks: {
+          backends: ctx.backends,
+          subagentSpawner: ctx.subagentSpawner,
+          languageModelMiddleware: ctx.languageModelMiddleware,
+          usageRecorder: ctx.usageRecorder,
+          streamIdFactory: ctx.streamIdFactory,
+          smsInbox: ctx.smsInbox,
+          emailAdapterFor: ctx.emailAdapterFor,
+          sandbox: ctx.sandbox,
+        },
+      });
+
+      // Aggregate
+      const totalFindings = swarmResults.reduce(
+        (sum, r) => sum + (r?.findings.length ?? 0),
+        0,
+      );
+      const failedCount = swarmResults.filter((r) => r == null).length;
+
+      return {
+        success: true,
+        totalTargets: total,
+        totalFindings,
+        failedTargets: failedCount,
+        results: targets.map((t, i) => ({
+          target: t.target,
+          findingsCount: swarmResults[i]?.findings.length ?? 0,
+          error: swarmResults[i] == null ? "Agent failed" : undefined,
+        })),
+        message: `Swarm complete. ${totalFindings} findings across ${total} targets. ${
+          failedCount > 0
+            ? `${failedCount} targets failed.`
+            : "All targets tested successfully."
+        }`,
+      };
+    },
+  });
+}

package/src/core/agents/offSecAgent/tools/submitPlan.ts

@@ -0,0 +1,51 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { createLogger } from "../../../logger/structured";
+import { planFilePath, readPlan } from "../../../plan";
+import { scopedLogger } from "../../../util/lazyLogger";
+import type { ToolContext } from "./types";
+
+const log = scopedLogger(() => createLogger("submit_plan"));
+
+const submitPlanInputSchema = z.object({
+  toolCallDescription: z
+    .string()
+    .describe(
+      "A concise, human-readable description of what this tool call is doing (e.g., 'Submitting pentest plan for operator review')",
+    ),
+});
+
+type SubmitPlanResult = {
+  success: boolean;
+  error: string;
+  path: string;
+};
+
+export function submitPlan(ctx: ToolContext & { subagentId?: string }) {
+  return tool({
+    description: `Submit the pentest plan for operator review and approval.
+
+Call this tool AFTER you have written the plan via write_plan. It reads the plan
+from disk and presents it to the operator for approval. The operator can approve,
+reject (sending you back to refine), or edit the plan before approving.
+
+Only call this when the plan is complete and ready for review.`,
+    inputSchema: submitPlanInputSchema,
+    execute: async (): Promise<SubmitPlanResult> => {
+      const scopeId = ctx.planSubagentId ?? ctx.subagentId;
+      const planPath = planFilePath(ctx.session.rootPath, scopeId);
+      log.debug(`enter: path=${planPath}`);
+      const plan = readPlan(ctx.session.rootPath, scopeId);
+      if (!plan?.trim()) {
+        return {
+          success: false,
+          error:
+            "Plan file not found or empty. Write the plan first using write_plan.",
+          path: planPath,
+        };
+      }
+      log.debug(`done: planLen=${plan.length}`);
+      return { success: true, error: "", path: planPath };
+    },
+  });
+}

package/src/core/agents/offSecAgent/tools/testEndpointVariations.ts

@@ -0,0 +1,127 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { resolveBackends } from "../../../tools/backends";
+import type { HttpRequest } from "../../../tools/backends/types";
+import { assertUrlInScope, ScopeViolationError } from "./scopeGuard";
+import type { ToolContext } from "./types";
+
+/**
+ * Factory for the `test_endpoint_variations` tool.
+ *
+ * Tests multiple endpoint URLs for accessibility, useful for
+ * probing authorization issues and mapping live routes.
+ */
+export function testEndpointVariations(ctx: ToolContext) {
+  return tool({
+    description: `Test multiple variations of an endpoint pattern with different parameters.
+
+Use this to:
+- Test an endpoint with multiple IDs to check for authorization issues
+- Test related endpoints that follow similar patterns
+- Systematically probe endpoint variations you've identified`,
+    inputSchema: z.object({
+      endpoints: z.array(z.string()).describe("Array of endpoint URLs to test"),
+      sessionCookie: z
+        .string()
+        .optional()
+        .describe("Session cookie if authentication required"),
+      toolCallDescription: z
+        .string()
+        .describe(
+          "A concise, human-readable description of what this tool call is doing",
+        ),
+    }),
+    execute: async (params) => {
+      try {
+        for (const endpoint of params.endpoints) {
+          assertUrlInScope(endpoint, ctx);
+        }
+      } catch (e) {
+        if (e instanceof ScopeViolationError) {
+          return { success: false, message: e.message };
+        }
+        throw e;
+      }
+
+      const backends = resolveBackends(ctx);
+      try {
+        const { endpoints, sessionCookie } = params;
+
+        const results: Array<{
+          endpoint: string;
+          status: number;
+          accessible: boolean;
+          contentLength?: number;
+          error?: string;
+        }> = [];
+        const accessible: Array<string> = [];
+        const inaccessible: Array<string> = [];
+
+        for (const endpoint of endpoints) {
+          try {
+            const request: HttpRequest = {
+              url: endpoint,
+              method: "GET",
+              followRedirects: true,
+            };
+            if (sessionCookie) {
+              request.headers = { Cookie: sessionCookie };
+            }
+
+            const result = await backends.http.request(request);
+            if (result.status === 0) {
+              results.push({
+                endpoint,
+                status: result.status,
+                accessible: false,
+                error: result.error ?? "Request failed",
+              });
+              inaccessible.push(endpoint);
+              continue;
+            }
+            const body = result.body;
+
+            results.push({
+              endpoint,
+              status: result.status,
+              accessible: result.status >= 200 && result.status < 400,
+              contentLength: body ? body.length : 0,
+            });
+
+            if (result.status >= 200 && result.status < 400) {
+              accessible.push(endpoint);
+            } else {
+              inaccessible.push(endpoint);
+            }
+          } catch (error: unknown) {
+            const errorMsg =
+              error instanceof Error ? error.message : String(error);
+            results.push({
+              endpoint,
+              status: 0,
+              accessible: false,
+              error: errorMsg,
+            });
+            inaccessible.push(endpoint);
+          }
+        }
+
+        return {
+          success: true,
+          totalTested: endpoints.length,
+          accessible: accessible.length,
+          inaccessible: inaccessible.length,
+          results,
+          accessibleEndpoints: accessible,
+          message: `Tested ${endpoints.length} endpoints. ${accessible.length} accessible, ${inaccessible.length} not accessible.`,
+        };
+      } catch (error: unknown) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+          success: false,
+          message: `Endpoint testing error: ${errorMsg}`,
+        };
+      }
+    },
+  });
+}