Offensive Security Agent API

Run the general-purpose offensive security agent directly

The Offensive Security Agent API provides direct access to the base agent that powers all other specialized agents in Pensar Apex.

runOffensiveSecurityAgent

Runs the general-purpose offensive security agent with a custom prompt and tools.

This is a low-level API intended for advanced use cases. Most users should use higher-level APIs like runPentestAgent or runTargetedPentestAgent.

Import

import { runOffensiveSecurityAgent } from '@pensar/apex';
import type { StreamTextResult, ToolSet } from 'ai';

Function Signature

async function runOffensiveSecurityAgent(
  input: OffensiveSecurityAgentInput
): Promise<StreamTextResult<ToolSet, never>>

Parameters

input · OffensiveSecurityAgentInput · required

Configuration for the offensive security agent.

Show OffensiveSecurityAgentInput

session · SessionInfo · required

Session information for storing results:

• id: Unique session identifier
• rootPath: Session root directory
• findingsPath: Path for findings
• logsPath: Path for logs
• pocsPath: Path for POCs

objective · string · required

Testing objective or goal.

target · string

Target URL, domain, or IP (optional).

model · AIModel

AI model to use (default: claude-sonnet-4-5).

tools · ToolSet

Custom tools to make available to the agent.

systemPrompt · string

System prompt to guide agent behavior.

authConfig · AIAuthConfig

AI provider authentication.

callbacks · ConsumeCallbacks

Event handlers for agent execution.

Return Value

result · StreamTextResult<ToolSet, never>

AI SDK stream result containing:

• text: Generated text stream
• toolCalls: Invoked tool calls
• toolResults: Tool execution results
• finishReason: Why the agent stopped
• usage: Token usage statistics

Example Usage

Basic Agent Execution

import { runOffensiveSecurityAgent } from '@pensar/apex';
import { sessions } from '@pensar/apex';

const session = await sessions.create({
  name: 'Custom Agent Test',
  targets: ['https://example.com']
});

const stream = await runOffensiveSecurityAgent({
  session: {
    id: session.id,
    rootPath: session.rootPath,
    findingsPath: session.findingsPath,
    logsPath: session.logsPath,
    pocsPath: session.pocsPath
  },
  objective: 'Test for XSS vulnerabilities',
  target: 'https://example.com',
  model: 'claude-sonnet-4-5',
  callbacks: {
    onTextDelta: (d) => process.stdout.write(d.text),
    onToolCall: (d) => console.log(`→ ${d.toolName}`),
    onToolResult: (d) => console.log(`✓ Completed`),
    onError: (e) => console.error('Error:', e)
  }
});

// Access stream result
const { text, toolCalls, usage } = await stream.result;
console.log(`\nTokens used: ${usage.totalTokens}`);

Custom Tools

Provide custom tools to the agent:

import { runOffensiveSecurityAgent } from '@pensar/apex';
import { tool } from 'ai';
import { z } from 'zod';

const customTools = {
  analyzeResponse: tool({
    description: 'Analyze HTTP response for security issues',
    parameters: z.object({
      url: z.string(),
      responseBody: z.string()
    }),
    execute: async ({ url, responseBody }) => {
      // Custom analysis logic
      return {
        issues: ['XSS', 'Missing CSP header'],
        severity: 'HIGH'
      };
    }
  })
};

const stream = await runOffensiveSecurityAgent({
  session: sessionInfo,
  objective: 'Analyze security headers',
  target: 'https://example.com',
  tools: customTools,
  callbacks: {
    onTextDelta: (d) => process.stdout.write(d.text)
  }
});

Custom System Prompt

Provide custom guidance:

const customPrompt = `
You are a security researcher specializing in API security.
Focus on:
- Authentication and authorization flaws
- API rate limiting
- Input validation
- Data exposure

Always document findings with clear evidence and remediation steps.
`;

const stream = await runOffensiveSecurityAgent({
  session: sessionInfo,
  objective: 'Audit API security',
  target: 'https://api.example.com',
  systemPrompt: customPrompt,
  model: 'claude-opus-4'
});

Processing Stream Results

Access detailed stream data:

const stream = await runOffensiveSecurityAgent({
  session: sessionInfo,
  objective: 'Test target',
  target: 'https://example.com'
});

// Wait for completion
const result = await stream.result;

console.log('Generated text:', result.text);
console.log('Tool calls:', result.toolCalls.length);
console.log('Finish reason:', result.finishReason);
console.log('Usage:', {
  input: result.usage.promptTokens,
  output: result.usage.completionTokens,
  total: result.usage.totalTokens
});

When to Use This API

Use runOffensiveSecurityAgent when you need:

Custom agent behavior

Define specialized testing workflows not covered by built-in agents.

Custom tools

Integrate your own security tools or APIs with the agent.

Fine-grained control

Full control over system prompts, tools, and execution flow.

Research and experimentation

Test new attack techniques or analysis approaches.

For most pentesting scenarios, use the higher-level APIs:

• runPentestAgent for full pentests
• runTargetedPentestAgent for focused testing
• runAttackSurfaceAgent for discovery

Limitations

This API requires:

• Manual session management
• Custom tool definitions
• Understanding of agent architecture
• Proper error handling

It does not provide:

• Built-in attack surface discovery
• Automatic finding deduplication
• Report generation
• Multi-agent orchestration

Related

OffensiveSecurityAgent Class

Base agent class documentation

Pentest Agent

Specialized pentest agent

Agents Concept

Understanding the agent architecture

Sessions

Managing agent sessions