Cybermes

Autonomous Offensive Security & Bug Bounty Automation Framework

Installation • Architecture • Why Cybermes? • Features • Workspace Structure • Toolchain • Documentation

Installation & Setup

Cybermes can be used directly through your AI assistant via Model Context Protocol (MCP) or executed as a standalone CLI / pipeline.

1. MCP Server Installation (Recommended for AI Workflows)

Cybermes includes a high-performance native Go MCP server (cybermes-mcp) that exposes 10+ security tools and context providers directly to AI coding environments (Google Antigravity / Gemini, Kilo Code, Cursor, Claude Desktop, Windsurf, Cline, Roo Code, OpenCode, Claude Code CLI, Continue.dev, Zed, Hermes, and Codex).

Universal Auto-Installer (1-Click)

# Auto-detect and configure all installed AI clients
npx -y cybermes-mcp install

# Install ONLY to specific AI providers:
npx -y cybermes-mcp install --kilo
npx -y cybermes-mcp install --gemini --cursor

Global Installation (No NPX Startup Latency)

npm install -g cybermes-mcp
cybermes-mcp install --global

Local Interactive MCP Manager & Optimizer

# Windows
.\mcp.bat            # or .\mcp.ps1

# Linux / macOS
./mcp.sh             # or python3 scripts/mcp.py

Manual Client Configuration

To manually register the MCP server in your client configuration (mcpServers section):

{
  "mcpServers": {
    "cybermes": {
      "command": "npx",
      "args": ["-y", "cybermes-mcp"]
    }
  }
}

For client-specific paths, direct flags (--kilo, --gemini, --global, --dry-run), and native binary setup, see the MCP Integration Guide.

2. Standalone CLI Installation

If you plan to run Cybermes directly from the terminal or in headless CI/CD pipelines:

Windows (Native PowerShell)

# Clone repository and execute installer
git clone https://github.com/Zyrexnn/Cybermes.git
cd Cybermes
.\setup_windows.ps1

# Configure environment variables and API keys
notepad .env

(For WSL2 or manual setups, refer to the Windows Installation Guide)

Linux / macOS

# Clone repository and execute installer
git clone https://github.com/Zyrexnn/Cybermes.git
cd Cybermes
./setup.sh

# Configure environment variables and API keys
nano .env

Docker Container

git clone https://github.com/Zyrexnn/Cybermes.git && cd Cybermes
cp .env.example .env && nano .env
docker compose up -d

3. Environment Health Check

Verify system dependencies, path bindings, and tool integrity:

# Run environment diagnostics
python tools/doctor.py

# Automatically resolve and repair missing components
python tools/doctor.py --fix

4. Running an Assessment

# Linux / macOS
./cybermes "Assess https://example.com"

# Windows
.\cybermes.bat "Assess https://example.com"

# Docker
docker compose exec cybermes cybermes "Assess https://example.com"

Local Testing: Run the included mock vulnerable application in examples/:

python examples/mock_vulnerable_app.py   # Starts mock app on http://127.0.0.1:8888
./cybermes "Assess http://127.0.0.1:8888"

Architecture & Operational Pipeline

Cybermes provides two distinct operational workflows tailored to different execution environments:

1. Autonomous Hermes CLI Workflow: Fully autonomous terminal/headless execution where the local Hermes engine reasons, spawns subprocesses, filters streaming outputs via smart_pipe, and executes validation loops directly on the OS.
2. Model Context Protocol (MCP) Server Workflow: Client-Server architecture exposing 10+ high-performance native Go tools and 200+ security SOPs over JSON-RPC 2.0 stdio to external AI coding assistants and IDEs (Gemini/Antigravity, Claude Desktop, Cursor, Windsurf, Cline, Roo Code).

1. 🤖 Autonomous Hermes CLI Workflow

The standalone CLI mode utilizes the built-in Hermes Agent engine (hermes.exe / cybermes) as an autonomous reasoning brain. The operator provides a target prompt, and Hermes autonomously maps the attack surface, invokes CLI binaries, filters outputs through smart_pipe to prevent LLM context saturation, verifies hypotheses with standalone PoC scripts, and produces executive reports.

Hermes CLI Execution Flow:

flowchart LR
    subgraph P1["1. Scope & Recon"]
        direction TB
        A([CLI Input]) --> B[Hermes Agent]
        B --> C[Recon Tools]
        C --> D[smart_pipe Filter]
    end

    subgraph P2["2. Skill & Validation Gate"]
        direction TB
        D --> E[Knowledge & SOPs]
        E --> F[Validation Gate]
        F --> G[Run PoC Script]
    end

    subgraph P3["3. Deliverables"]
        direction TB
        G --> H[reports/ Workspace]
        H --> I([Executive Reports])
    end

    P1 ==> P2 ==> P3

Hermes Pipeline Stages:

1. Target Ingestion & Scope Validation: Operator issues a single CLI prompt. Hermes resolves domain boundaries and initializes target workspace directories (recon/<TARGET_SLUG>/ and reports/<TARGET_SLUG>/).
2. Autonomous Toolchain Orchestration: Hermes spawns external reconnaissance tools (subfinder, httpx, katana, ffuf) in sequence.
3. High-Speed Stream Filtering (smart_pipe): Raw outputs are archived to disk in recon/ while smart_pipe streams only relevant endpoints, HTTP status codes, and leaked secrets into Hermes' context window.
4. Hypothesis & Skill Retrieval: Hermes queries the offline database (search_knowledge) and loads relevant offensive playbooks from skills/.
5. Deterministic PoC Validation Gate: Hermes writes and executes a non-destructive script (pocs/poc_<vuln>.py), capturing raw HTTP request/response evidence.
6. Report Compilation: Calls native Go aggregate_reports and generate_pdf.py to compile SUMMARY.md, metadata.json, interactive report.html, and REPORT_<target>.pdf.

2. 🔌 Cybermes MCP Server Workflow

In the MCP workflow, Cybermes operates as a native JSON-RPC 2.0 server (cybermes-mcp) providing specialized security tools, prompts, and context providers directly to external AI assistants and IDEs (Cursor, Antigravity / Gemini, Claude, Windsurf, VS Code / Cline). The external model acts as the reasoning engine while Cybermes handles high-speed tool execution, local knowledge lookups, and reporting.

MCP Protocol Execution Flow:

flowchart LR
    Client([AI Editor / IDE]) <-->|JSON-RPC 2.0 stdio| MCP[Cybermes MCP: cybermes-mcp]
    
    subgraph Tools["Modular Capabilities"]
        direction TB
        T1[Recon & Probing]
        T2[200+ SOPs & Knowledge]
        T3[Secrets & Nuclei Scan]
        T4[Findings & Evidence]
    end

    MCP <--> Tools
    Tools --> Out[(reports/SLUG/ Deliverables)]

MCP Tooling & Interaction Lifecycle:

1. Handshake & Discovery: AI Client starts cybermes-mcp via stdio and discovers exposed tools, schemas, and resource templates.
2. Environment & Scope Assessment: The AI invokes cybermes_validate_scope and cybermes_check_environment to inspect target authorization and system tool health.
3. Structured Recon & Secret Mining: AI executes cybermes_recon_crawl, cybermes_http_probe, or cybermes_scan_secrets. The MCP server executes compiled routines and returns clean, structured JSON results without context bloat.
4. On-Demand Playbook & Exploit Lookup: When a vulnerability vector is identified, the AI calls cybermes_search_knowledge and cybermes_get_skill to retrieve targeted exploitation steps in sub-50ms.
5. **Determinist