DOCSEARCHbyAlgolia
Submit Docs

Pensar Apex

repository·canary·Indexed 43 days ago

https://github.com/pensarai/apex

AI-powered penetration testing CLI tool with a terminal UI that uses autonomous agents for blackbox and whitebox security testing. Version 2.5.0 includes bundled wordlists for discovery tools, a Kali-based container environment, and the Argus benchmark suite for validating agent performance across single-vulnerability targets and multi-step attack chains.

Tokens
83.2K
Snippets
239
Records
407
Agent score
55%

What's inside Apex

  1. Overview of Apex Benchmarks

    canary
    The benchmarks directory contains evaluation results for Apex, measuring its performance against known-vulnerable applications. These benchmarks are used to validate the effectiveness of Apex in various security testing scenarios.

  2. Overview of Pensar Apex users and environments

    canary

    Pensar Apex is designed for professional pentesters, security engineers, and developers. It is intended to be used across various environments, including:

    • Local terminals
    • Remote hosts
    • Containers
    • CI environments

    Apex enables users to run and steer authorized security testing through two primary interfaces: a Terminal UI (TUI) for interpretable and steerable agent activity, and a headless CLI for automation and integrations.

  3. Overview of Argus Benchmark Suite

    canary

    Argus is a validation suite consisting of 60 benchmarks designed to evaluate AI-powered penetration testing tools. Each benchmark is implemented as a self-contained Docker Compose environment containing intentionally planted vulnerabilities and a defined set of expected findings.

    Benchmark Categories

    • Single-vulnerability targets (001-040): Focuses on identifying a specific vulnerability class (e.g., SSRF, SQLi, XSS, JWT confusion) amidst noise.
    • Intermediate targets (023, 030, 034, 040): Involves multiple vulnerabilities or more complex exploitation paths.
    • Multi-step attack chains (041-060): Requires sequential exploitation across multiple services in a Docker environment. Success requires executing the complete chain rather than finding a single vulnerability.

  4. Manage the attack surface with `pensar apps`

    canary

    The pensar apps command allows you to manage your workspace's attack surface, which consists of apps and their associated endpoints. You can list, view, create, update, and delete these entities via the Pensar Console API.

    Important Scoping Note: All commands operate on the selected workspace determined by your current pensar login session. Apps and endpoints are scoped to that workspace; there is no --project argument.

    # Basic usage overview
