Attack Surface Agents

Overview

Attack surface agents are recon-focused specializations of the OffensiveSecurityAgent that map the entire attack surface of a target. They discover assets, endpoints, authentication flows, and produce a structured list of targets for deep penetration testing.

BlackboxAttackSurfaceAgent

Maps the entire attack surface of a target through blackbox reconnaissance — discovers assets, endpoints, authentication flows, and produces a list of targets for deep testing.

Constructor

new BlackboxAttackSurfaceAgent(opts: AttackSurfaceAgentInput)

opts

AttackSurfaceAgentInput

required

Configuration object for the attack surface agent

AttackSurfaceAgentInput

model

AIModel

required

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

session

SessionInfo

required

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

target

string

The target to analyze (domain, IP, URL, network range, or org name). Either target or cwd must be provided.

cwd

string

Working directory for source-code based analysis. Either target or cwd must be provided.

authConfig

AIAuthConfig

Optional per-provider API key overrides

onStepFinish

StreamTextOnStepFinishCallback<ToolSet>

Callback fired after each agent step

abortSignal

AbortSignal

AbortSignal to cancel the agent mid-run

callbacks

ConsumeCallbacks

Callbacks for stream events and subagent forwarding

findingsRegistry

FindingsRegistry

Shared findings registry for cross-agent dedup

credentialManager

CredentialManager

In-memory credential store for secret-free agent prompts

stopWhen

StopCondition<ToolSet>

Override the default stop condition

Result Type

The consume() method returns an AttackSurfaceResult:

results

AttackSurfaceAnalysisResults | null

The full analysis results (targets, assets, key findings)

targets

PentestTarget[]

All targets identified for deep penetration testing

resultsPath

string

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

assetsPath

string

Absolute path to the session’s assets directory

AttackSurfaceAnalysisResults

summary

AttackSurfaceSummary

High-level summary of the analysis

totalAssets

number

Total number of assets discovered

totalDomains

number

Total number of domains/subdomains found

highValueTargets

number

Number of high-priority targets identified

analysisComplete

boolean

Whether the analysis completed successfully

discoveredAssets

string[]

Array of discovered asset strings (e.g., “example.com - Web server (nginx) - Ports 80,443”)

targets

PentestTarget[]

Structured targets for deep testing

target

string

Target URL or endpoint

objective

string

Testing objective for this target

rationale

string

Why this target was selected

authenticationInfo

AuthenticationInfo

Authentication details if required

method

string

Authentication method (e.g., “cookie”, “bearer”)

details

string

Details about the auth mechanism

credentials

string

Credential reference or ID

string

Cookie string if using cookie auth

headers

string

Additional headers required

keyFindings

string[]

Array of key findings from the analysis (e.g., “[HIGH] Admin panel exposed - admin.example.com”)

Active Tools

The BlackboxAttackSurfaceAgent uses the following tools:

execute_command - Run reconnaissance commands (nmap, dig, curl, etc.)
document_asset - Document discovered assets
create_attack_surface_report - Generate the final analysis report
browser_navigate - Navigate to web pages
browser_snapshot - Capture DOM snapshots
browser_screenshot - Take screenshots for documentation
browser_click - Interact with page elements
browser_fill - Fill form fields
browser_evaluate - Execute JavaScript in the browser context
browser_console - Access browser console logs
browser_get_cookies - Extract cookies from browser
email_list_inboxes - List available email inboxes (if configured)
email_list_messages - List messages in an inbox
email_search_messages - Search for specific messages
email_get_message - Retrieve full message content

Usage Examples

Basic Attack Surface Analysis

import { BlackboxAttackSurfaceAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";

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

const agent = new BlackboxAttackSurfaceAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
});

const { targets, results, resultsPath } = await agent.consume({
  onTextDelta: (delta) => {
    process.stdout.write(delta.text);
  },
  onToolCall: (delta) => {
    console.log(`→ ${delta.toolName}`);
  },
});

console.log(`\nIdentified ${targets.length} targets for deep testing`);
console.log(`Results saved to: ${resultsPath}`);

// Access structured results
if (results) {
  console.log(`Total assets: ${results.summary.totalAssets}`);
  console.log(`Total domains: ${results.summary.totalDomains}`);
  console.log(`High-value targets: ${results.summary.highValueTargets}`);
}

With Authentication Credentials

import { BlackboxAttackSurfaceAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";
import { CredentialManager } from "@pensar/apex/credentials";

const credentialManager = new CredentialManager();
credentialManager.addCredential({
  id: "admin_creds",
  username: "[email protected]",
  password: "secure_password",
  loginUrl: "https://example.com/login",
  role: "admin",
});

const session = await createSession({
  name: "Authenticated Recon",
  targets: ["https://example.com"],
  credentialManager,
});

const agent = new BlackboxAttackSurfaceAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
  credentialManager,
});

const { targets, results } = await agent.consume({
  onTextDelta: (delta) => process.stdout.write(delta.text),
});

console.log(`Found ${targets.length} authenticated targets`);

With Custom Configuration

import { BlackboxAttackSurfaceAgent } from "@pensar/apex";
import { createSession } from "@pensar/apex/session";

const session = await createSession({
  name: "Custom Recon",
  targets: ["https://example.com"],
  config: {
    scopeConstraints: {
      strictScope: true, // Only test allowed hosts
    },
    enumerateSubdomains: true, // Enable subdomain enumeration
    authenticationInstructions: "Use OAuth flow with Google Sign-In",
  },
});

const agent = new BlackboxAttackSurfaceAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
});

