> 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.

# runAttackSurfaceAgent

> Map a target's attack surface from the outside (blackbox) or from its source code (whitebox)

**`Signature`**

```ts title="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`](/apex/sdk/reference/run-targeted-pentest-agent) to test the endpoints you care about.

**`Import`**

```ts title="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`** `SessionInfo` — required

Session for artifacts. See [`sessions.create()`](/apex/sdk/reference/sessions).

---

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

Model ID. See [Models](/apex/sdk/configuration#models).

---

**`authConfig`** `AIAuthConfig`

AI provider credentials.

---

**`eventBus`** `AgentEventBus`

Streaming events. See [AgentEventBus](/apex/sdk/reference/agent-event-bus).

---

**`abortSignal`** `AbortSignal`

Cancels the run.

---

**`surfaceIntegrationEnabled`** `boolean` — default: true

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

---

**`reasoning`** `ReasoningSetting`

Extended-thinking setting. See [Reasoning](/apex/sdk/configuration#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`**

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