pensar apps                                   # List apps
pensar apps get <appId>                        # Show app details
pensar apps create [options]                   # Create an app
pensar apps update <appId> [options]           # Update an app
pensar apps delete <appId>                     # Delete an app
pensar apps domains                            # List workspace domains
pensar apps domain-create <domain>             # Create/resolve a domain
pensar apps endpoints <appId> [filters]        # List an app's endpoints
pensar apps endpoint <endpointId>              # Show endpoint details
pensar apps endpoint-create <appId> [options]  # Create an endpoint
pensar apps endpoint-update <endpointId> [options]  # Update an endpoint
pensar apps endpoint-delete <endpointId>       # Delete an endpoint
pensar apps search <query> [options]           # Substring-search apps
pensar apps search-endpoints <query> [options] # Substring-search endpoints

  5. What is removed and preserved during uninstall

    canary

    When running pensar uninstall, the system targets specific components based on your installation method and data location.

    Removed Components

    • Binary/Package: Depending on how you installed it, the command runs npm uninstall -g @pensar/apex, brew uninstall pensarai/tap/apex, or deletes the standalone binary file.
    • Data Directory (~/.pensar/): Configuration files, auth tokens, and cached data are deleted.

    Preserved Components

    The following directories under ~/.pensar/ are kept to prevent loss of work:

    • sessions/: Pentest and operator session data.
    • memories/: Agent memory and context.
    • skills/: Custom operator skills.

  6. Overview of Apex architectural decisions

    canary

    Apex's architecture is shaped by several key product and technical decisions, including:

    • Interface: A Terminal UI (TUI) approach rather than a web app or purely headless CLI.
    • Interaction Modes: Two distinct modes: /pentest for automated testing and /operator for interactive engagement.
    • Agent Architecture: A specialized sub-agent architecture using swarm orchestration.
    • Methodology: A rigid 7-step methodology implemented in the TargetedPentestAgent.
    • Data Management: A shared findings registry for tracking security issues.
    • Extensibility: A public API layer that is decoupled from the TUI, and support for multi-provider AI models.
    • Telemetry: Inference telemetry is treated as a physical-attempt contract rather than a billing ledger.

  7. Understand the Apex interface options

    canary

    Apex provides two primary ways to interact with autonomous pentest agents:

    1. Terminal UI (TUI): The primary interactive interface built with OpenTUI. It is designed for real-time, live-streaming output such as recon discoveries, swarm agent logs, and finding alerts. It is ideal for security practitioners working in native terminal environments like Kali VMs, SSH jump hosts, or Docker containers.
    2. Headless CLI: A programmatic interface designed for scripting, CI/CD integration, and invocation from other coding agents or AI skills. It provides the same agent capabilities as the TUI but without a terminal renderer.

    Use the TUI when you need to monitor and steer an autonomous run in real time, and use the CLI when you need to automate tasks or integrate Apex into a pipeline.

  8. How Pensar credits work

    canary

    Credits are a pre-paid balance (denominated in USD) stored at the workspace level in Pensar Console.

    Usage and Billing

    • Billing Category: Apex Inference.
    • Pricing: Calculated as the Base model cost + 15% Pensar markup.
    • Consumption: Each AI request deducts from the balance based on the model used and tokens consumed.
    • Attribution: Requests are tracked per-user based on your authenticated identity.
    • Insufficient Funds: Requests are automatically rejected if the workspace balance is insufficient.

    Important Note

    Credits are shared across all billing categories in your workspace (e.g., Apex Inference and Continuous Pentesting). You can monitor usage per category in the Pensar Console under Settings > Usage.

  9. How findings are collected and reported in Apex

    canary

    In /pentest mode, Apex uses a centralized, shared findings registry located in src/core/findings/. Instead of agents returning results in batches at the end of an engagement, all TargetedPentestAgents write their discoveries to this registry in real time.

    This architecture provides several key behaviors:

    • Automatic Deduplication: The registry deduplicates findings at write time. If multiple agents discover the same vulnerability, the registry preserves only the strongest evidence for that unique finding.
    • Real-time Visibility: Because findings flow through a shared, observable store, the pentest dashboard (TUI) can display findings as they are discovered rather than waiting for agents to finish.
    • Single Source of Truth: The report generator reads exclusively from this registry, ensuring consistent output and avoiding the need to merge disparate agent schemas or confidence levels.

  10. How Argus scoring and metrics work

    canary

    Argus uses an LLM-based scorer to compare an agent's findings against a set of expected findings using semantic matching. A finding is considered "matched" if it describes the same vulnerability class at the same location, regardless of exact wording.

    Scoring Formulas

    • Recall = matched expected findings / total expected findings
    • Precision = matched expected findings / total actual findings reported

    Status Definitions

    • success: At least one expected finding was matched.
    • missed: The agent completed the run but matched zero expected findings.
    • failed: The run crashed or could not complete.

  11. How to consume Apex agent capabilities via the Public API

    canary

    Apex provides a public API layer located at src/core/api/ that exposes all agent capabilities (such as attack surface mapping, targeted pentesting, and authentication analysis) independently of the Terminal User Interface (TUI).

    Developers can use this API to:

    • Integrate Apex agents into automated CI/CD pipelines.
    • Build third-party security tools or platforms by embedding individual agents (e.g., auth agent, attack surface agent, or pentest swarm).
    • Programmatically trigger specific agent tasks without launching the interactive TUI.

    The agent stubs are designed to be independently instantiated and composed, making them suitable for headless environments like Pensar Console or custom SDK implementations.

  12. Understand the Bundled Wordlists in Apex

    canary

    Apex ships with a set of bundled wordlists to ensure the agent can reliably use the -w argument for discovery tools (like gobuster, ffuf, dirb, wfuzz, and dirsearch) across different operating systems (macOS, Alpine, vanilla Linux, Docker). This prevents the agent from failing due to hardcoded paths like /usr/share/wordlists/dirb/common.txt which are specific to Kali Linux.

    There are three tiers of wordlists available, and the agent selects a tier based on signals such as time budget, user intent, and the completeness of prior reconnaissance. Note that the agent does not automatically chain tiers; it picks one based on the current context.