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

package/src/core/api/attackSurface.ts

@@ -0,0 +1,89 @@
+import {
+  type AttackSurfaceAgentInput,
+  type AttackSurfaceResult,
+  BlackboxAttackSurfaceAgent,
+} from "../agents/specialized/attackSurface/blackboxAgent";
+import type { WhiteboxAttackSurfaceResult } from "../agents/specialized/whiteboxAttackSurface";
+import { runWhiteboxAttackSurfaceWorkflow } from "../workflows/whiteboxAttackSurface";
+
+// ---------------------------------------------------------------------------
+// Unified input — accepts both blackbox and whitebox configurations
+// ---------------------------------------------------------------------------
+
+export type AttackSurfaceInput = AttackSurfaceAgentInput;
+
+// ---------------------------------------------------------------------------
+// Convenience runners
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the appropriate attack surface agent based on the input.
+ *
+ * - If `cwd` is provided, runs the **whitebox** agent which analyzes
+ *   source code directly to map endpoints and pages.
+ * - Otherwise, runs the **blackbox** agent which probes a live target
+ *   from the outside.
+ *
+ * `target` is always required (the live URL to test against).
+ */
+export async function runAttackSurfaceAgent(
+  input: AttackSurfaceAgentInput,
+): Promise<AttackSurfaceResult | WhiteboxAttackSurfaceResult> {
+  const isWhitebox = "cwd" in input && !!input.cwd;
+
+  if (isWhitebox) {
+    return runWhiteboxAttackSurface(
+      input as AttackSurfaceAgentInput & { cwd: string },
+    );
+  }
+
+  return runBlackboxAttackSurface(input);
+}
+
+// ---------------------------------------------------------------------------
+// Blackbox (live target probing)
+// ---------------------------------------------------------------------------
+
+async function runBlackboxAttackSurface(
+  input: AttackSurfaceAgentInput,
+): Promise<AttackSurfaceResult> {
+  const agent = new BlackboxAttackSurfaceAgent(input);
+
+  const { results, targets, resultsPath, assetsPath } = await agent.consume();
+
+  console.log(`\nIdentified ${targets.length} targets for deep testing`);
+  console.log(`Results: ${resultsPath}`);
+  console.log(`Assets: ${assetsPath}`);
+
+  return { results, targets, resultsPath, assetsPath };
+}
+
+// ---------------------------------------------------------------------------
+// Whitebox (source code analysis)
+// ---------------------------------------------------------------------------
+
+async function runWhiteboxAttackSurface(
+  input: AttackSurfaceAgentInput & { cwd: string },
+): Promise<WhiteboxAttackSurfaceResult> {
+  const result = await runWhiteboxAttackSurfaceWorkflow({
+    codebasePath: input.cwd,
+    model: input.model,
+    session: input.session,
+    authConfig: input.authConfig,
+    abortSignal: input.abortSignal,
+    attackSurfaceRegistry: input.attackSurfaceRegistry,
+    eventBus: input.eventBus,
+    surfaceIntegrationEnabled: input.surfaceIntegrationEnabled,
+    enableThinking: input.enableThinking,
+    thinkingEffort: input.thinkingEffort,
+    openAIReasoningEffort: input.openAIReasoningEffort,
+  });
+
+  console.log(
+    `\nWhitebox analysis complete: ${result.summary.totalApps} apps, ` +
+      `${result.summary.totalApiEndpoints} API endpoints, ` +
+      `${result.summary.totalPages} pages`,
+  );
+
+  return result;
+}

package/src/core/api/authentication.ts

@@ -0,0 +1,8 @@
+import {
+  runAuthenticationAgent as _runAuthAgent,
+  type AuthenticationAgentInput,
+} from "../agents/specialized/authenticationAgent/agent";
+
+// Re-export from the canonical location
+export const runAuthenticationAgent = _runAuthAgent;
+export type { AuthenticationAgentInput };

package/src/core/api/benchmark.ts

