# Cybermes

> An offensive-security agent that runs bug-bounty recon, proves findings with PoC scripts and writes the report

- Category: Agents & Automation / Security Agents
- Language: Python
- Licence: Apache-2.0
- Repository: https://github.com/Zyrexnn/Cybermes
- Canonical page: https://ai-tldr.dev/tools/cybermes/

## In short

Cybermes is an open-source framework for authorised bug-bounty hunting, reconnaissance and vulnerability research. It sits in the Security Agents category of the Agents & Automation tools and is open-source, written in Python and licensed Apache-2.0. To get started: option A: add the MCP server to your AI client.

## Overview

Cybermes is an open-source framework for authorised bug-bounty hunting, reconnaissance and vulnerability research. It pairs native Go utilities with more than 200 offensive-security playbooks and a set of standard recon tools (subfinder, httpx, katana, ffuf, nuclei, sqlmap), and drives them with an AI model so that one prompt such as "Assess https://example.com" turns into recon, analysis, verified findings and a written report.

It runs in two ways. As a standalone CLI, the built-in Hermes Agent engine (built on Nous Research's Hermes Agent) is the reasoning loop: it maps the attack surface, spawns the recon tools, reads their output and writes proof-of-concept scripts on the operating system itself. As an MCP server, `cybermes-mcp` exposes its tools, playbooks and report helpers over JSON-RPC stdio to an AI client such as Claude Desktop, Cursor, Windsurf, Cline, Roo Code, Codex or Gemini/Antigravity, and the client's model does the reasoning.

Two pieces of plumbing carry the design. `smart_pipe` is a Go stream filter that archives raw crawler and fuzzer output to disk and passes only relevant endpoints, status codes and leaked secrets into the model's context, so thousands of 404 lines never reach it. A validation gate then requires a standalone, non-destructive Python PoC (`pocs/poc_<vuln>.py`) with captured HTTP evidence before a finding is recorded. Every target gets its own `recon/` and `reports/` workspace, compiled into `SUMMARY.md`, `metadata.json`, an HTML report and a PDF.

This is offensive-security tooling, built for systems you are authorised to test. The project is Apache-2.0 licensed and runs on Linux, macOS, Windows and Docker.

## What it does

- Two modes: an autonomous Hermes Agent CLI, or a Go MCP server (`cybermes-mcp`) for AI coding clients
- One-command MCP install that detects and configures supported clients (`npx -y cybermes-mcp install`)
- 200+ offensive playbooks in `skills/`, covering API flaws (IDOR/BOLA, JWT), web bugs (SSRF, XSS, SQLi, race conditions) and cloud misconfigurations
- Offline knowledge search (`search_knowledge`) across the playbooks plus PayloadsAllTheThings and HackTricks material
- `smart_pipe` filters tool output down to high-signal lines before it enters the model's context
- PoC validation gate: a finding is logged only with a standalone non-destructive script and raw HTTP evidence
- Recon pipelines for subfinder, httpx, katana, ffuf, nuclei and sqlmap, plus a `secret_scan` credential scanner
- Per-target workspaces and reports in Markdown, JSON, HTML and PDF
- Native installers for Linux, macOS and Windows PowerShell, a Docker Compose setup and a `doctor.py` health check

## Getting started

Use Cybermes inside your AI client through MCP, or install the standalone CLI. Only point it at targets you are authorised to test; the repository ships a mock vulnerable app for a first run.

1. Option A: add the MCP server to your AI client

   The installer detects supported clients and registers the server; flags limit it to specific clients.

```bash
# configure every detected AI client
npx -y cybermes-mcp install

# or only some of them
npx -y cybermes-mcp install --gemini --cursor
```

2. Or register it by hand

   Add the server to the client's mcpServers section.

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

3. Option B: install the standalone CLI

   On Linux or macOS, clone the repository, run the installer and put your API keys in .env (Windows uses setup_windows.ps1).

```bash
git clone https://github.com/Zyrexnn/Cybermes.git
cd Cybermes
./setup.sh
nano .env
```

4. Check the environment

   doctor.py verifies dependencies and tool paths; --fix repairs missing components.

```bash
python tools/doctor.py
python tools/doctor.py --fix
```

5. Run a first assessment against the bundled mock app

   Findings, PoCs, evidence and reports land in reports/<target>/.

```bash
python examples/mock_vulnerable_app.py   # serves http://127.0.0.1:8888
./cybermes "Assess http://127.0.0.1:8888"
```

## When to use it

- Reach for it to run authorised bug-bounty reconnaissance end to end from a single prompt, with findings written up as reports
- Reach for it when you want Claude, Cursor or another MCP client to drive recon and secret scanning without pasting terminal output into the chat
- Reach for it when you need every reported vulnerability backed by a reproducible PoC script and HTTP evidence
- Reach for it to practise agent-driven web testing on the bundled mock vulnerable app before pointing it at a scoped target
