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

package/build/lib/core/agents/offSecAgent/tools/spawnPentestSwarm.d.ts

@@ -0,0 +1,52 @@
+import type { ToolContext } from "./types";
+/**
+ * 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 declare function spawnPentestSwarm(ctx: ToolContext): import("ai").Tool<{
+    targets: {
+        target: string;
+        objectives: string[];
+        name?: string | undefined;
+        grpc?: {
+            transport: "grpc" | "grpc_web" | "connect";
+            serviceFqn: string;
+            method: string;
+            streamingType?: "unary" | "server_stream" | "client_stream" | "bidi" | undefined;
+            reflectionAvailable?: boolean | undefined;
+            schemaSource?: "unknown" | "proto" | "reflection" | "protoset" | "js_bundle" | "gateway_derived" | undefined;
+            host?: string | null | undefined;
+            frontingGatewayOperation?: {
+                gatewayType: "rest" | "connect" | "graphql";
+                operation: string;
+            } | null | undefined;
+        } | undefined;
+    }[];
+    toolCallDescription: string;
+}, {
+    success: boolean;
+    message: string;
+    totalTargets?: undefined;
+    totalFindings?: undefined;
+    failedTargets?: undefined;
+    results?: undefined;
+} | {
+    success: boolean;
+    totalTargets: number;
+    totalFindings: number;
+    failedTargets: number;
+    results: {
+        target: string;
+        findingsCount: number;
+        error: string | undefined;
+    }[];
+    message: string;
+}>;

package/build/lib/core/agents/offSecAgent/tools/submitPlan.d.ts

@@ -0,0 +1,12 @@
+import type { ToolContext } from "./types";
+type SubmitPlanResult = {
+    success: boolean;
+    error: string;
+    path: string;
+};
+export declare function submitPlan(ctx: ToolContext & {
+    subagentId?: string;
+}): import("ai").Tool<{
+    toolCallDescription: string;
+}, SubmitPlanResult>;
+export {};

package/build/lib/core/agents/offSecAgent/tools/testEndpointVariations.d.ts

@@ -0,0 +1,34 @@
+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 declare function testEndpointVariations(ctx: ToolContext): import("ai").Tool<{
+    endpoints: string[];
+    toolCallDescription: string;
+    sessionCookie?: string | undefined;
+}, {
+    success: boolean;
+    message: string;
+    totalTested?: undefined;
+    accessible?: undefined;
+    inaccessible?: undefined;
+    results?: undefined;
+    accessibleEndpoints?: undefined;
+} | {
+    success: boolean;
+    totalTested: number;
+    accessible: number;
+    inaccessible: number;
+    results: {
+        endpoint: string;
+        status: number;
+        accessible: boolean;
+        contentLength?: number;
+        error?: string;
+    }[];
+    accessibleEndpoints: string[];
+    message: string;
+}>;

package/build/lib/core/agents/offSecAgent/tools/threatModelGenerator.d.ts

@@ -0,0 +1,32 @@
+import type { EndpointTransport, GrpcEndpointMetadata } from "../../specialized/attackSurface/grpcSchema";
+import type { RiskScore } from "../../specialized/whiteboxAttackSurface";
+import type { ToolContext } from "./types";
+export interface GenerateThreatModelInput {
+    appName: string;
+    routePath: string;
+    method?: string | string[];
+    file?: string;
+    line?: number;
+    handler?: string;
+    authRequired?: boolean;
+    description: string;
+    transport?: EndpointTransport;
+    grpc?: GrpcEndpointMetadata;
+}
+export interface ThreatModelOutput {
+    businessLogic: string;
+    threatModel: string;
+    riskScore: RiskScore;
+    pentestObjectives: string[];
+}
+/**
+ * Spawn a dedicated CodeAgent to produce a business-logic model, threat model,
+ * quantitative risk score, and adversarial test plan for a single endpoint.
+ * All four sections come from one agent pass — the agent reads the source
+ * code once and returns the full structured response.
+ *
+ * The structured `pentestObjectives` objects are flattened to markdown strings
+ * before returning so downstream consumers (apex-adapter, DB) see the existing
+ * `string[]` shape.
+ */
+export declare function generateThreatModelForEndpoint(ctx: ToolContext, input: GenerateThreatModelInput): Promise<ThreatModelOutput | null>;

