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
The target to analyze (domain, IP, URL, network range, or org name)
Working directory for source-code based analysis. When provided, enables whitebox mode.
AI model identifier (e.g., "claude-sonnet-4-20250514")
Session object providing paths for findings, POCs, logs, etc.
Optional per-provider API key overrides
AbortSignal to cancel the agent mid-run
Stream event callbacks for monitoring agent progress Show ConsumeCallbacks properties
Called for each text chunk streamed from the AI
Called when the agent invokes a tool
Called when a tool execution completes
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)
High-level statistics about the analysis Total number of assets discovered
Total number of domains found
Count of high-priority targets
Whether the analysis completed successfully
List of all discovered assets (servers, services, endpoints)
Prioritized targets for deep penetration testing
Notable security observations from reconnaissance
Show WhiteboxAttackSurfaceResult (Whitebox)
All applications/services discovered in the codebase Application or service name
Framework in use (e.g., Express, Next.js, Django)
Brief description of the app
Statistics about the whitebox analysis All targets identified for deep penetration testing Show PentestTarget properties
The URL or endpoint to test
Testing objective for this target
Why this target was prioritized
Authentication details if applicable Absolute path to the attack-surface-results.json file
Absolute path to the session’s assets directory
Usage Examples Blackbox Testing
Whitebox Testing
With Authentication
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 } ` );
Blackbox Pentest Full penetration testing workflow
Targeted Pentest Test specific targets and objectives
Authentication Authenticate against a target
