SecAgent

<p align="center"> <img src="docs/assets/secagent_logo.png" alt="SecAgent Logo" width="380"> </p>

Authorized offensive security assessment toolkit

SecAgent combines scoped discovery, bounded HTTP checks, proof replay, optional browser inspection, and operator-controlled identity, state, and callback workflows. Findings and manual leads are reported separately.

---

</div>

---

LEGAL DISCLAIMER — SecAgent is designed exclusively for authorized security testing, red team engagements, and vulnerability research on systems you own or have explicit written permission to test. Unauthorized use against systems without permission is illegal. The authors assume no liability for misuse.

---

Table of Contents

• What Is SecAgent
• Key Differentiators
• Capabilities Matrix
• Comprehensive System Architecture
  • 1. High-Level System Topology & Polyglot Engine
  • 2. Autonomous Scan Lifecycle Sequence
  • 3. Multi-Agent Swarm Decision Logic
  • 4. Multi-Provider LLM Fallback & Consensus Engine
• Quick Start Guide
• Installation Guide
  • Prerequisites
  • Method 1 — Automated Installation Engine (Recommended)
  • Method 2 — Manual Package Installation
• Releases, Deployments & Packages
  • Releases
  • Deployment Models
  • Package Artifacts
• Configuration & Operational Manifest
• Complete CLI Usage Reference
  • Subcommand Specifications & Flags
• Sample Deliverables & Deliverable Schemas
  • 1. Executive Markdown Deliverable
  • 2. Machine-Readable JSON Schema
• Project Directory Layout
• Troubleshooting & Operations Guide
• Contributing & Security Policy
• License

---

What Is SecAgent

SecAgent is a CLI toolkit for authorized security assessments. The default pipeline discovers scoped web routes, imports read-only API requests, runs bounded checks, and replays supported findings under explicit proof policies. Optional agents and native components provide additional workflows, but their presence in the repository does not imply that they run in the bounded default pipeline.

Built for:

• Red Teams operating within an approved scope and traffic budget
• Security Researchers examining web and API attack surfaces
• Bug Bounty Hunters reviewing candidate issues and proof evidence
• Offensive AI Researchers auditing AI supply chains, prompt injections, and RAG pipelines

---

Key Differentiators

1. Pure CLI-First Architecture: No bloated web UI or complex database setup required. Designed for headless VPS execution, Docker containers, SSH sessions, and CI/CD pipelines.
2. Optional Native Components: Go, Rust, and C++ components exist in the repository; the bounded Python default scan does not depend on all of them.
3. Aura Cognitive Memory Engine: Target DNA layering, payload pattern crystallization, decay-reinforcement mechanisms, and WAF fingerprint memory across scan missions (secagent memory).
4. Typed Live Validation: CrucibleValidator replays supported checks and compares active probes with an unmodified control. XSS uses a scoped real-browser canary replay. Identity, state and SSRF proof require explicit operator contracts.
5. Bounded Built-in Traffic: Shared request count, per-host rate, concurrency, and deadline limits cover built-in discovery, checks, and proof replay.
6. Headless Browser Inspection: BrowserAgent automated Chrome DOM extraction & dynamic Playwright form parsing with fallback HTTP inspection.
7. TLS Verification: The default HTTP scan verifies TLS unless --insecure is set.
8. Hardware-Aware Local Fallback: Automatically detects GPU/CPU capabilities to provision local Ollama models (llama3, mistral, codellama) when cloud APIs are unavailable.
9. Model Context Protocol (MCP) Server Mode: Native JSON-RPC stdio server (secagent mcp) allowing Claude Code, Cursor, and VS Code Copilot to drive SecAgent with zero API cost.
10. Declarative YAML Playbooks: Define and version-control complex pentesting methodologies with conditional rules and LLM decision gates (secagent playbook).
11. Proof Capsule Replay Engine: Replay a supplied typed .json proof capsule with secagent replay. The scan pipeline does not yet generate capsules automatically.
12. Human-In-The-Loop (HITL) Teleoperation: Intercept double Ctrl+C during scan execution to drop into an interactive operator REPL (step, inspect, inject, resume, abort).
13. LLM Budget Guard & Cost Safeguard: Real-time token cost accounting and configurable budget limit enforcement (SECAGENT_PRICE_LIMIT).

---

Capabilities Matrix

