Skip to navigation
SDKReference

runAttackSurfaceAgent

Signature
function runAttackSurfaceAgent(
  input: AttackSurfaceInput,
): Promise<AttackSurfaceResult | WhiteboxAttackSurfaceResult>;

Runs only the discovery phase of a pentest:

  • Blackbox. When cwd is not set, the agent probes the live target (domain, IP, URL, network range, or organization name). It returns the assets it found, plus the targets that warrant deep testing.
  • Whitebox. When cwd is set, Apex analyzes the source code. It returns every app, page, and API endpoint it finds, each with pentest objectives and a risk score.

Feed the results into runTargetedPentestAgent to test the endpoints you care about.

Import
import { runAttackSurfaceAgent } from "@pensar/apex/core/api";

Parameters

target
string

What to analyze. Required for blackbox runs.

cwd
string

Path to the source code. Switches the run to whitebox mode.

session
SessionInfoRequired

Session for artifacts. See sessions.create().

model
AIModelRequired

Model ID. See Models.

authConfig
AIAuthConfig

AI provider credentials.

eventBus
AgentEventBus

Streaming events. See AgentEventBus.

abortSignal
AbortSignal

Cancels the run.

surfaceIntegrationEnabled
booleanDefaults to true

Whitebox only. Set to false to skip deterministic @pensar/surface enumeration.

reasoning
ReasoningSetting

Extended-thinking setting. See Reasoning.

Returns

Blackbox: AttackSurfaceResult

targets
PentestTarget[]

Targets recommended for deep testing. Each has a target, an objective, a rationale, and optional authenticationInfo.

results
AttackSurfaceAnalysisResults | null

The full analysis: summary counts, discoveredAssets, targets, and keyFindings. null if the agent didn’t submit one.

resultsPath
string

Absolute path to attack-surface-results.json in the session.

assetsPath
string

Absolute path to the session’s assets directory.

Whitebox: WhiteboxAttackSurfaceResult

apps
App[]

Every application found in the repository, with its name, type, framework, location, pages, and apiEndpoints. Each endpoint carries method, path, file, authRequired, pentestObjectives, and riskScore.

summary
{ totalApps: number; totalPages: number; totalApiEndpoints: number; totalPentestObjectives: number }

Counts across all apps.

repoType
string

Repository layout, for example monorepo or single-app.

packageManager
string

Detected package manager.

Example

Discover, then test the riskiest targets
import { buildAuthConfig } from "@pensar/apex/core/ai";
import { runAttackSurfaceAgent, runTargetedPentestAgent } from "@pensar/apex/core/api";
import { config } from "@pensar/apex/core/config";
import { sessions } from "@pensar/apex/core/session";
const authConfig = buildAuthConfig(await config.get());
const model = "claude-opus-4-6";
const session = await sessions.create({
  name: "Recon",
  targets: ["example.com"],
});
const surface = await runAttackSurfaceAgent({
  target: "example.com",
  session,
  model,
  authConfig,
});
if ("targets" in surface) {
  for (const t of surface.targets.slice(0, 3)) {
    await runTargetedPentestAgent({
      target: t.target,
      objectives: [t.objective],
      session,
      model,
      authConfig,
    });
  }
}