> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pensarai/apex/llms.txt
> Use this file to discover all available pages before exploring further.
# 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)
```typescript theme={null}
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
Configuration for the attack surface agent
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
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
Callback fired after each agent step completes
### Response
The full analysis results with discovered assets and key findings
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
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
Path to the app root
Web pages and routes
API endpoints
Statistics about the whitebox analysis
Number of apps found
Total web pages
Total API endpoints
All targets identified for deep penetration testing
The URL or endpoint to test
Testing objective for this target
Why this target was prioritized
Authentication details if applicable
Authentication method
Additional auth details
Credential reference ID
Session cookies
Required headers
Absolute path to the attack-surface-results.json file
Absolute path to the session's assets directory
***
## Usage Examples
```typescript Blackbox Testing theme={null}
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}`);
```
```typescript Whitebox Testing theme={null}
import { runAttackSurfaceAgent } from '@pensar/apex/api/attackSurface';
import { createSession } from '@pensar/apex/session';
// Create session
const session = await createSession({
name: 'Codebase Analysis',
targets: ['https://staging.example.com'],
});
// Run whitebox attack surface analysis
const result = await runAttackSurfaceAgent({
target: 'https://staging.example.com',
cwd: '/path/to/project', // Enables whitebox mode
model: 'claude-sonnet-4-20250514',
session,
});
if ('apps' in result) {
console.log(`Analyzed ${result.summary.totalApps} applications`);
console.log(`Found ${result.summary.totalApiEndpoints} API endpoints`);
}
```
```typescript With Authentication theme={null}
import { runAttackSurfaceAgent } from '@pensar/apex/api/attackSurface';
import { createSession } from '@pensar/apex/session';
// Create session with credentials
const session = await createSession({
name: 'Authenticated Scan',
targets: ['https://app.example.com'],
config: {
authCredentials: {
username: 'testuser',
password: 'testpass',
loginUrl: 'https://app.example.com/login',
},
},
});
// Agent will automatically authenticate before scanning
const result = await runAttackSurfaceAgent({
target: 'https://app.example.com',
model: 'claude-sonnet-4-20250514',
session,
});
```
***
## Related APIs
Full penetration testing workflow
Test specific targets and objectives
Authenticate against a target