Cybermes: a Hermes-driven agent that chains recon tools and gates findings behind PoC validation

What Cybermes is trying to fix about automated recon

Most reconnaissance pipelines fail in one of two directions. Either they dump raw tool output into a report and leave a human to work out which lines matter, or they hand every line of that output to a language model and watch the context window fill with banner noise before the interesting part arrives. Cybermes is built around the claim that both problems are solvable in the same pipeline. It targets authorized bug bounty hunting, reconnaissance, vulnerability research and structured reporting, and it is explicitly scoped to authorized work. The intended user is a security engineer or small team that already runs offensive tooling and wants the orchestration, the output filtering and the report generation handled by an agent rather than by a folder of shell scripts. It is not aimed at someone who wants a point-and-click scanner. The README describes a framework that reasons about a target, invokes binaries, filters their output, and then writes reports into a workspace directory.

Two execution paths: the Hermes CLI loop and the MCP server

Cybermes ships two distinct operational workflows, and they are not interchangeable. The first is the autonomous Hermes CLI workflow. The local Hermes engine acts as the reasoning component: the operator supplies a target prompt, and Hermes maps the attack surface, invokes CLI binaries as subprocesses, filters their streaming output through a component called smart_pipe, verifies hypotheses with standalone PoC scripts, and writes executive reports. The README's flow diagram breaks this into three phases: scope and recon, then a skill and validation gate, then deliverables. The second workflow is a Model Context Protocol server. A native Go binary named cybermes-mcp exposes what the README describes as 10+ security tools and 200+ security SOPs over JSON-RPC 2.0 stdio to external AI coding assistants. That is a client-server arrangement where the assistant drives the tools, not an autonomous loop. The distinction matters for how you install the project and for how much of the reasoning happens locally.

smart_pipe and the validation gate are the two mechanisms worth understanding

The README names smart_pipe as the component that filters streaming tool output to prevent LLM context saturation. That is a concrete design decision rather than a marketing phrase: instead of forwarding raw scanner output to the model, the pipeline reduces it first. The second mechanism is the validation gate. Before a hypothesis becomes a deliverable, the pipeline runs a standalone PoC script. The README's diagram places the gate between the knowledge and SOP stage and the PoC execution stage, with reports following only after the PoC runs. This is the part of the design with real consequences. A finding that cannot be demonstrated by a script does not proceed to the report in this model. That reduces false positives, and it also means the framework's usefulness depends on whether a given vulnerability class can be expressed as a runnable PoC. Classes that resist scripted demonstration will be harder to carry through the pipeline. The README does not describe a manual override path for the gate, so treat that as an open question rather than a documented feature.

Installing it: MCP path versus standalone CLI path

The README recommends the MCP route for AI workflows. The one-command installer is `npx -y cybermes-mcp install`, which auto-detects and configures installed AI clients. You can narrow it with flags such as `--kilo`, `--gemini` and `--cursor`. To avoid npx startup latency there is a global install: `npm install -g cybermes-mcp` followed by `cybermes-mcp install --global`. Manual registration goes in the `mcpServers` section of the client config, with `command` set to `npx` and `args` set to `["-y", "cybermes-mcp"]`. The README also documents local manager scripts: `mcp.bat` or `mcp.ps1` on Windows, `mcp.sh` or `python3 scripts/mcp.py` on Linux and macOS. The standalone path is different. On Linux and macOS you clone the repository, run `./setup.sh`, then edit `.env`. On Windows you run `setup_windows.ps1` and then edit `.env` in Notepad. Docker is a third option: copy `.env.example` to `.env`, edit it, then `docker compose up -d`. After installation the README gives an environment check, `python tools/doctor.py`, with a repair mode at `python tools/doctor.py --fix`. Running an assessment is `./cybermes "Assess https://example.com"` on Linux and macOS, `cybermes.bat` on Windows, and `docker compose exec cybermes cybermes "Assess https://example.com"` inside the container. There is a mock target for local testing: `python examples/mock_vulnerable_app.py` starts an app on `http://127.0.0.1:8888`. Use that before pointing the agent at anything real.

The toolchain cost is the part the feature list hides