package/build/lib/core/agents/offSecAgent/tools/toolOutput.d.ts

@@ -0,0 +1,23 @@
+import type { ToolContext } from "./types";
+export declare const TOOL_OUTPUT_MAX_BYTES: number;
+export declare const TOOL_OUTPUT_MAX_LINES = 2000;
+export declare function unavailableToolOutputMessage(err: unknown): string;
+export declare function resolveToolOutput(ctx: ToolContext, reference: string): Promise<string | undefined>;
+export declare function boundedOutputPreview(text: string, marker: string, maxBytes?: number, maxLines?: number): string;
+type TextToolResult = {
+    success: boolean;
+    error: string;
+    command?: string;
+    exitCode?: number;
+    truncated?: boolean;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+};
+export declare function toolOutputForModel<T extends TextToolResult>(ctx: ToolContext, output: T): Promise<{
+    type: "json";
+    value: T;
+} | {
+    type: "text";
+    value: string;
+}>;
+export {};

package/build/lib/core/agents/offSecAgent/tools/types.d.ts

@@ -0,0 +1,215 @@
+import type { LanguageModelMiddleware, StreamTextOnStepFinishCallback, ToolSet } from "ai";
+import type { AIAuthConfig, AIModel, CacheMetrics, OpenAIReasoningEffort, ThinkingEffort, UsageRecorder } from "../../../ai";
+import type { CredentialManager } from "../../../credentials";
+import type { AgentEventBus } from "../../../eventBus";
+import type { AttackSurfaceRegistry } from "../../../findings/attackSurfaceRegistry";
+import type { FindingsRegistry } from "../../../findings/registry";
+import type { PromptInjectionLibrary } from "../../../prompt-injections";
+import type { SessionInfo } from "../../../session";
+import type { SkillsRegistry } from "../../../skills/registry";
+import type { ToolBackends } from "../../../tools/backends/types";
+import type { GrpcPentestContext } from "../../specialized/attackSurface/grpcSchema";
+import type { SubagentSpawner } from "../subagentSpawner";
+import type { StepTraceWriter } from "../trace";
+import type { StreamIdFactory, SystemPentestScope } from "../types";
+import type { CallbackListenerRegistry } from "./callbackListener";
+import type { EmailAdapterResolver } from "./email/adapters";
+import type { PerCommandShell } from "./perCommandShell";
+import type { PlaywrightMcpSession } from "./playwrightMcp";
+import type { UnifiedSandbox } from "./sandbox";
+import type { SmsInbox } from "./smsInbox";
+/**
+ * Shared context passed to every tool factory.
+ *
+ * Each tool receives what it needs from here — session paths,
+ * abort signal, etc. — so individual tool files never import
+ * session or agent internals directly.
+ */
+export type ToolContext = {
+    attackSurfaceArtifactsPath?: string;
+    /** Session providing paths for findings, POCs, logs, scratchpad, etc. */
+    session: SessionInfo;
+    /** The agent's operational working directory. Defaults to session.rootPath. */
+    agentCwd: string;
+    /**
+     * Root that scopes this agent's native file tools (read_file, list_files,
+     * glob, grep, create_file, update_file, delete_file, apply_patch) when they
+     * resolve relative paths and enforce confinement. Only file-tool path
+     * resolution is affected — command cwd and shell/OS permissions are NOT
+     * restricted by this value.
+     */
+    fileWorkspaceRoot?: string;
+    /** The target URL / host — needed by browser tools for context */
+    target?: string;
+    /**
+     * gRPC context when the owning agent's target is a gRPC method. Set on a
+     * pentest orchestrator so `spawn_pentest_agent` forwards it to workers,
+     * which then run the gRPC test battery instead of HTTP-style tests.
+     */
+    grpc?: GrpcPentestContext;
+    /** Structured multi-application scope inherited by spawned pentest workers. */
+    systemScope?: SystemPentestScope;
+    /** Signal to cancel in-flight operations */
+    abortSignal?: AbortSignal;
+    /**
+     * Execution backends for fs / command / http / browser / inbox. Unset means
+     * local execution; hosts inject sandbox-backed implementations.
+     */
+    backends?: ToolBackends;
+    /** AI model — needed by tools that delegate to sub-agents */
+    model?: AIModel;
+    /** Per-provider API key overrides — needed by tools that spawn sub-agents */
+    authConfig?: AIAuthConfig;
+    /** Event bus for streaming agent output and subagent lifecycle events */
+    eventBus?: AgentEventBus;
+    /** Usage callbacks forwarded to sub-agents spawned by tools. */
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    /**
+     * When set, tools like execute_command / http_request / document_vulnerability
+     * route execution through this sandbox instead of running locally.
+     */
+    sandbox?: UnifiedSandbox;
+    /**
+     * Shared findings registry for cross-agent dedup.
+     * When present, `document_vulnerability` checks for duplicates before writing.
+     */
+    findingsRegistry?: FindingsRegistry;
+    /**
+     * Shared attack surface registry for cross-agent asset dedup.
+     * When present, `document_endpoint` checks for duplicates before writing.
+     */
+    attackSurfaceRegistry?: AttackSurfaceRegistry;
+    /**
+     * In-memory credential store. When present, tools can resolve
+     * credential IDs to full secrets without the agent ever seeing them.
+     */
+    credentialManager?: CredentialManager;
+    /** Secret values injected into the shell env; scrubbed from execute_command output. */
+    secretValues?: string[];
+    /**
+     * Shell env this agent runs with. Tools that spawn a sub-agent forward it so
+     * the child's shell resolves the same variables (credential secrets among
+     * them) as the parent's.
+     */
+    environmentVariables?: Record<string, string>;
+    /**
+     * Per-command executor: every invocation runs in a fresh process group
+     * with this agent's working directory and configured environment. Nothing
+     * carries across calls. Only used in local (non-sandbox) mode.
+     */
+    commandShell?: PerCommandShell;
+    /**
+     * Skills registry for on-demand skill loading.
+     * When present, read_skill is available.
+     */
+    skillsRegistry?: SkillsRegistry;
+    /**
+     * Runtime-only prompt-injection payload resolver. Agents receive safe
+     * metadata and IDs; tools resolve raw payloads only during execution.
+     */
+    promptInjectionLibrary?: PromptInjectionLibrary;
+    /**
+     * Local filesystem path for a prompt-injection payload library. When set,
+     * tools load safe metadata and runtime payloads from this source instead of
+     * shipping payloads inside Apex.
+     */
+    promptInjectionLibrarySource?: string;
+    /**
+     * Step trace writer for appending records to trace.jsonl.
+     * When present, checkpoint_state tool is available.
+     */
+    traceWriter?: StepTraceWriter;
+    /**
+     * Per-agent task directory for structured task decomposition.
+     * When present, task tools (create_task, update_task, list_tasks) are available.
+     * Set to `{session.rootPath}/subagents/{subagentId}-tasks/` for subagents.
+     * Only populated when `SessionConfig.taskDriven` is enabled.
+     */
+    tasksDir?: string;
+    /** Enable extended thinking for sub-agents spawned by orchestration tools. */
+    enableThinking?: boolean;
+    /** Adaptive-thinking effort hint for spawned sub-agents (Anthropic 4.6+). */
+    thinkingEffort?: ThinkingEffort | null;
+    /** OpenAI reasoning effort for GPT/o-series sub-agents. */
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    /**
+     * Whitebox attack surface flag. Forwarded into `runPentestWorkflow` so the
+     * orchestrator-driven pentest path honors the user's config / env override.
+     * Defaults to `true` when undefined.
+     */
+    surfaceIntegrationEnabled?: boolean;
+    /**
+     * Project-level threat model content (e.g. from `.pensar/threat_model.md`).
+     * Passed to spawned per-endpoint threat-model sub-agents as additional
+     * context so they can incorporate deployment details, compliance
+     * requirements, or known concerns when analyzing each endpoint.
+     */
+    projectThreatModel?: string;
+    /**
+     * Override for plan file scoping. When set, write_plan uses this ID
+     * instead of `subagentId` to derive the plan file path, allowing
+     * plan agents to write plans scoped to their corresponding execution agent.
+     */
+    planSubagentId?: string;
+    /** Owner subagent id — emitted as `parentSubagentId` on lifecycle events. */
+    subagentId?: string;
+    /**
+     * Playwright MCP browser session for this agent's browser tools.
+     *
+     * When set, `createBrowserToolset` wires its browser tools through this
+     * pre-constructed session instead of spinning up its own MCP
+     * child-process / Chromium. This is how `spawn_pentest_agent` hands a
+     * worker a session that was cloned from the orchestrator's session and
+     * pre-seeded with the orchestrator's cookies + localStorage — the
+     * worker is authenticated for the same origins as the orchestrator but
+     * operates against an isolated Chromium so its actions do not leak back
+     * to the orchestrator or to sibling workers.
+     *
+     * Lifecycle: when this field is set externally, the supplier owns
+     * disconnect (e.g. `spawn_pentest_agent` tears down the worker's
+     * session on completion). When unset, `createBrowserToolset` constructs
+     * its own session and wires `abortSignal` to disconnect.
+     */
+    browserSession?: PlaywrightMcpSession;
+    /**
+     * X display (e.g. `":11"`) the owning agent's browser runs on. Spawn tools
+     * pass it to worker sessions so a spawned worker's browser shares the same
+     * virtual desktop instead of falling back to the process-wide `DISPLAY`.
+     */
+    display?: string;
+    /**
+     * Seam through which orchestration tools spawn sub-agents. Resolved once when
+     * the agent builds its tools (`OffensiveSecurityAgentInput.subagentSpawner` ??
+     * the in-process spawner), so it is always present here and tools never
+     * re-default it; a durable runtime injects one that spawns child workflows
+     * instead. The three durable hooks below are inherited by every child the
+     * spawner constructs.
+     */
+    subagentSpawner: SubagentSpawner;
+    /**
+     * Callback listeners started by this agent's callback helper tools.
+     * The owning agent drains it on run finalization (and after abort), so
+     * listener cleanup stays possible once the run abort signal has fired.
+     * Unset → the callback helper tools refuse to start (ownership-tracked
+     * cleanup is required).
+     */
+    callbackListeners?: CallbackListenerRegistry;
+    /**
+     * Transport for inbound SMS reads. Unset → the Console agent API over HTTP,
+     * which needs sandbox dispatch; a host with direct database access injects
+     * one that reads in-process.
+     */
+    smsInbox?: SmsInbox;
+    /**
+     * Supplies an adapter for an inbox with no transport of its own (a
+     * `pensar-managed` inbox). Unset → the config-driven factory.
+     */
+    emailAdapterFor?: EmailAdapterResolver;
+    /** Provider middleware inherited by spawned children. Unset → raw model. */
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    /** Usage recorder inherited by spawned children. Unset → process-global callback. */
+    usageRecorder?: UsageRecorder;
+    /** Streamed-id factory inherited by spawned children. Unset → random ULIDs. */
+    streamIdFactory?: StreamIdFactory;
+};