@@ -0,0 +1,35 @@
+import {
+  BenchmarkComparisonAgent,
+  type BenchmarkComparisonAgentInput,
+} from "../agents/specialized/benchmarkComparisonAgent";
+// ---------------------------------------------------------------------------
+// Convenience runner
+// ---------------------------------------------------------------------------
+
+export async function runBenchmarkComparisonAgent(
+  input: BenchmarkComparisonAgentInput,
+) {
+  const agent = new BenchmarkComparisonAgent(input);
+
+  agent.eventBus.on("text-delta", (d) => process.stdout.write(d.text));
+  agent.eventBus.on("tool-call-complete", (d) =>
+    console.log(`→ calling ${d.toolName}`),
+  );
+  agent.eventBus.on("tool-result", (d) =>
+    console.log(`✓ ${d.toolName} completed`),
+  );
+  agent.eventBus.on("error", (d) => console.error("Agent error:", d.error));
+
+  const { comparison, resultsPath } = await agent.consume();
+
+  if (comparison) {
+    console.log(
+      `\nComparison: ${comparison.matched.length}/${comparison.totalExpected} matched, ` +
+        `Precision: ${Math.round(comparison.precision * 100)}%, ` +
+        `Recall: ${Math.round(comparison.recall * 100)}%`,
+    );
+  }
+  console.log(`Results: ${resultsPath}`);
+
+  return { comparison, resultsPath };
+}

package/src/core/api/blackboxPentest.test.ts

@@ -0,0 +1,89 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionInfo } from "../session";
+import {
+  readExecutionMetrics,
+  writeExecutionMetrics,
+} from "../session/execution-metrics";
+import type { PentestWorkflowInput } from "../workflows/pentest";
+
+const mocks = vi.hoisted(() => ({
+  runPentestWorkflow: vi.fn(),
+}));
+
+vi.mock("../workflows/pentest", () => ({
+  runPentestWorkflow: mocks.runPentestWorkflow,
+}));
+
+import { runPentestAgent } from "./blackboxPentest";
+
+let rootPath: string;
+
+beforeEach(() => {
+  rootPath = mkdtempSync(join(tmpdir(), "headless-pentest-usage-"));
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  mocks.runPentestWorkflow.mockImplementation(
+    async (input: PentestWorkflowInput) => {
+      await input.onStepFinish?.({
+        usage: {
+          inputTokens: 100,
+          outputTokens: 20,
+          inputTokenDetails: { cacheReadTokens: 80, cacheWriteTokens: 10 },
+        },
+      } as Parameters<NonNullable<PentestWorkflowInput["onStepFinish"]>>[0]);
+      return {
+        findings: [],
+        findingsPath: join(rootPath, "findings"),
+        pocsPath: join(rootPath, "pocs"),
+        reportPath: null,
+      };
+    },
+  );
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  mocks.runPentestWorkflow.mockReset();
+  rmSync(rootPath, { recursive: true, force: true });
+});
+
+describe("runPentestAgent usage persistence", () => {
+  it("persists headless step and cache usage without clobbering prior totals", async () => {
+    writeExecutionMetrics({
+      sessionRootPath: rootPath,
+      tokenUsage: {
+        inputTokens: 10,
+        outputTokens: 2,
+        cacheReadTokens: 5,
+      },
+    });
+
+    const session = {
+      id: "ses_headless",
+      version: "test",
+      targets: ["https://example.com"],
+      time: { created: 0, updated: 0 },
+      rootPath,
+      logsPath: join(rootPath, "logs"),
+      findingsPath: join(rootPath, "findings"),
+      scratchpadPath: join(rootPath, "scratchpad"),
+      pocsPath: join(rootPath, "pocs"),
+    } as SessionInfo;
+
+    await runPentestAgent({
+      target: "https://example.com",
+      model: {} as PentestWorkflowInput["model"],
+      session,
+    });
+
+    expect(readExecutionMetrics(rootPath)?.tokenUsage).toEqual({
+      inputTokens: 110,
+      outputTokens: 22,
+      cacheReadTokens: 85,
+      cacheWriteTokens: 10,
+      totalTokens: 132,
+    });
+  });
+});

package/src/core/api/blackboxPentest.ts

