Jcyber

MCP toolkit for agent-driven pentesting. The agent harness (Claude Code, or any MCP-capable LLM) is the reasoning loop. Jcyber provides scope-gated scanning tools, an evidence graph, a finding lifecycle, and long-term memory through an MCP server.

How it works

Agent Harness (Claude Code / any MCP client)
    |
    | MCP protocol (stdio)
    v
Jcyber MCP Server ---- scope gate (pre-hook, every call)
    |          |            |             |
    v          v            v             v
HexStrike  Memgraph    TencentDB      Caido
(:8899)    (:7687)     (memory)       (:8889)
    |                                    |
    +----------> Target <----------------+

The agent decides what to scan, when to create hypotheses, and when to promote findings. Jcyber enforces safety in code: the scope gate runs before every tool call, exploit tools require operator confirmation, and all evidence is normalized into the engagement graph.

Related MCP server: Offensive Security MCP Server

The systems

MCP tools (57 total)

• 42 HexStrike scanning tools - nmap_scan, nuclei_scan, sqlmap_scan, ffuf_scan, httpx_probe, etc. Each scope-gated.

• Verification tool (1) - confirm_difference - 3-gate confirmation: baseline vs attack request, mechanical response diff (status, body, timing). Absorbed from CyberStrike.

• Graph tools (6) - create_hypothesis, promote_finding (endpoint-aware duplicate triage), score_finding, retire_hypothesis, create_attack_chain, get_attack_chains

• Engagement tools (4) - intake_target, get_state, render_findings_report, get_decision_trace

• Memory tools (2) - recall_lessons, commit_learnings

• Jev classifiers (2) - suggest_severity, check_duplicate

Requirements

• Python 3.12+ and uv

• Docker (for Memgraph)

• HexStrike server running on :8899

• Caido proxy on :8889 (API on :8080)

• Secrets in .env: TYPESAFE_API_KEY, CAIDO_API_TOKEN (auto-loaded by python-dotenv)

Ports

Quick start

1. Install.

uv sync

2. Start the session brain (Memgraph).

docker compose -f deploy/docker-compose.memgraph.yml up -d

3. Start the MCP server.

Option A - standalone server (connect your agent separately):

python -m jcyber serve

Option B - intake a target and start serving:

python -m jcyber run https://example.com

4. Connect your agent. Add the MCP server to your agent's config. For Claude Code / OMP, add to your MCP config:

{
  "jcyber": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "jcyber", "serve"]
  }
}

The agent reads the SKILL.md methodology and drives the engagement through MCP tool calls.

Environment variables

Secrets live in .env (auto-loaded by python-dotenv at startup).

Safety

• Scope gate - deterministic string matching against the engagement scope, enforced as a pre-hook on every MCP tool call. Not prompt-bypassable.

• Exploit confirmation - exploit tools (metasploit_run, hydra_attack, etc.) return a confirmation prompt instead of executing. Operator must approve.

• Evidence graph - all tool output is normalized, sha256-deduped, and stored in Memgraph with full provenance.

• Finding lifecycle - Evidence (E-###) -> Hypothesis (H-###) -> Finding (F-###) -> Validated Finding. No skipping.

CLI

python -m jcyber serve              # start MCP server (stdio)
python -m jcyber run <url>          # intake target + start MCP server
python -m jcyber intake <link>      # create engagement directory
python -m jcyber report <dir>       # render engagement report
python -m jcyber trace <dir>        # render decision trace

Layout

jcyber/
  mcp_server.py        MCP server with all 57 tools
  SKILL.md             Agent methodology (the pentesting ladder)
  scope.py             Deterministic scope gate
  normalize.py         Evidence normalization (sha256, summary)
  config.py            Engagement + scope config parsing
  intake.py            Bare-link intake (URL -> engagement)
  report.py            Report renderer (graph -> Markdown)
  trace.py             Decision trace renderer
  learn.py             Distiller (findings -> long-term memory)
  ports.py             Protocol interfaces
  types.py             Domain types (Evidence, Scope, Severity)
  clients/
    hexstrike.py       HexStrike REST adapter
    memgraph.py        Memgraph Bolt adapter
    tencentdb.py       TencentDB HTTP adapter
    caido.py           Caido GraphQL adapter
    toon.py            TOON codec (CLI wrapper)
schema/
  memgraph/            Engagement graph DDL + indexes
  storage-layout.md    TOON config shapes
  tencentdb/           Memory interface spec
tests/                 pytest suite (no external deps needed)
deploy/                Docker Compose for Memgraph

Testing

uv run pytest -q
uv run ruff check . && uv run ruff format --check .
uv run pyright

Contributing

See CONTRIBUTING.md.

Legality

Jcyber assumes in-scope targets only. The scope gate is load-bearing, not decorative: it is deterministic string matching enforced in code as a pre-hook on every MCP tool call. Out-of-scope targets are rejected before reaching any scanner. Nothing in this repo grants permission to test any system. Authorization is the operator's responsibility.

License

MIT - see LICENSE.