> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/apex/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/apex/_mcp/server.

# runPentestAgent

> Run a full blackbox or whitebox pentest: attack surface discovery followed by a swarm of targeted pentest agents

**`Signature`**

```ts title="Signature"
function runPentestAgent(
  input: PentestWorkflowInput,
): Promise<PentestWorkflowResult>;
```

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

1. **Discovery.** Maps the attack surface. With `cwd` it reads the source code (whitebox); otherwise it probes the live `target` (blackbox).
2. **Pentesting.** Spawns a targeted pentest agent for each discovered endpoint, up to 10 at a time.
3. **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`**

```ts title="Import"
import { runPentestAgent } from "@pensar/apex/core/api";
```

## Parameters

**`target`** `string` — required

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

---

**`session`** `SessionInfo` — required

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

---

**`model`** `AIModel` — required

Model ID, for example `"claude-opus-4-6"`. See [Models](/apex/sdk/configuration#models).

---

**`authConfig`** `AIAuthConfig`

AI provider credentials. Usually `buildAuthConfig(await config.get())`. See [Configuration](/apex/sdk/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](/apex/sdk/reference/agent-event-bus).

---

**`abortSignal`** `AbortSignal`

Cancels the run. See [Errors and cancellation](/apex/sdk/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](/apex/sdk/configuration#reasoning).

---

**`enableThinking`** `boolean` — default: false

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

---

**`fastStrike`** `boolean` — default: false

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

---

**`findingPolicy`** `'native' | 'external'` — default: native

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

---

**`surfaceIntegrationEnabled`** `boolean` — default: 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`**

```ts title="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}`);
```

## Related

#### [runTargetedPentestAgent](/apex/sdk/reference/run-targeted-pentest-agent)

Skip discovery and test specific objectives

#### [pensar pentest](/apex/cli-commands/pensar-pentest)

The CLI equivalent