@@ -0,0 +1,64 @@
+//
+
+import { normalizeStepUsage } from "../ai";
+import {
+  readExecutionMetrics,
+  writeExecutionMetrics,
+} from "../session/execution-metrics";
+import {
+  accumulateSessionTokens,
+  EMPTY_SESSION_TOKEN_USAGE,
+} from "../session/usage";
+import {
+  type PentestWorkflowInput,
+  type PentestWorkflowResult,
+  runPentestWorkflow,
+} from "../workflows/pentest";
+
+// ---------------------------------------------------------------------------
+// Convenience runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the deterministic pentest workflow (blackbox or whitebox based on input).
+ *
+ * - Provide `target` for blackbox testing against a live service
+ * - Provide `cwd` for whitebox testing against a local codebase
+ *
+ * Phase 1: Runs attack surface discovery (whitebox workflow or blackbox agent)
+ * Phase 2: Spawns targeted pentest agents for each discovered target
+ */
+export async function runPentestAgent(
+  input: PentestWorkflowInput,
+): Promise<PentestWorkflowResult> {
+  const persisted = readExecutionMetrics(input.session.rootPath)?.tokenUsage;
+  let tokenUsage = persisted ?? EMPTY_SESSION_TOKEN_USAGE;
+
+  const onStepFinish: PentestWorkflowInput["onStepFinish"] = async (event) => {
+    tokenUsage = accumulateSessionTokens(tokenUsage, normalizeStepUsage(event));
+    await input.onStepFinish?.(event);
+  };
+
+  let result: PentestWorkflowResult;
+  try {
+    result = await runPentestWorkflow({
+      ...input,
+      onStepFinish,
+      onCacheMetrics: input.onCacheMetrics,
+    });
+  } finally {
+    writeExecutionMetrics({
+      sessionRootPath: input.session.rootPath,
+      tokenUsage,
+    });
+  }
+
+  const { findings, findingsPath, pocsPath, reportPath } = result;
+
+  console.log(`\nFound ${findings.length} vulnerabilities`);
+  console.log(`Findings: ${findingsPath}`);
+  console.log(`POCs: ${pocsPath}`);
+  if (reportPath) console.log(`Report: ${reportPath}`);
+
+  return { findings, findingsPath, pocsPath, reportPath };
+}

package/src/core/api/clientIdentity.test.ts

@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../installation", () => ({ getCurrentVersion: () => "1.4.2" }));
+
+import {
+  CLIENT_HEADERS,
+  clientIdentityHeaders,
+  getCurrentCommand,
+  setCurrentCommand,
+} from "./clientIdentity";
+
+beforeEach(() => {
+  setCurrentCommand(undefined);
+});
+
+describe("clientIdentityHeaders", () => {
+  it("names the client and its version on every request", () => {
+    expect(clientIdentityHeaders()).toEqual({
+      [CLIENT_HEADERS.client]: "cli",
+      [CLIENT_HEADERS.version]: "1.4.2",
+    });
+  });
+
+  it("includes the command once the router has set one", () => {
+    setCurrentCommand("pentests");
+    expect(clientIdentityHeaders()[CLIENT_HEADERS.command]).toBe("pentests");
+  });
+
+  it("omits the command header entirely when there is none", () => {
+    expect(clientIdentityHeaders()).not.toHaveProperty(CLIENT_HEADERS.command);
+  });
+});
+
+describe("setCurrentCommand", () => {
+  it("normalizes case and surrounding whitespace", () => {
+    setCurrentCommand("  Issues  ");
+    expect(getCurrentCommand()).toBe("issues");
+  });
+
+  // Console drops anything that is not a short lowercase identifier, so sending
+  // it would be noise. The router passes raw argv, which can be anything.
+  it("drops a command Console would reject rather than sending it", () => {
+    for (const raw of [
+      "a".repeat(64),
+      "--prompt",
+      "issues list",
+      "../traversal",
+      "https://example.com",
+      "",
+    ]) {
+      setCurrentCommand(raw);
+      expect(getCurrentCommand()).toBeUndefined();
+    }
+  });
+
+  it("clears a previously set command when given nothing", () => {
+    setCurrentCommand("issues");
+    setCurrentCommand(undefined);
+    expect(getCurrentCommand()).toBeUndefined();
+  });
+});

package/src/core/api/clientIdentity.ts