| Module | Sub-Components | Operational Description | |--------|----------------|-------------------------| | Neural Swarm Orchestration | Orchestrator, ArmadaSwarm, TaskDAG | Decomposes high-level objectives into directed acyclic execution graphs (DAGs) with retry and circuit breaker logic. | | MCP Server Mode | MCPServer, JSON-RPC stdio | Exposes SecAgent tools to Claude Code, Cursor, and Copilot via Model Context Protocol (secagent mcp). | | Declarative Playbooks | Playbook, PlaybookRunner | Executes YAML-defined scanning methodologies with dependency ordering and conditional execution (secagent playbook). | | Proof Capsules & Replay | ProofCapsule, ProofCapsuleReplayer | Serializes supplied capsules and replays registered typed checks under scope and request limits. Authenticated capsules use environment references for session headers. | | HITL Teleoperation | TeleoperationController | Intercepts double Ctrl+C to pause scan and launch interactive REPL shell. | | LLM Cost Safeguard | BudgetGuard | Real-time token pricing and cost limit enforcement across OpenAI, Anthropic, Gemini, Groq, and OpenRouter. | | Aura Cognitive Memory | AuraMemoryManager, Target DNA | Target DNA fingerprinting, WAF memory, payload pattern crystallization, automatic confidence reinforcement & decay (secagent memory). | | Active Recon Engine | ReconAgent, GoRecon, httpx Prober | Scoped HTTP probing, bounded subdomain checks, HTML link and form parameter discovery. | | Headless Browser Engine | BrowserAgent, Playwright | Chromium DOM tree inspection, dynamic JS error tracking, and automated HTML form input extraction. | | Web Security Scanner | CVEScanner, CVEChecks | Check catalog with typed policies; unsupported or capability-dependent checks remain manual leads or coverage gaps. | | API Inventory | OpenAPI, Swagger, HAR | Preserves methods and bodies in memory; default active probes use GET templates only. Stateful writes require an explicit contract. | | Bounded Fuzzing | Binary input mutator, GET payload variants, AURA feedback | Mutates local input files, records byte and bit changes plus program outcomes, and optionally tests encoded GET variants under the shared scan budget and proof policy. | | 12 Specialized Swarm Agents | specialized.py | Functional AI swarm agents for intelligent tool selection, CTF challenge solving, exploit generation, vulnerability correlation, and rate-limit detection. | | Web3 & Contract Auditor | Web3SecurityAgent | EVM & Solana smart contract security analysis for reentrancy, integer overflow, delegatecall vulnerabilities, and access control bypasses. | | PoC Verification | CrucibleValidator | Typed replay, controls, and evidence hashes for supported checks. This reduces unproven findings but does not establish a zero false-positive rate. | | Exploit Chain Correlation | ChainCorrelator | Suggests hypotheses for operator review; a chain is not proof of exploitability. | | Impact-First Reporting | ReportAgent | Generates executive Markdown reports and machine-readable JSON artifacts. |

---

Comprehensive System Architecture

The diagrams below show repository components and optional integrations. They are not a claim that every component executes during secagent scan; the bounded default path is the Python scan pipeline described above.

1. High-Level System Topology & Polyglot Engine

graph TB
    subgraph CLI_LAYER["🖥️ CLI & Interface Control Plane"]
        CLI["secagent CLI (Rich TUI)"]
        MCP["🔌 MCPServer (JSON-RPC stdio)"]
        PLAYBOOK["📜 Playbook Engine (YAML Methodologies)"]
        CAPSULE["📦 Proof Capsule Engine & Replayer"]
        HITL["🕹️ Teleoperation Controller (Double Ctrl+C)"]
        BUDGET["💰 BudgetGuard (Token & Cost Accounting)"]
        SCOPE["Scope Gate (Fail-Closed Enforcer)"]
        VAULT["Vault Key Manager (.env Loader)"]
        PREFLIGHT["Preflight Integrity Checker"]
    end

    subgraph MEMORY_LAYER["🧠 Cognitive Memory Subsystem"]
        AURA["AuraMemoryManager (Target DNA & Pattern Engine)"]
        DB[("💾 SQLite / aura-memory SDK Database")]
    end

    subgraph SWARM_LAYER["🐝 Python Agent Swarm"]
        PLANNER["🎯 Planner Agent (Armada DAG Builder)"]
        RECON["🔍 Recon Agent (httpx + Async Prober)"]
        WEB["🌐 Web Security Agent"]
        API["⚡ API Security Agent"]
        WEB3["🕸️ Web3 Security Agent"]
        VALIDATOR["🔬 Validator Agent (Crucible)"]
        REPORTER["📊 Report Agent"]
    end

    subgraph ENGINE_LAYER["⚙️ Polyglot Core Engine"]
        CPP["⚡ C/C++ Foundational Core (cpp-core)"]
        RUST["🦀 Rust Engine & Priority Scheduler"]
        GO["🐹 Go Subdomain & Network Prober"]
        REDIS[("🔴 Redis Pub/Sub Event Bus")]
    end

    CLI --> SCOPE
    MCP --> SCOPE
    PLAYBOOK --> SCOPE
    CAPSULE --> VALIDATOR
    HITL --> SWARM_LAYER
    BUDGET --> SWARM_LAYER
    SCOPE --> PREFLIGHT
    PREFLIGHT --> VAULT
    VAULT --> PLANNER
    AURA <--> DB
    PLANNER <-->|Recall Target DNA| AURA
    PLANNER --> RECON
    PLANNER --> WEB
    PLANNER --> API
    PLANNER --> WEB3
    RECON --> GO
    RECON --> RUST
    RECON --> CPP
    SWARM_LAYER --> REDIS
    SWARM_LAYER --> VALIDATOR
    VALIDATOR -->|Export Proof Capsule| CAPSULE
    VALIDATOR -->|Crystallize Exploits| AURA
    VALIDATOR --> REPORTER

---

5. C/C++ Foundational Core Engine (cpp-core) & Native Bridge Demonstration

SecAgent incorporates a compiled C++20 Foundational Core (cpp-core) for sub-millisecond execution tasks, SIMD-accelerated regex/signature matching, and asynchronous raw socket probing.

C++ Core Architecture Topology

graph LR
    subgraph PYTHON_BRIDGE["🐍 Python Native Bridge"]
        PY_NATIVE["secagents.core.native"]