Skip to main content

​
Overview

The Blackbox Pentest API orchestrates a full penetration testing workflow that combines attack surface discovery with targeted exploitation. It automatically spawns multiple specialized agents to test discovered targets in parallel. Key Features:
  • Two-phase workflow: reconnaissance then exploitation
  • Supports both blackbox and whitebox testing modes
  • Automatic target prioritization and agent spawning
  • Parallel execution with configurable concurrency
  • Comprehensive finding deduplication
  • Automatic report generation

​
runPentestAgent

Run the deterministic pentest workflow (blackbox or whitebox based on input). Workflow Phases:
  1. Phase 1: Runs attack surface discovery (whitebox workflow or blackbox agent)
  2. Phase 2: Spawns targeted pentest agents for each discovered target
  3. Phase 3: Aggregates results and generates report
import { runPentestAgent } from '@pensar/apex/api/blackboxPentest';

const result = await runPentestAgent({
  target: 'https://example.com',
  model: 'claude-sonnet-4-20250514',
  session: sessionInfo,
  callbacks: {
    onTextDelta: (d) => process.stdout.write(d.text),
    subagentCallbacks: {
      onSubagentSpawn: ({ subagentId, status }) => {
        console.log(`${subagentId}: ${status}`);
      },
      onSubagentComplete: ({ subagentId, status }) => {
        console.log(`${subagentId}: ${status}`);
      },
    },
  },
});

console.log(`Found ${result.findings.length} vulnerabilities`);

​
Parameters

​
input
PentestWorkflowInput
required
Configuration for the pentest workflow

​
Response

​
findings
Finding[]
All vulnerability findings discovered during the pentest
​
findingsPath
string
Absolute path to the session’s findings directory
​
pocsPath
string
Absolute path to the session’s POC scripts directory
​
reportPath
string | null
Path to the generated pentest report (null if not generated)

​
Usage Examples

import { runPentestAgent } from '@pensar/apex/api/blackboxPentest';
import { createSession } from '@pensar/apex/session';

// Create session
const session = await createSession({
  name: 'Full Pentest',
  targets: ['https://example.com'],
});

// Run full pentest workflow
const result = await runPentestAgent({
  target: 'https://example.com',
  model: 'claude-sonnet-4-20250514',
  session,
});

console.log(`Findings: ${result.findingsPath}`);
console.log(`POCs: ${result.pocsPath}`);
if (result.reportPath) {
  console.log(`Report: ${result.reportPath}`);
}

​
Workflow Details

​
Phase 1: Attack Surface Discovery

The workflow begins by discovering the attack surface:
  • Blackbox mode (default): Runs external reconnaissance using web scraping, DNS enumeration, port scanning, and browser automation
  • Whitebox mode (when cwd provided): Analyzes source code to extract API endpoints, routes, and pages
Both modes produce a list of prioritized targets with specific testing objectives.

​
Phase 2: Parallel Exploitation

The workflow spawns multiple TargetedPentestAgent instances (default: 10 concurrent) to test each target:
  • Each agent receives specific targets and objectives from Phase 1
  • Agents run in parallel with bounded concurrency
  • Findings are automatically deduplicated via shared registry
  • Progress is tracked via subagent callbacks

​
Phase 3: Result Aggregation

After all agents complete:
  • All findings are collected from the session’s findings directory
  • A comprehensive pentest report is generated (if applicable)
  • Results are returned with paths to findings, POCs, and reports

Attack Surface

Run attack surface discovery separately

Targeted Pentest

Test specific targets without discovery

Authentication

Authenticate before pentesting

Patching

Generate patches for vulnerabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us