@@ -0,0 +1,57 @@
+/**
+ * How this client identifies itself to the Pensar Console API.
+ *
+ * The API is reachable by the CLI, CI jobs, curl and customer automation with
+ * the same credentials, and the credential says nothing about the client. So we
+ * say who we are on every request; a caller that says nothing is recorded as a
+ * generic API caller rather than being assumed to be the CLI.
+ *
+ * Console parses these in `packages/functions/src/callerClient.ts` and only
+ * honours a known client name and a bounded command, so keep the names in step
+ * and keep the command a short identifier, never free text.
+ */
+import { getCurrentVersion } from "../installation";
+
+export const CLIENT_HEADERS = {
+  client: "X-Pensar-Client",
+  version: "X-Pensar-Client-Version",
+  command: "X-Pensar-Command",
+} as const;
+
+/** What this binary is, from Console's point of view. */
+const CLIENT_NAME = "cli";
+
+// The top-level command, set once by the CLI router. Deliberately not the
+// subcommand: Console already records the endpoint each request hits, so
+// `pentests` here plus `POST /pentests` there gives the same resolution
+// without threading a name through every API function.
+let currentCommand: string | undefined;
+
+/** Record the command being run. Called once, by the CLI entrypoint. */
+export function setCurrentCommand(command: string | undefined): void {
+  currentCommand = normalizeCommand(command);
+}
+
+export function getCurrentCommand(): string | undefined {
+  return currentCommand;
+}
+
+// Console drops anything that is not a short lowercase identifier, so send
+// nothing rather than something it will discard.
+const COMMAND_SHAPE = /^[a-z][a-z0-9-]{0,31}$/;
+
+function normalizeCommand(command: string | undefined): string | undefined {
+  if (!command) return undefined;
+  const trimmed = command.trim().toLowerCase();
+  return COMMAND_SHAPE.test(trimmed) ? trimmed : undefined;
+}
+
+/** Client identification headers for a Console API request. */
+export function clientIdentityHeaders(): Record<string, string> {
+  const command = getCurrentCommand();
+  return {
+    [CLIENT_HEADERS.client]: CLIENT_NAME,
+    [CLIENT_HEADERS.version]: getCurrentVersion(),
+    ...(command ? { [CLIENT_HEADERS.command]: command } : {}),
+  };
+}

package/src/core/api/comments.test.ts

@@ -0,0 +1,69 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const apiRequest = vi.hoisted(() => vi.fn());
+
+vi.mock("./apiClient", () => ({ apiRequest }));
+
+import { createIssueComment, listIssueComments } from "./issues";
+
+const ISSUE_ID = "11111111-1111-1111-1111-111111111111";
+
+describe("listIssueComments", () => {
+  beforeEach(() => {
+    apiRequest.mockReset();
+    apiRequest.mockResolvedValue({ comments: [], pagination: {} });
+  });
+
+  it("GETs the issue's comment sub-resource", async () => {
+    await listIssueComments(ISSUE_ID);
+
+    expect(apiRequest).toHaveBeenCalledWith(
+      "GET",
+      `/issues/${ISSUE_ID}/comments`,
+    );
+  });
+
+  it("accepts a label in place of a uuid", async () => {
+    await listIssueComments("VULN-000123");
+
+    expect(apiRequest).toHaveBeenCalledWith(
+      "GET",
+      "/issues/VULN-000123/comments",
+    );
+  });
+
+  it("passes pagination through as query params", async () => {
+    await listIssueComments(ISSUE_ID, { page: 2, pageSize: 10 });
+
+    expect(apiRequest).toHaveBeenCalledWith(
+      "GET",
+      `/issues/${ISSUE_ID}/comments?page=2&pageSize=10`,
+    );
+  });
+
+  it("omits the query string entirely when no options are given", async () => {
+    await listIssueComments(ISSUE_ID, {});
+
+    expect(apiRequest).toHaveBeenCalledWith(
+      "GET",
+      `/issues/${ISSUE_ID}/comments`,
+    );
+  });
+});
+
+describe("createIssueComment", () => {
+  beforeEach(() => {
+    apiRequest.mockReset();
+    apiRequest.mockResolvedValue({ id: "c1" });
+  });
+
+  it("POSTs the body to the issue's comment sub-resource", async () => {
+    await createIssueComment(ISSUE_ID, "Rescored to 7.1");
+
+    expect(apiRequest).toHaveBeenCalledWith(
+      "POST",
+      `/issues/${ISSUE_ID}/comments`,
+      { body: "Rescored to 7.1" },
+    );
+  });
+});

package/src/core/api/constants.ts

