Overview The Targeted Pentest API provides focused penetration testing capabilities for specific targets and objectives. Unlike the full workflow, this API allows you to test individual endpoints or features with precise testing goals.
Key Features:
Focused testing on specific targets
Custom testing objectives per target
Automatic PoC script generation
Finding deduplication across runs
Sandbox support for isolated execution
Browser automation for complex testing scenarios
runTargetedPentestAgent Run a targeted penetration test against a specific target with defined objectives.
Testing Methodology:
PLAN : State objectives and outline testing approachVERIFY : Confirm target is reachable and understand baseline behaviorPREPARE : Research payloads and attack techniquesTEST : Execute targeted attacks methodicallyEXPLOIT : Create proof-of-concept scriptsDOCUMENT : Document confirmed vulnerabilitiesFINISH : Submit final summary
import { runTargetedPentestAgent } from '@pensar/apex/api/targetedPentest' ; const result = await runTargetedPentestAgent ({ target: 'https://api.example.com/users' , objectives: [ 'Test for SQL injection vulnerabilities' , 'Check for authentication bypass' , 'Test for broken access control' , ], model: 'claude-sonnet-4-20250514' , session: sessionInfo , }); console . log ( `Found ${ result . findings . length } vulnerabilities` );
Parameters input
PentestAgentInput
required
Configuration for the targeted pentest agent Show PentestAgentInput properties
The URL or host to test (e.g., "https://api.example.com/users")
One or more testing objectives. Each should be specific and actionable. Examples:
"Test for SQL injection on /api/users""Check authentication bypass via JWT manipulation""Test IDOR on user profile endpoints""Test for XSS in search functionality" AI model identifier (e.g., "claude-sonnet-4-20250514")
Session object providing paths for findings, POCs, logs, etc.
When set, tools execute inside this sandbox instead of locally. Useful for isolated testing environments.
Shared findings registry for cross-agent deduplication. When provided, the agent checks for duplicate vulnerabilities before documenting.
Optional per-provider API key overrides
AbortSignal to cancel the agent mid-run
onStepFinish
StreamTextOnStepFinishCallback
Callback fired after each agent step completes
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
Response All vulnerability findings discovered during the test severity
'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW'
Severity level
Detailed description of the vulnerability
Impact assessment and potential consequences
Evidence demonstrating the vulnerability (logs, screenshots, responses)
Path to the proof-of-concept exploit script
Recommended remediation steps
External references (CVEs, CWEs, documentation) - optional
Absolute path to the session’s findings directory where JSON reports are stored
Absolute path to the session’s POC scripts directory
Usage Examples Basic Usage
With Authentication
With Findings Registry
With Progress Monitoring
With Sandbox Isolation
import { runTargetedPentestAgent } from '@pensar/apex/api/targetedPentest' ; import { createSession } from '@pensar/apex/session' ; const session = await createSession ({ name: 'API Security Test' , targets: [ 'https://api.example.com' ], }); const result = await runTargetedPentestAgent ({ target: 'https://api.example.com/users' , objectives: [ 'Test for SQL injection in search parameter' , 'Check for broken access control on user updates' , ], model: 'claude-sonnet-4-20250514' , session , }); console . log ( `Found ${ result . findings . length } vulnerabilities` ); result . findings . forEach (( finding ) => { console . log ( `[ ${ finding . severity } ] ${ finding . title } ` ); console . log ( ` PoC: ${ finding . pocPath } ` ); });
Testing Guidelines Writing Effective Objectives Objectives should be specific, actionable, and focused:
Good objectives:
"Test SQL injection in username parameter on login endpoint""Check for authentication bypass via JWT token manipulation""Test for IDOR vulnerabilities on user profile update (PUT /api/users/:id)""Test XSS in post content and comment fields"
Avoid vague objectives:
"Test the API" (too broad)"Find vulnerabilities" (not actionable)"Security test" (no specific target)
Available Testing Capabilities The agent has access to these testing tools:
execute_command : Run shell commands (curl, custom scripts, exploit tools)http_request : Make HTTP requests with custom headers/bodybrowser_navigate : Load pages in a headless browserbrowser_click : Interact with buttons and linksbrowser_fill : Fill form fieldsbrowser_screenshot : Capture visual evidencedocument_vulnerability : Document confirmed findingscreate_poc : Generate proof-of-concept exploit scripts
Authentication Handling If the session has authentication data (from prior auth or manual setup):
The agent automatically includes cookies and headers in all requests
Authentication is preserved across HTTP requests and browser actions
Session expiration is detected and reported
Blackbox Pentest Full workflow with discovery + exploitation
Attack Surface Discover targets before testing
Authentication Authenticate before testing
Patching Generate patches for findings