package/build/lib/core/agents/offSecAgent/tools/updateFile.d.ts

@@ -0,0 +1,14 @@
+import type { ToolContext } from "./types";
+export type UpdateFileResult = {
+    success: boolean;
+    error: string;
+    path: string;
+    replacements: number;
+};
+export declare function updateFile(ctx: ToolContext): import("ai").Tool<{
+    path: string;
+    oldContent: string;
+    newContent: string;
+    toolCallDescription: string;
+    replaceAll?: boolean | undefined;
+}, UpdateFileResult>;

package/build/lib/core/agents/offSecAgent/tools/updateTask.d.ts

@@ -0,0 +1,20 @@
+import type { ToolContext } from "./types";
+type UpdateTaskResult = {
+    success: boolean;
+    error?: string;
+    task?: {
+        id: number;
+        subject: string;
+        status: string;
+        objective: string;
+        technique: string;
+        result?: string;
+    };
+};
+export declare function updateTask(ctx: ToolContext): import("ai").Tool<{
+    taskId: number;
+    status: "in_progress" | "completed" | "failed";
+    result?: string | undefined;
+    observation?: string | undefined;
+}, UpdateTaskResult>;
+export {};

package/build/lib/core/agents/offSecAgent/tools/validateDiscovery.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Factory for the `validate_discovery_completeness` tool.
+ *
+ * Evaluates recon coverage, computes a confidence score, and
+ * identifies gaps before the final report is generated.
+ */
+export declare function validateDiscovery(_ctx: unknown): import("ai").Tool<{
+    discoveredEndpoints: string[];
+    authenticatedWithCredentials: boolean;
+    pagesWithJSAnalyzed: string[];
+    credentialsFound: boolean;
+    toolCallDescription: string;
+}, {
+    complete: boolean;
+    confidence: number;
+    gaps: {
+        gap: string;
+        severity: string;
+        recommendation: string;
+    }[];
+    summary: string;
+    readyForReport: boolean;
+    message: string;
+}>;

