Attack Surface

Discover and map the attack surface of a target system

Overview

The Attack Surface API provides comprehensive reconnaissance and attack surface mapping capabilities for both blackbox and whitebox testing scenarios.

Key Features:

• Automatic mode selection based on input (whitebox vs blackbox)
• Asset discovery and enumeration
• Endpoint and page detection
• Authentication flow mapping
• Target prioritization for deep testing

---

runAttackSurfaceAgent

Run the appropriate attack surface agent based on the input configuration.

Behavior:

• If cwd is provided, runs the whitebox agent which analyzes source code directly to map endpoints and pages
• Otherwise, runs the blackbox agent which probes a live target from the outside
• target is always required (the live URL to test against)

import { runAttackSurfaceAgent } from '@pensar/apex/api/attackSurface';

const result = await runAttackSurfaceAgent({
  target: 'https://example.com',
  model: 'claude-sonnet-4-20250514',
  session: sessionInfo,
  callbacks: {
    onTextDelta: (d) => process.stdout.write(d.text),
    onToolCall: (d) => console.log(`→ calling ${d.toolName}`),
    onToolResult: (d) => console.log(`✓ ${d.toolName} completed`),
  },
});

console.log(`Identified ${result.targets.length} targets`);

Parameters

input · AttackSurfaceAgentInput · required

Configuration for the attack surface agent

Show AttackSurfaceAgentInput properties

target · string · required

The target to analyze (domain, IP, URL, network range, or org name)

cwd · string

Working directory for source-code based analysis. When provided, enables whitebox mode.

model · AIModel · required

AI model identifier (e.g., "claude-sonnet-4-20250514")

session · SessionInfo · required

Session object providing paths for findings, POCs, logs, etc.

authConfig · AIAuthConfig

Optional per-provider API key overrides

abortSignal · AbortSignal

AbortSignal to cancel the agent mid-run

callbacks · ConsumeCallbacks

Stream event callbacks for monitoring agent progress

Show ConsumeCallbacks properties

onTextDelta · (delta) => void

Called for each text chunk streamed from the AI

onToolCall · (delta) => void

Called when the agent invokes a tool

onToolResult · (delta) => void

Called when a tool execution completes

onError · (error) => void

Called when an error occurs

onStepFinish · StreamTextOnStepFinishCallback

Callback fired after each agent step completes

Response

results · AttackSurfaceAnalysisResults | WhiteboxAttackSurfaceResult | null

The full analysis results with discovered assets and key findings

Show AttackSurfaceAnalysisResults (Blackbox)

summary · AttackSurfaceSummary

High-level statistics about the analysis

Show properties

totalAssets · number

Total number of assets discovered

totalDomains · number

Total number of domains found

highValueTargets · number

Count of high-priority targets

analysisComplete · boolean

Whether the analysis completed successfully

discoveredAssets · string[]

List of all discovered assets (servers, services, endpoints)

targets · PentestTarget[]

Prioritized targets for deep penetration testing

keyFindings · string[]

Notable security observations from reconnaissance

Show WhiteboxAttackSurfaceResult (Whitebox)

apps · App[]

All applications/services discovered in the codebase

Show App properties

name · string

Application or service name

framework · string

Framework in use (e.g., Express, Next.js, Django)

description · string

Brief description of the app

location · string

Path to the app root

pages · Endpoint[]

Web pages and routes

apiEndpoints · Endpoint[]

API endpoints

summary · object

Statistics about the whitebox analysis

Show properties

totalApps · number

Number of apps found

totalPages · number

Total web pages

totalApiEndpoints · number

Total API endpoints

targets · PentestTarget[]

All targets identified for deep penetration testing

Show PentestTarget properties

target · string

The URL or endpoint to test

objective · string

Testing objective for this target

rationale · string

Why this target was prioritized

authenticationInfo · object

Authentication details if applicable

Show properties

method · string

Authentication method

details · string

Additional auth details

credentials · string

Credential reference ID

cookies · string

Session cookies

headers · string

Required headers

resultsPath · string

Absolute path to the attack-surface-results.json file

assetsPath · string

Absolute path to the session’s assets directory

---

Usage Examples

Blackbox Testing

import { runAttackSurfaceAgent } from '@pensar/apex/api/attackSurface';
import { createSession } from '@pensar/apex/session';

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

// Run blackbox attack surface analysis
const result = await runAttackSurfaceAgent({
  target: 'https://example.com',
  model: 'claude-sonnet-4-20250514',
  session,
  callbacks: {
    onTextDelta: (d) => process.stdout.write(d.text),
    onToolCall: (d) => console.log(`→ ${d.toolName}`),
  },
});

console.log(`Found ${result.targets.length} targets`);
console.log(`Results saved to: ${result.resultsPath}`);

---

Related APIs

Blackbox Pentest

Full penetration testing workflow

Targeted Pentest

Test specific targets and objectives

Authentication

Authenticate against a target