const { targets, results } = await agent.consume({
  onTextDelta: (delta) => process.stdout.write(delta.text),
});

Processing Results

import { BlackboxAttackSurfaceAgent } from "@pensar/apex";
import { 
  parseDiscoveredAsset, 
  parseKeyFinding,
  getHighPriorityKeywords 
} from "@pensar/apex/agents/specialized/attackSurface";

const agent = new BlackboxAttackSurfaceAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
});

const { results } = await agent.consume();

if (results) {
  // Parse discovered assets
  const parsedAssets = results.discoveredAssets.map(parseDiscoveredAsset);
  console.log("Assets:", parsedAssets);

  // Parse key findings
  const findings = results.keyFindings.map(parseKeyFinding);
  const criticalFindings = findings.filter(f => f.severity === "CRITICAL");
  console.log("Critical findings:", criticalFindings);

  // Get high-priority targets
  const highPriority = getHighPriorityKeywords(results);
  console.log("High-priority items:", highPriority);

  // Process targets for pentest agents
  for (const target of results.targets) {
    console.log(`\nTarget: ${target.target}`);
    console.log(`Objective: ${target.objective}`);
    console.log(`Rationale: ${target.rationale}`);
    
    if (target.authenticationInfo) {
      console.log(`Auth method: ${target.authenticationInfo.method}`);
    }
  }
}

Loading Previous Results

import { loadAttackSurfaceResults } from "@pensar/apex/agents/specialized/attackSurface";
import { join } from "path";

const resultsPath = join(session.rootPath, "attack-surface-results.json");
const results = loadAttackSurfaceResults(resultsPath);

console.log(`Loaded ${results.targets.length} targets from previous analysis`);

Analysis Phases

The BlackboxAttackSurfaceAgent follows a structured reconnaissance methodology:

Phase 1: Authentication (if credentials provided)

The agent authenticates first if credentials are available, then proceeds with authenticated discovery.

Phase 2: Subdomain Enumeration (if enabled)

DNS brute-force, certificate transparency logs, zone transfers, and passive DNS lookup.

Phase 3: Asset Discovery

Port scanning, service enumeration, technology detection, and web crawling.

Phase 4: Endpoint Discovery

JavaScript extraction, API endpoint discovery, sitemap parsing, and robots.txt analysis.

Phase 5: Target Selection

Analysis of discovered assets to identify high-value targets for deep penetration testing.

Phase 6: Report Generation

Creates structured JSON report with all findings and pentest targets.

Scope Configuration

Control reconnaissance scope through session configuration:

const session = await createSession({
  name: "Strict Recon",
  targets: ["https://example.com"],
  config: {
    scopeConstraints: {
      strictScope: true,
      allowedHosts: ["example.com", "*.example.com"],
      allowedPorts: [80, 443, 8080],
    },
  },
});

Helper Functions

parseDiscoveredAsset()

Parse a discovered asset string into structured data.

function parseDiscoveredAsset(asset: string): {
  identifier: string;
  description: string;
  details?: string;
}

parseKeyFinding()

Parse a key finding string into severity and description.

function parseKeyFinding(finding: string): {
  severity: string;
  description: string;
}

getHighPriorityKeywords()

Extract high-priority findings (CRITICAL and HIGH severity).

function getHighPriorityKeywords(results: AttackSurfaceAnalysisResults): string[]

extractPentestTargets()

Extract simplified target objects for orchestration.

function extractPentestTargets(results: AttackSurfaceAnalysisResults): Array<{
  target: string;
  objective: string;
}>

Best Practices

Authentication First: If credentials are provided, the agent authenticates before running any reconnaissance commands.

Subdomain Enumeration: Only enable enumerateSubdomains when you have permission to perform active DNS enumeration on the target domain.

Scope Control: Use strictScope: true for bug bounty programs with defined scope. Use strictScope: false for comprehensive red team assessments.

API Overview

Core APIs

Agents

Attack Surface Agents

Overview

BlackboxAttackSurfaceAgent

Constructor

AttackSurfaceAgentInput

Result Type

AttackSurfaceAnalysisResults

Active Tools

Usage Examples

Basic Attack Surface Analysis

With Authentication Credentials

With Custom Configuration

Processing Results

Loading Previous Results

Analysis Phases

Scope Configuration

Helper Functions

parseDiscoveredAsset()

parseKeyFinding()

getHighPriorityKeywords()

extractPentestTargets()

Best Practices

Build docs developers (and LLMs) love

API Overview

Core APIs

Agents

​Overview

​BlackboxAttackSurfaceAgent

​Constructor

​AttackSurfaceAgentInput

​Result Type

​AttackSurfaceAnalysisResults

​Active Tools

​Usage Examples

​Basic Attack Surface Analysis

​With Authentication Credentials

​With Custom Configuration

​Processing Results

​Loading Previous Results

​Analysis Phases

​Scope Configuration

​Helper Functions

​parseDiscoveredAsset()

​parseKeyFinding()

​getHighPriorityKeywords()

​extractPentestTargets()

​Best Practices

​Related

Build docs developers (and LLMs) love

Overview

BlackboxAttackSurfaceAgent

Constructor

AttackSurfaceAgentInput

Result Type

AttackSurfaceAnalysisResults

Active Tools

Usage Examples

Basic Attack Surface Analysis

With Authentication Credentials

With Custom Configuration

Processing Results

Loading Previous Results

Analysis Phases

Scope Configuration

Helper Functions

parseDiscoveredAsset()

parseKeyFinding()

getHighPriorityKeywords()

extractPentestTargets()

Best Practices

Related