API Overview

​

Introduction

• Attack surface discovery (blackbox and whitebox)
• Authentication testing and credential management
• Targeted penetration testing with custom objectives
• Automated vulnerability patching
• Benchmark comparison for security testing frameworks

​

When to Use the API vs CLI

​

Use the API when:

• Automation: You need to run security tests as part of CI/CD pipelines
• Integration: You’re building security tools or dashboards that need programmatic access
• Custom workflows: You need fine-grained control over agent behavior and callbacks
• Batch processing: You want to test multiple targets or configurations programmatically
• Custom storage: You need to integrate findings with your own database or tracking system

​

Use the CLI when:

• Interactive testing: You want real-time feedback with a rich terminal UI
• Ad-hoc assessments: You’re performing one-off security evaluations
• Learning: You’re exploring features or understanding how agents work
• Operator mode: You need human-in-the-loop approval for tool execution

​

Architecture Overview

​

1. Sessions

• Unique identifier for tracking and resumption
• Directory structure for findings, POCs, logs, and artifacts
• Configuration including auth credentials, scope constraints, and rate limiting
• Credential manager for secure secret handling (secrets never reach the AI model)

import { sessions } from "@pensar/apex/core/session";

const session = await sessions.create({
  name: "API Security Test",
  targets: ["https://api.example.com"],
  config: {
    authCredentials: {
      username: "testuser",
      password: "testpass",
      loginUrl: "https://api.example.com/login"
    },
    scopeConstraints: {
      strictScope: true,
      allowedHosts: ["api.example.com"]
    }
  }
});

​

2. Agents

• Attack Surface Agent (runAttackSurfaceAgent) - Discovers endpoints, assets, and authentication flows
• Authentication Agent (runAuthenticationAgent) - Bypasses login mechanisms and extracts auth tokens
• Targeted Pentest Agent (runTargetedPentestAgent) - Tests specific endpoints for vulnerabilities
• Pentest Agent (runPentestAgent) - Full workflow combining attack surface + targeted testing
• Patching Agent (runPatchingAgent) - Automatically generates and validates security patches
• Benchmark Agent (runBenchmarkComparisonAgent) - Compares results against expected vulnerabilities

• Accepts a model (Claude, GPT-4, etc.) and session
• Streams tool calls and results via callbacks
• Returns typed results with findings and artifact paths
• Supports abort signals for cancellation

​

3. Callbacks

const result = await runPentestAgent({
  target: "https://example.com",
  model: "claude-sonnet-4-20250514",
  session,
  callbacks: {
    onTextDelta: (delta) => {
      // Stream AI reasoning in real-time
      process.stdout.write(delta.text);
    },
    onToolCall: (call) => {
      // Log when tools are invoked
      console.log(`→ calling ${call.toolName}`);
    },
    onToolResult: (result) => {
      // Track tool execution results
      console.log(`✓ ${result.toolName} completed`);
    },
    onError: (error) => {
      // Handle errors gracefully
      console.error("Agent error:", error);
    }
  }
});

​

API Modules

​

Security Considerations

​

Output Structure

~/.pensar/executions/{session-id}/
├── findings/           # Vulnerability reports (JSON)
├── pocs/              # Proof-of-concept scripts
├── logs/              # Execution logs
├── scratchpad/        # Agent working notes
├── assets/            # Screenshots, network captures
├── auth/              # Authentication artifacts
└── session.json       # Session metadata

​

Next Steps