package/build/lib/core/agents/offSecAgent/tools/webSearch.d.ts

@@ -0,0 +1,16 @@
+import type { ToolContext } from "./types";
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export interface WebSearchResponse {
+    success: boolean;
+    results: WebSearchResult[];
+    error?: string;
+}
+export declare function webSearch(_ctx: ToolContext): import("ai").Tool<{
+    query: string;
+    toolCallDescription: string;
+}, WebSearchResponse>;
+export {};

package/build/lib/core/agents/offSecAgent/tools/whiteboxCandidates.d.ts

@@ -0,0 +1,108 @@
+import type { ToolContext } from "./types";
+export declare function createWhiteboxCandidate(ctx: ToolContext): import("ai").Tool<{
+    title: string;
+    vulnerabilityClass: string;
+    summary: string;
+    confidence: "high" | "medium" | "low";
+    toolCallDescription: string;
+    sourceTrace?: {
+        source?: {
+            file: string;
+            line?: number | undefined;
+            symbol?: string | undefined;
+        } | undefined;
+        sink?: {
+            file: string;
+            line?: number | undefined;
+            symbol?: string | undefined;
+        } | undefined;
+        path?: {
+            file: string;
+            line?: number | undefined;
+            symbol?: string | undefined;
+        }[] | undefined;
+        notes?: string | undefined;
+    } | undefined;
+    artifacts?: {
+        path: string;
+        type: "repo-profile" | "static-scan" | "code-query" | "source-trace" | "candidate" | "job-log" | "fuzz-harness" | "fuzz-crash" | "build-log" | "raw-output";
+        description: string;
+    }[] | undefined;
+}, {
+    success: boolean;
+    summary: string;
+    data: {
+        candidate: import("../../../whitebox").WhiteboxCandidate;
+    };
+    artifactPaths: string[];
+    nextActions: string[];
+    truncated: boolean;
+}>;
+export declare function updateWhiteboxCandidate(ctx: ToolContext): import("ai").Tool<{
+    id: string;
+    toolCallDescription: string;
+    state?: "hypothesis" | "investigating" | "repro_attempted" | "confirmed" | "rejected" | "deferred" | undefined;
+    confidence?: "high" | "medium" | "low" | undefined;
+    summary?: string | undefined;
+    artifacts?: {
+        path: string;
+        type: "repo-profile" | "static-scan" | "code-query" | "source-trace" | "candidate" | "job-log" | "fuzz-harness" | "fuzz-crash" | "build-log" | "raw-output";
+        description: string;
+    }[] | undefined;
+    sourceTrace?: {
+        source?: {
+            file: string;
+            line?: number | undefined;
+            symbol?: string | undefined;
+        } | undefined;
+        sink?: {
+            file: string;
+            line?: number | undefined;
+            symbol?: string | undefined;
+        } | undefined;
+        path?: {
+            file: string;
+            line?: number | undefined;
+            symbol?: string | undefined;
+        }[] | undefined;
+        notes?: string | undefined;
+    } | undefined;
+    verification?: {
+        strategy: string;
+        status: "failed" | "not_started" | "running" | "succeeded";
+        notes?: string | undefined;
+    } | undefined;
+}, {
+    success: boolean;
+    summary: string;
+    data: {
+        candidate: import("../../../whitebox").WhiteboxCandidate;
+    };
+    artifactPaths: string[];
+    nextActions: string[];
+    truncated: boolean;
+    recovery?: undefined;
+} | {
+    success: boolean;
+    summary: string;
+    artifactPaths: never[];
+    nextActions: string[];
+    recovery: string;
+    data?: undefined;
+    truncated?: undefined;
+}>;
+export declare function listWhiteboxCandidates(ctx: ToolContext): import("ai").Tool<{
+    toolCallDescription: string;
+    state?: "hypothesis" | "investigating" | "repro_attempted" | "confirmed" | "rejected" | "deferred" | undefined;
+    limit?: number | undefined;
+}, {
+    success: boolean;
+    summary: string;
+    data: {
+        candidates: import("../../../whitebox").WhiteboxCandidate[];
+        total: number;
+    };
+    artifactPaths: string[];
+    nextActions: string[];
+    truncated: boolean;
+}>;