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"

Related MCP server: apex

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. Deterministic Evidence Recording & Aggregation: AI logs verified findings with cybermes_record_finding / cybermes_record_evidence and compiles target deliverables via cybermes_aggregate_report.

3. ⚖️ Hermes CLI vs. Cybermes MCP Comparison

Why Cybermes?

Core Features

• Native Go Toolchain: Zero-overhead compiled utilities for output stream filtering (smart_pipe), credential scanning (secret_scan), offline knowledge retrieval (search_knowledge), and report aggregation (aggregate_reports).

• Model Context Protocol (MCP): Native Go MCP server (cybermes-mcp) exposing security tools and context providers to AI assistants like Claude Desktop, Cursor, Windsurf, and VS Code / Cline.

• 200+ Offensive Playbooks: Standard operating procedures in skills/ covering API security (IDOR/BOLA, JWT, BPLA), web vulnerabilities (SSRF, XSS, SQLi, Race Conditions), and cloud misconfigurations.

• Integrated Reconnaissance: Pre-configured pipelines for subfinder, httpx, katana, ffuf, nuclei, and sqlmap.

• Target Workspace Isolation: Strict target-scoped evidence tracking, preventing context contamination across engagements.

• Multi-Format Reporting: Automated output generation in Markdown (SUMMARY.md), JSON metrics (metadata.json), standalone HTML dashboards, and PDF reports (REPORT_<target>.pdf).

• Cross-Platform Compatibility: Fully supported on Windows (native PowerShell), Linux, macOS, and Docker.

Target Workspace & Deliverables

Every target assessment creates a dedicated directory structure under reports/ and recon/:

Cybermes/
├── reports/<TARGET_SLUG>/        # Verified findings & deliverables
│   ├── SUMMARY.md                # Consolidated executive findings matrix
│   ├── metadata.json             # Structured JSON metrics & counters
│   ├── report.html               # Standalone interactive HTML report
│   ├── REPORT_<target>.pdf       # Print-ready PDF report (named per assessed target)
│   ├── findings/                 # Confirmed vulnerability writeups (low, medium, high, critical)
│   │   └── high_idor_orders.md
│   ├── pocs/                     # Standalone Python proof-of-concept scripts
│   │   └── poc_idor_orders.py
│   └── evidence/                 # Raw logs, screenshots, recon notes
│       └── recon_notes.md
└── recon/<TARGET_SLUG>/          # Raw tool outputs & streaming dumps
    ├── subdomains.txt
    └── endpoints.txt

Toolchain

Documentation

Detailed guides and references are available in the docs/ directory:

• Windows Installation Guide — Setup via PowerShell, WSL2, and troubleshooting.

• MCP Setup Guide — Integration guide for all supported AI coding editors and clients.

• Prompt Engineering Guide — Structuring security research prompts effectively.

• Telegram Gateway Setup — Configuring remote execution via Telegram.

• Tools & Skills Reference — Breakdown of offensive playbooks and built-in tools.

• Troubleshooting & FAQ — Common error resolutions and diagnostics.

• Autonomous Swarm Playbook — 24/7 fleet architecture: orchestrator/executor topology, swarm design, two-layer validator, evaluation framework, and deployment runbook.

• Fleet Operations Skill — SSH access patterns for VM2 (lab) and Tencent (executor), dispatch patterns, concurrency limits, and credential handling.

Validation Pipeline

Findings are gated by two independent layers before they reach findings/. No claim enters a report on model prose alone.

agent claim
    |
    v
[LAPIS 1] reports/<slug>/pocs/validate.py     deterministic: baseline / attack / negative / gate
    | exit 0 = PASS                            exit 1 -> evidence/recon_notes.md
    v
[LAPIS 2] jev judge (MCP)                      adversarial: does the wire evidence support
    | SEPATUT                                  the claimed class and severity?
    v                                          TIDAK SEPATUT -> evidence/recon_notes.md
reports/<slug>/findings/<severity>_<name>.md

Gate types: differential (IDOR, auth bypass), reflected (XSS, SSTI), timing (blind injection), oob (SSRF, XXE).

The validator is pure Python stdlib — no LLM, no dependencies. CI runs a three-scenario smoke test on every push (real IDOR must PASS, no-IDOR must FAIL, non-discriminative target must FAIL).

Fleet Topology

Scanning traffic never originates from the orchestrator. See docs/AUTONOMOUS_SWARM_PLAYBOOK.md.

Acknowledgments & Upstream Credits

Cybermes integrates and builds upon foundational work from the open-source and offensive security research communities:

(See ATTRIBUTION.md for full license notices and upstream details)

Contributors

Thank you to everyone who helps build, maintain, and research Cybermes:

Want to contribute? Check out our Contributing Guide and Contributors List.

License

This project is licensed under the Apache License 2.0.

Third-party research materials, datasets, and upstream tools referenced or incorporated within this repository retain their respective original licenses (see ATTRIBUTION.md).

Legal & Ethical Disclaimer

IMPORTANT: Cybermes is developed exclusively for authorized security testing, legitimate bug bounty research, and academic security education.

Testing against targets without explicit, prior written permission from the target owner is illegal and strictly prohibited. The maintainers assume no liability and are not responsible for any misuse, damage, or legal consequences resulting from this tool.