runPentestAgent | Pensar Apex

Signature

function runPentestAgent(
  input: PentestWorkflowInput,
): Promise<PentestWorkflowResult>;

Runs Apex’s full pentest workflow, the same one pensar pentest and the TUI’s /pentest use:

Discovery. Maps the attack surface. With cwd it reads the source code (whitebox); otherwise it probes the live target (blackbox).
Pentesting. Spawns a targeted pentest agent for each discovered endpoint, up to 10 at a time.
Reporting. Groups findings by root cause and writes pentest-report.md and pentest-report.json to the session directory.

Token usage is saved to the session whether the run succeeds or fails. When the run finishes, a short summary of the findings and artifact paths is printed to stdout.

Import

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

Parameters

target

stringRequired

Live target URL, domain, or IP. Required in whitebox mode too: the pentest phase always runs against the live service.

session

SessionInfoRequired

Session that receives findings, POCs, logs, and the report. Create one with sessions.create(). Its config controls scope, credentials, headers, and safety settings for the run.

model

AIModelRequired

Model ID, for example "claude-opus-4-6". See Models.

authConfig

AIAuthConfig

AI provider credentials. Usually buildAuthConfig(await config.get()). See Configuration.

cwd

string

Path to the target’s source code. Enables whitebox attack surface discovery.

eventBus

AgentEventBus

Receives streaming text, tool calls, sub-agent lifecycle, and workflow phase events. See AgentEventBus.

abortSignal

AbortSignal

Cancels the run. See Errors and cancellation.

prompt

string

Extra guidance injected into the discovery agents’ system prompts (for example, “Focus on authentication bypass”).

threatModel

string

Raw threat model content. Apex wraps it with standard instructions and injects it next to prompt.

reasoning

ReasoningSetting

Extended-thinking setting for supported models. See Reasoning.

enableThinking

booleanDefaults to false

Enable extended thinking for supported models. Prefer reasoning for new code.

fastStrike

booleanDefaults to false

Skip attack surface discovery and the swarm. Runs a single operator in one tight recon-to-exploit loop against target.

findingPolicy

'native' | 'external'Defaults to native

native runs Apex’s finding judge and returns structured findings. external skips the judge and returns concise reportedFindings for your own evaluator.

surfaceIntegrationEnabled

booleanDefaults to true

Whitebox only. Set to false to skip deterministic @pensar/surface enumeration and use the discovery agents for every app.

onStepFinish

(step: StepResult) => void | Promise<void>

Called after every agent step, with the AI SDK step result (including token usage).

Returns

Promise<PentestWorkflowResult>

findings

Finding[]

Every documented vulnerability. Empty when findingPolicy is external.

title

string

Short vulnerability title.

severity

'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW'

Severity rating.

endpoint

string

Affected URL or endpoint.

description

string

What the vulnerability is.

impact

string

What an attacker can achieve.

evidence

string

Proof gathered during exploitation.

pocPath

string

Path to the proof-of-concept script in the session’s pocs/ directory.

remediation

string

How to fix it.

cwes

CweEntry[]

CWE mappings, when known.

rootCauseGroup

string

Shared identifier for findings with the same root cause.

reportedFindings

string[]

Concise findings for external evaluation. Only set when findingPolicy is external.

objectiveResults

{ objective: string; completed: boolean; result?: string }[]

Per-objective status from every swarm worker. Only set when findingPolicy is external.

findingsPath

string

Absolute path to the session’s findings/ directory.

pocsPath

string

Absolute path to the session’s pocs/ directory.

reportPath

string | null

Absolute path to pentest-report.md. null when no report is written, for example when findingPolicy is external.

Example

Whitebox pentest with progress

import { buildAuthConfig } from "@pensar/apex/core/ai";
import { runPentestAgent } from "@pensar/apex/core/api";
import { config } from "@pensar/apex/core/config";
import { AgentEventBus } from "@pensar/apex/core/eventBus";
import { sessions } from "@pensar/apex/core/session";
const target = "http://localhost:3000";
const session = await sessions.create({
  name: "Whitebox pentest",
  targets: [target],
  config: { codebasePath: "./my-app" },
});
const eventBus = new AgentEventBus();
eventBus.on("workflow-phase-start", ({ label }) => console.log(`== ${label}`));
eventBus.on("subagent-complete", ({ subagentId, status }) =>
  console.log(`${subagentId}: ${status}`),
);
const { findings, reportPath } = await runPentestAgent({
  target,
  cwd: "./my-app",
  session,
  model: "claude-opus-4-6",
  authConfig: buildAuthConfig(await config.get()),
  eventBus,
  prompt: "Prioritize the payments API",
});
const critical = findings.filter((f) => f.severity === "CRITICAL");
console.log(`${critical.length} critical findings. Report: ${reportPath}`);

runTargetedPentestAgent

Skip discovery and test specific objectives

pensar pentest

The CLI equivalent

Parameters

Returns

Example

Related