SDK Quickstart | Pensar Apex

This guide runs a blackbox pentest against a live target from a TypeScript script and prints the findings.

Prerequisites

@pensar/apex installed in your project (see Installation)
An AI provider configured, either through an environment variable such as ANTHROPIC_API_KEY or by running pensar login. See Configuration.
A target you are authorized to test

Run a pentest

pentest.ts

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 = "https://staging.example.com";
// Provider keys from ~/.pensar/config.json, with environment variable fallbacks
const pensarConfig = await config.get();
// Allocates ~/.pensar/sessions/<id>/ for findings, POCs, and logs
const session = await sessions.create({
  name: "SDK pentest",
  targets: [target],
});
const eventBus = new AgentEventBus();
eventBus.on("tool-call-complete", (e) => console.log(`→ ${e.toolName}`));
const result = await runPentestAgent({
  target,
  session,
  model: "claude-opus-4-6",
  authConfig: buildAuthConfig(pensarConfig),
  eventBus,
});
for (const finding of result.findings) {
  console.log(`[${finding.severity}] ${finding.title} — ${finding.endpoint}`);
}
console.log(`Report: ${result.reportPath}`);

Run it:

ANTHROPIC_API_KEY=sk-ant-... bun pentest.ts

runPentestAgent first maps the target’s attack surface, then runs a swarm of targeted pentest agents against each endpoint it discovered. When it finishes, the session directory contains:

Path	Contents
`findings/`	One file per documented vulnerability
`pocs/`	Proof-of-concept scripts for each finding
`logs/`	Execution logs
`pentest-report.md`, `pentest-report.json`	The final pentest report (`result.reportPath` points to the Markdown file)

Whitebox mode

Pass cwd with the path to the target’s source code. The attack surface phase then reads the code directly, while the pentest phase still tests the live target:

const result = await runPentestAgent({
  target: "http://localhost:3000",
  cwd: "./my-app",
  session,
  model: "claude-opus-4-6",
  authConfig: buildAuthConfig(pensarConfig),
});

Next steps

runTargetedPentestAgent

Test specific objectives against a single target

AgentEventBus

Stream agent text, tool calls, and phases

Errors and cancellation

Abort runs and handle failures

sessions

Configure scope, credentials, and headers