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

package/src/core/agents/specialized/attackSurface/blackboxAgent.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { CredentialManager } from "../../../credentials";
+import type { SessionInfo } from "../../../session";
+import { buildBlackboxPrompt } from "./blackboxAgent";
+
+describe("buildBlackboxPrompt", () => {
+  it("guides SMS MFA without exposing the shared number", () => {
+    const credentialManager = new CredentialManager();
+    credentialManager.add({
+      username: "tester",
+      password: "secret",
+      loginUrl: "https://example.com/login",
+      additionalFields: {
+        authMethod: "sms-mfa",
+        phoneNumber: "stage-managed-number",
+      },
+    });
+
+    const prompt = buildBlackboxPrompt("https://example.com", {
+      id: "session-1",
+      rootPath: "/tmp/apex-blackbox-prompt",
+      config: {},
+      credentialManager,
+    } as SessionInfo);
+
+    expect(prompt).toContain("Authentication method: sms-mfa");
+    expect(prompt).toContain("`sms-mfa`: fill username and password first");
+    expect(prompt).toContain("Make at most two separate reservation attempts");
+    expect(prompt).not.toContain("stage-managed-number");
+  });
+});

package/src/core/agents/specialized/attackSurface/blackboxAgent.ts

@@ -0,0 +1,272 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hasToolCall, stepCountIs } from "ai";
+import type { SessionInfo } from "../../../session";
+import { AgentRuntime } from "../../agentRuntime";
+import { defineAgent } from "../../defineAgent";
+import type { SpecializedAgentInput } from "../../offSecAgent";
+import { MOBILE_OTP_PROMPT_GUIDANCE } from "../mobileOtpPrompt";
+import { SYSTEM as ATTACK_SURFACE_SYSTEM_PROMPT } from "./prompts";
+import type { AttackSurfaceAnalysisResults, PentestTarget } from "./types";
+import { loadAttackSurfaceResults } from "./types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** At least one of `target` or `cwd` must be provided. */
+export type AttackSurfaceAgentInput = SpecializedAgentInput &
+  (
+    | {
+        /** The target to analyze (domain, IP, URL, network range, or org name) */
+        target: string;
+        cwd?: string;
+      }
+    | {
+        target?: string;
+        /** Working directory for source-code based analysis */
+        cwd: string;
+      }
+  ) & {
+    /**
+     * Whitebox-only: when false, the workflow skips the `@pensar/surface`
+     * deterministic-enumeration path and uses the legacy pages+apiEndpoints
+     * discovery agents. Defaults to `true`. Has no effect on blackbox runs.
+     */
+    surfaceIntegrationEnabled?: boolean;
+  };
+
+/** The typed result returned by `AttackSurfaceAgent.consume()`. */
+export interface AttackSurfaceResult {
+  /** The full analysis results (targets, assets, key findings) */
+  results: AttackSurfaceAnalysisResults | null;
+  /** All targets identified for deep penetration testing */
+  targets: PentestTarget[];
+  /** Absolute path to the attack-surface-results.json file */
+  resultsPath: string;
+  /** Absolute path to the session's assets directory */
+  assetsPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// AttackSurfaceAgent
+// ---------------------------------------------------------------------------
+
+interface BlackboxState {
+  target: string;
+  subagentFolder: string;
+}
+
+function resolveBlackboxTarget(opts: AttackSurfaceAgentInput): string {
+  return opts.target ?? (opts.cwd as string);
+}
+
+export const blackboxAttackSurfaceDefinition = defineAgent<
+  AttackSurfaceAgentInput,
+  AttackSurfaceResult,
+  BlackboxState
+>({
+  name: "blackbox-attack-surface",
+  role: "orchestrator",
+  createState: (opts) => {
+    const subagentFolder = join(
+      opts.session.rootPath,
+      "subagents",
+      "attack-surface-agent",
+    );
+    if (!existsSync(subagentFolder)) {
+      mkdirSync(subagentFolder, { recursive: true });
+    }
+    return { target: resolveBlackboxTarget(opts), subagentFolder };
+  },
+  system: () => ATTACK_SURFACE_SYSTEM_PROMPT,
+  activeTools: () => [
+    // Core recon tools
+    "execute_command",
+    "document_app",
+    "document_endpoint",
+    "create_attack_surface_report",
+    // Browser automation for SPAs, JS-heavy apps, and auth flows
+    "browser_navigate",
+    "browser_snapshot",
+    "browser_screenshot",
+    "browser_click",
+    "browser_fill",
+    "browser_evaluate",
+    "browser_console",
+    "browser_get_cookies",
+    // Email tools (filtered out by base class when no inboxes configured)
+    "email_list_inboxes",
+    "email_list_messages",
+    "email_search_messages",
+    "email_get_message",
+    // Send email (filtered out by base class when no SMTP configured)
+    "send_email",
+    // Mobile OTP list (filtered out by base class when no Mobile OTP cred)
+    "sms_list_messages",
+    // Web search tools — research target technologies, find known vulnerabilities
+    "web_search",
+    "get_page",
+  ],
+  stopWhen: () => [
+    hasToolCall("create_attack_surface_report"),
+    stepCountIs(10_000),
+  ],
+  target: (_opts, state) => state.target,
+  prompt: (opts, state) => buildBlackboxPrompt(state.target, opts.session),
+  resolveResult: (opts) => {
+    const resultsPath = join(
+      opts.session.rootPath,
+      "attack-surface-results.json",
+    );
+    const assetsPath = join(opts.session.rootPath, "assets");
+    let results: AttackSurfaceAnalysisResults | null = null;
+    let targets: PentestTarget[] = [];
+
+    if (existsSync(resultsPath)) {
+      try {
+        results = loadAttackSurfaceResults(resultsPath);
+        targets = results.targets || [];
+      } catch {
+        // Report may not have been written yet
+      }
+    }
+
+    return { results, targets, resultsPath, assetsPath };
+  },
+  onStepFinish: (opts, state) => (e) => {
+    opts.onStepFinish?.(e);
+    const messages = e.response.messages;
+    if (messages !== undefined) {
+      writeFileSync(
+        join(state.subagentFolder, "attack-surface-agent.log"),
+        JSON.stringify(messages, null, 2),
+      );
+    }
+  },
+});
+
+/**
+ * A recon-focused specialisation of {@link OffensiveSecurityAgent}.
+ *
+ * Maps the entire attack surface of a target — discovers assets, endpoints,
+ * authentication flows, and produces a list of targets for deep testing.
+ *
+ * `consume()` returns an {@link AttackSurfaceResult} with the full analysis.
+ *
+ * @example
+ * ```ts
+ * const agent = new AttackSurfaceAgent({
+ *   target: "https://example.com",
+ *   model: "claude-sonnet-4-20250514",
+ *   session,
+ * });
+ *
+ * const { targets, results } = await agent.consume({
+ *   onTextDelta: (d) => process.stdout.write(d.text),
+ *   onToolCall:  (d) => console.log(`→ ${d.toolName}`),
+ * });
+ *
+ * console.log(`Identified ${targets.length} targets for deep testing`);
+ * ```
+ */
+export class BlackboxAttackSurfaceAgent extends AgentRuntime<
+  AttackSurfaceAgentInput,
+  AttackSurfaceResult,
+  BlackboxState
+> {
+  constructor(opts: AttackSurfaceAgentInput) {
+    super(blackboxAttackSurfaceDefinition, opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+export function buildBlackboxPrompt(
+  target: string,
+  session: SessionInfo,
+): string {
+  const scopeConstraints = session.config?.scopeConstraints;
+  const authenticationInstructions = session.config?.authenticationInstructions;
+  const enumerateSubdomains = session.config?.enumerateSubdomains ?? false;
+  const operatorPrompt = session.config?.prompt;
+
+  const cm = session.credentialManager;
+  const credBlock = cm?.formatForPrompt();
+  const firstRef = cm?.listReferences()[0];
+  const loginTarget = firstRef?.loginUrl ?? target;
+
+  // --- Authentication block ---
+  let authBlock: string;
+
+  if (credBlock) {
+    const parts: string[] = [];
+    if (authenticationInstructions) {
+      parts.push(
+        `<authentication_instructions>\n${authenticationInstructions}\n</authentication_instructions>`,
+      );
+    }
+    parts.push(credBlock);
+
+    authBlock = `⚠️ AUTHENTICATION CREDENTIALS PROVIDED — YOU MUST LOG IN FIRST.
+
+Your FIRST tool call must be: browser_navigate to ${loginTarget}
+Then use browser tools to authenticate. Pass the credentialId to delegate_to_auth_subagent — secrets are resolved automatically.
+For browser_fill on password/secret fields, use credentialId + credentialField instead of raw values.
+${MOBILE_OTP_PROMPT_GUIDANCE}
+
+Do NOT run curl, nmap, dig, or any other command before completing login.
+Include authentication information with EVERY target that requires it in your final report.
+
+${parts.join("\n\n")}`;
+  } else if (authenticationInstructions) {
+    authBlock = `⚠️ AUTHENTICATION INSTRUCTIONS PROVIDED — YOU MUST LOG IN FIRST.
+
+Your FIRST tool call must be: browser_navigate to ${loginTarget}
+
+Do NOT run curl, nmap, dig, or any other command before completing login.
+Include authentication information with EVERY target that requires it in your final report.
+
+<authentication_instructions>
+${authenticationInstructions}
+</authentication_instructions>`;
+  } else {
+    authBlock = `AUTHENTICATION: No credentials provided. Skip Phase 1 and proceed with unauthenticated discovery.
+Note any login pages you find as assets and flag them for pentest agents.`;
+  }
+
+  // --- Scope block ---
+  const scopeRules = scopeConstraints?.strictScope
+    ? `STRICT SCOPE — Only test URLs/endpoints within allowed hosts and ports. Do NOT scan outside the target.`
+    : `OPEN SCOPE — You may discover and explore related/adjacent targets.`;
+
+  // --- Subdomain enumeration block ---
+  const subdomainBlock = enumerateSubdomains
+    ? `SUBDOMAIN ENUMERATION: ENABLED — Execute Phase 2 fully (DNS brute-force, certificate transparency, zone transfers).`
+    : `SUBDOMAIN ENUMERATION: DISABLED — Skip Phase 2 entirely. Focus only on the provided target URL.`;
+
+  const startDirective =
+    credBlock || authenticationInstructions
+      ? `Begin NOW by logging in. Your first tool call must be browser_navigate to ${loginTarget}. After login, continue with the remaining phases.`
+      : `Begin attack surface analysis now. Follow the phases defined in your system prompt in order.`;
+
+  const operatorGuidanceBlock = operatorPrompt
+    ? `\n## Operator Guidance\n${operatorPrompt}\n`
+    : "";
+
+  return `TARGET: ${target}
+
+Session: ${session.id}
+Assets directory: ${join(session.rootPath, "assets")}
+
+${authBlock}
+
+SCOPE:
+${scopeRules}
+
+${subdomainBlock}
+${operatorGuidanceBlock}
+${startDirective}`;
+}

package/src/core/agents/specialized/attackSurface/blackboxRiskScoring.ts

@@ -0,0 +1,276 @@
+import type { RiskScore } from "../whiteboxAttackSurface";
+import type { RiskLevel } from "./schemas";
+
+interface EndpointDetails {
+  url?: string;
+  method?: string | string[];
+  authentication?: string;
+  authRequired?: boolean;
+  handler?: string;
+  file?: string;
+  line?: number;
+  services?: string[];
+  technology?: string[];
+  status?: string | number;
+  [key: string]: unknown;
+}
+
+/**
+ * Base score mapping from risk level to total score.
+ */
+const RISK_LEVEL_BASE_SCORE: Record<RiskLevel, number> = {
+  CRITICAL: 10,
+  HIGH: 8,
+  MEDIUM: 5,
+  LOW: 2,
+};
+
+/**
+ * Heuristic exposure scores by risk level.
+ *
+ * Blackbox assets are discovered from the outside, so exposure is
+ * generally higher than for whitebox endpoints. The agent's riskLevel
+ * already encodes how exposed/sensitive the asset is.
+ */
+const EXPOSURE_BY_RISK: Record<RiskLevel, number> = {
+  CRITICAL: 3,
+  HIGH: 3,
+  MEDIUM: 2,
+  LOW: 1,
+};
+
+/**
+ * Compute a heuristic {@link RiskScore} for a blackbox-discovered asset.
+ *
+ * Since there is no source code to read, we derive the four breakdown
+ * dimensions from the agent-assigned `riskLevel`, the `assetType`, and
+ * observable metadata (authentication, services, technology stack).
+ *
+ * The breakdown dimensions match the whitebox model:
+ *   - **exposure** (0-3): How reachable is the asset from the outside?
+ *   - **dataSensitivity** (0-3): How sensitive is the data it likely handles?
+ *   - **functionCriticality** (0-2): How critical is the business function?
+ *   - **securityIndicators** (0-2): Are there observable security concerns?
+ */
+export function computeBlackboxRiskScore(
+  riskLevel: RiskLevel,
+  assetType: string,
+  details?: EndpointDetails,
+  notes?: string,
+): RiskScore {
+  const exposure = computeExposure(riskLevel, details);
+  const dataSensitivity = computeDataSensitivity(riskLevel, assetType, details);
+  const functionCriticality = computeFunctionCriticality(
+    riskLevel,
+    assetType,
+    details,
+    notes,
+  );
+  const securityIndicators = computeSecurityIndicators(
+    riskLevel,
+    details,
+    notes,
+  );
+
+  const rawSum =
+    exposure + dataSensitivity + functionCriticality + securityIndicators;
+  const score = Math.min(10, Math.max(0, rawSum));
+
+  const baseScore = RISK_LEVEL_BASE_SCORE[riskLevel] ?? 0;
+  const explanation = buildExplanation(riskLevel, assetType, baseScore, score, {
+    exposure,
+    dataSensitivity,
+    functionCriticality,
+    securityIndicators,
+  });
+
+  return {
+    score,
+    explanation,
+    breakdown: {
+      exposure,
+      dataSensitivity,
+      functionCriticality,
+      securityIndicators,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension helpers
+// ---------------------------------------------------------------------------
+
+function computeExposure(
+  riskLevel: RiskLevel,
+  details?: EndpointDetails,
+): number {
+  let base = EXPOSURE_BY_RISK[riskLevel] ?? 1;
+
+  if (details?.authentication) {
+    const authLower = details.authentication.toLowerCase();
+    if (
+      authLower.includes("none") ||
+      authLower.includes("no auth") ||
+      authLower.includes("public")
+    ) {
+      base = Math.max(base, 3);
+    } else if (
+      authLower.includes("admin") ||
+      authLower.includes("privileged")
+    ) {
+      base = Math.min(base, 1);
+    }
+  }
+
+  return Math.min(3, Math.max(0, base));
+}
+
+function computeDataSensitivity(
+  riskLevel: RiskLevel,
+  _assetType: string,
+  details?: EndpointDetails,
+): number {
+  if (riskLevel === "CRITICAL") return 3;
+
+  let score = riskLevel === "HIGH" ? 2 : riskLevel === "MEDIUM" ? 1 : 0;
+
+  const techStr = (details?.technology ?? []).join(" ").toLowerCase();
+  if (
+    techStr.includes("database") ||
+    techStr.includes("postgres") ||
+    techStr.includes("mysql") ||
+    techStr.includes("mongo") ||
+    techStr.includes("redis")
+  ) {
+    score = Math.max(score, 2);
+  }
+
+  return Math.min(3, score);
+}
+
+function computeFunctionCriticality(
+  riskLevel: RiskLevel,
+  assetType: string,
+  details?: EndpointDetails,
+  notes?: string,
+): number {
+  if (riskLevel === "CRITICAL") return 2;
+
+  const searchText = [
+    ...(details?.services ?? []),
+    ...(details?.technology ?? []),
+    details?.authentication ?? "",
+    notes ?? "",
+  ]
+    .join(" ")
+    .toLowerCase();
+
+  const criticalPatterns = [
+    "auth",
+    "login",
+    "payment",
+    "checkout",
+    "password",
+    "oauth",
+    "sso",
+    "saml",
+    "admin",
+    "transfer",
+    "billing",
+  ];
+  if (criticalPatterns.some((p) => searchText.includes(p))) return 2;
+
+  if (riskLevel === "HIGH") return 1;
+  if (assetType === "api" || assetType === "web_application") return 1;
+
+  return 0;
+}
+
+function computeSecurityIndicators(
+  riskLevel: RiskLevel,
+  details?: EndpointDetails,
+  notes?: string,
+): number {
+  if (riskLevel === "CRITICAL") return 2;
+
+  const searchText = [
+    ...(details?.services ?? []),
+    ...(details?.technology ?? []),
+    notes ?? "",
+    String(details?.status ?? ""),
+  ]
+    .join(" ")
+    .toLowerCase();
+
+  const criticalIndicators = [
+    "injection",
+    "sqli",
+    "xss",
+    "rce",
+    "traversal",
+    "deserialization",
+    "hardcoded",
+    "default credentials",
+    "vulnerable",
+    "cve-",
+    "exploit",
+  ];
+  if (criticalIndicators.some((p) => searchText.includes(p))) return 2;
+
+  const moderateIndicators = [
+    "outdated",
+    "deprecated",
+    "insecure",
+    "http:",
+    "self-signed",
+    "debug",
+    "verbose error",
+    "stack trace",
+    "cors",
+    "misconfigur",
+  ];
+  if (moderateIndicators.some((p) => searchText.includes(p))) return 1;
+
+  if (riskLevel === "HIGH") return 1;
+
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Explanation builder
+// ---------------------------------------------------------------------------
+
+function buildExplanation(
+  riskLevel: RiskLevel,
+  assetType: string,
+  _baseScore: number,
+  totalScore: number,
+  breakdown: {
+    exposure: number;
+    dataSensitivity: number;
+    functionCriticality: number;
+    securityIndicators: number;
+  },
+): string {
+  const parts: string[] = [
+    `${riskLevel} risk ${assetType.replace(/_/g, " ")} (score ${totalScore}/10).`,
+  ];
+
+  if (breakdown.exposure >= 3) parts.push("Publicly exposed.");
+  else if (breakdown.exposure >= 2) parts.push("Externally accessible.");
+
+  if (breakdown.dataSensitivity >= 3)
+    parts.push("Likely handles sensitive data.");
+  else if (breakdown.dataSensitivity >= 2)
+    parts.push("May handle business-critical data.");
+
+  if (breakdown.functionCriticality >= 2) parts.push("Critical function.");
+  else if (breakdown.functionCriticality >= 1) parts.push("Core function.");
+
+  if (breakdown.securityIndicators >= 2)
+    parts.push("Security concerns observed.");
+  else if (breakdown.securityIndicators >= 1)
+    parts.push("Moderate security concerns.");
+
+  return parts.join(" ");
+}