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, and all evidence is normalized into the engagement graph.

Related MCP server: pyntra

The systems

MCP tools (34 total)

• 12 category dispatchers - scan_essential, scan_web_security, scan_osint, ... covering all 90 routed HexStrike tools (nmap, nuclei, subfinder, ffuf, ...). Each call scope-gated; member list ships in each dispatcher's description, so tools/list stays small.

• Verification tools (9) - confirm_difference (3-gate: baseline vs attack, mechanical diff), http_repeater, browser_agent_inspect, api_fuzzer, graphql_scanner, comprehensive_api_audit, search_evidence (grep every raw tool output), retest_finding + record_retest (re-verification verdicts)

• Graph tools (7) - create_hypothesis, promote_finding (endpoint-aware duplicate triage), score_finding, retire_hypothesis, create_attack_chain (steps must exist — lineage enforced), get_attack_chains, next_chain_step (ARTEX-style frontier: never work past an unmet step)

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

• Memory tools (2) - recall_lessons, commit_learnings

Requirements

• Python 3.12+ and uv

• Docker (for Memgraph)

• HexStrike server running on :8899

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

• Secrets in .env: 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.

• 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 34 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 sentrux check . && uv run pyrefly check jcyber tests

License

MIT - see LICENSE.