Skip to main content
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.

​
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:
Define specialized testing workflows not covered by built-in agents.
Integrate your own security tools or APIs with the agent.
Full control over system prompts, tools, and execution flow.
Test new attack techniques or analysis approaches.
For most pentesting scenarios, use the higher-level APIs:

​
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

OffensiveSecurityAgent Class

Base agent class documentation

Pentest Agent

Specialized pentest agent

Agents Concept

Understanding the agent architecture

Sessions

Managing agent sessions

Build docs developers (and LLMs) love

Get started for freeTalk to us