The badges state Python 3.11+, Go 1.22+, and support for Linux, macOS, Windows and Docker. That combination has a practical consequence: you are maintaining two language runtimes plus a set of external security binaries, and the installers exist precisely because wiring those together by hand is tedious. The `doctor.py` script and its `--fix` flag are the project's own acknowledgment that environments drift. Any team adopting this should expect to run diagnostics after upgrades rather than assuming the pipeline still works. The Docker path reduces that burden by fixing the environment in an image, at the cost of running the agent inside a container where subprocess spawning and filesystem access behave differently from the host. The README does not document how the containerised agent handles PoC scripts that expect host networking or host-installed binaries, so if you go the Docker route, test the validation gate against the mock app before trusting it against a real target.

Where the autonomous loop is the wrong tool

An agent that spawns subprocesses and executes generated PoC scripts is doing something a static scanner never does. That is the source of its value and the source of its risk. If your rules of engagement prohibit automated exploitation attempts, or if the target environment cannot tolerate scripted requests, the validation gate becomes a liability rather than a filter. The same applies if you need deterministic, reproducible output for compliance evidence: an LLM-driven reasoning loop introduces variability that a fixed scanner invocation does not. There is also a scope question. The README's example prompt is a single target URL, and the workflow is described around one assessment at a time. Nothing in the supplied material describes parallel multi-target campaigns or scheduling, so do not assume the framework scales to a large asset inventory out of the box. And because the project is at v3.4.x with three releases in a single day in late August 2026, the release cadence suggests active churn. Pin a version rather than tracking main if you depend on specific playbook behaviour.

How it differs from a scanner-plus-wrapper approach

The obvious alternative is running Nuclei, sqlmap and a browser automation tool through a thin wrapper script and reading the output yourself. That approach is fully deterministic, has no LLM dependency, and produces output you can diff between runs. The difference in Cybermes is the reasoning layer: the Hermes engine decides which playbook applies and in what order, and smart_pipe decides what the model actually sees. A wrapper script has no equivalent of the validation gate, so it will report everything the underlying tools flag, including the false positives. The trade is control for filtering. With a wrapper you know exactly which command ran against which host. With Cybermes the README describes the agent mapping the attack surface and invoking binaries, but it does not enumerate which binaries run in which order for a given target. If auditability of individual tool invocations matters to your program, that gap is worth resolving before adoption. If your bottleneck is triage rather than coverage, the gate is the more valuable half of the design.

Licence, upgrades and what to check before you commit

Cybermes is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. It does not impose copyleft on your own code. That is a permissive position, and it also means the project carries no obligation to provide support. The README links a docs directory with MCP setup, Windows installation and other guides, but the supplied material does not describe a support channel, a compatibility policy between releases, or a deprecation process for playbooks. Given the release history (v3.4.0, v3.4.1 and v3.4.2 within about an hour on 2026-08-30, with v3.4.1 titled as an interactive prompt UI hotfix and terminal lifecycle change), expect interface changes between minor versions. Before adopting, run `python tools/doctor.py` and confirm what it checks, read `docs/MCP_SETUP.md` for the client-specific flags rather than guessing from the README, and confirm that the playbooks you need are present in the repository layout rather than assumed from the feature description. This is not legal advice; review the Apache-2.0 text against your own distribution model.

Editorial conclusion

Adopt Cybermes if you already run an authorized bug bounty or internal red team program, you are comfortable maintaining a Python 3.11+ and Go 1.22+ toolchain, and you want findings filtered by a PoC validation gate rather than a raw scanner dump. Do not adopt it if you need a single-binary scanner, if you cannot run untrusted PoC scripts against a target, or if you expect a hosted service with no local dependency management. Verify first that python tools/doctor.py --fix reports a clean environment, that the named playbooks you intend to rely on actually exist under the workspace layout, and that your rules of engagement permit an autonomous agent to spawn subprocesses and execute generated scripts on your behalf. The validation gate is the reason to choose this project; if your workflow cannot accommodate it, the rest of the framework is just orchestration you could assemble yourself.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. Zyrexnn/Cybermes on GitHub