@@ -0,0 +1,15 @@
+export const PENSAR_API_BASE_URL = "https://api.pensar.dev";
+const PENSAR_GATEWAY_BASE_URL = "https://gateway.pensar.dev";
+export const PENSAR_CONSOLE_BASE_URL = "https://console.pensar.dev";
+
+export function getPensarApiUrl(): string {
+  return process.env.PENSAR_API_URL || PENSAR_API_BASE_URL;
+}
+
+export function getPensarGatewayUrl(): string {
+  return process.env.PENSAR_GATEWAY_URL || PENSAR_GATEWAY_BASE_URL;
+}
+
+export function getPensarConsoleUrl(): string {
+  return process.env.PENSAR_CONSOLE_URL || PENSAR_CONSOLE_BASE_URL;
+}

package/src/core/api/domains.test.ts

@@ -0,0 +1,35 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const apiRequest = vi.hoisted(() => vi.fn());
+
+vi.mock("./apiClient", () => ({ apiRequest }));
+
+import { createDomain, listDomains } from "./domains";
+
+describe("domains API", () => {
+  beforeEach(() => {
+    apiRequest.mockReset();
+  });
+
+  it("lists domains in the authenticated workspace", async () => {
+    apiRequest.mockResolvedValue({ domains: [] });
+
+    await listDomains();
+
+    expect(apiRequest).toHaveBeenCalledWith("GET", "/domains");
+  });
+
+  it("creates or resolves a canonical workspace domain", async () => {
+    apiRequest.mockResolvedValue({
+      id: "domain-1",
+      url: "https://example.com",
+      verified: false,
+    });
+
+    await createDomain({ url: "example.com" });
+
+    expect(apiRequest).toHaveBeenCalledWith("POST", "/domains", {
+      url: "example.com",
+    });
+  });
+});

package/src/core/api/domains.ts

@@ -0,0 +1,32 @@
+/**
+ * REST API client for workspace-scoped Pensar domains.
+ *
+ * API-created domains are canonicalized and created idempotently by Console.
+ * They remain unverified and do not start reconnaissance.
+ */
+
+import { apiRequest } from "./apiClient";
+
+export interface DomainSummary {
+  id: string;
+  url: string;
+  verified: boolean;
+}
+
+export interface ListDomainsResult {
+  domains: DomainSummary[];
+}
+
+export interface CreateDomainInput {
+  url: string;
+}
+
+export async function listDomains(): Promise<ListDomainsResult> {
+  return apiRequest<ListDomainsResult>("GET", "/domains");
+}
+
+export async function createDomain(
+  data: CreateDomainInput,
+): Promise<DomainSummary> {
+  return apiRequest<DomainSummary>("POST", "/domains", data);
+}

package/src/core/api/environment.ts

@@ -0,0 +1,47 @@
+import { EnvironmentAgent } from "../agents/specialized/environment/agent";
+import type {
+  EnvironmentAgentInput,
+  EnvironmentResult,
+} from "../agents/specialized/environment/types";
+
+export type { EnvironmentAgentInput, EnvironmentResult };
+
+function attachDefaultEnvironmentStreamListeners(
+  agent: EnvironmentAgent,
+): void {
+  agent.eventBus.on("text-delta", (e) => {
+    process.stdout.write(e.text);
+  });
+  agent.eventBus.on("tool-call-complete", (e) => {
+    console.log(`→ calling ${e.toolName}`);
+  });
+  agent.eventBus.on("tool-result", (e) => {
+    console.log(`✓ ${e.toolName} completed`);
+  });
+  agent.eventBus.on("error", (e) => {
+    console.error("Environment agent error:", e.error);
+  });
+}
+
+/**
+ * Run the environment agent to set up a development environment in a sandbox.
+ *
+ * The agent reads project files, starts services, and validates the
+ * environment is healthy. When a sandbox is provided in the input,
+ * tools automatically route operations through it.
+ *
+ * When no `eventBus` is passed on the input, default stdout / console
+ * listeners are attached to the agent's bus for local CLI use.
+ *
+ * @returns Structured result with application URL, status, steps taken,
+ *          and authentication details.
+ */
+export async function runEnvironmentAgent(
+  input: EnvironmentAgentInput,
+): Promise<EnvironmentResult> {
+  const agent = new EnvironmentAgent(input);
+  if (!input.eventBus) {
+    attachDefaultEnvironmentStreamListeners(agent);
+  }
+  return agent.consume();
+}