Zyrexnn/Cybermes

Cybermes

Autonomous Offensive Security & Bug Bounty Automation Framework

Cybermes is an offensive security assistant and automation framework designed for authorized bug bounty hunting, reconnaissance, vulnerability research, and structured reporting.
It combines native Go performance utilities, 200+ modular offensive security playbooks, token-optimized streaming pipelines, and full Model Context Protocol (MCP) support for AI coding environments.

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

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

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).

# 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

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

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

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

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.

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

# 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)

# 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

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

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

# 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"

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).

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.

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

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.

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.

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)]

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.

• 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.

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

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.

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)

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

Zyrexnn

msarg44

Mortify4315

sizoune

xsoft

Muzakie-ID

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

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).

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.