{"id":50217969,"url":"https://github.com/ry-ops/mr-robot","last_synced_at":"2026-05-26T10:02:38.030Z","repository":{"id":359787258,"uuid":"1247502916","full_name":"ry-ops/mr-robot","owner":"ry-ops","description":"An ADR-driven security framework for Kali — a HackTheBox co-pilot orchestrating Hat-persona Claude agents across a shared arcade and a cross-engagement memory layer.","archived":false,"fork":false,"pushed_at":"2026-05-23T13:24:36.000Z","size":127,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T14:14:24.879Z","etag":null,"topics":["adr","claude-code","hackthebox","kali-linux","mcp","multi-agent","offensive-security","pentest","security"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ry-ops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T12:02:26.000Z","updated_at":"2026-05-23T13:27:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ry-ops/mr-robot","commit_stats":null,"previous_names":["ry-ops/mr-robot"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ry-ops/mr-robot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fmr-robot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fmr-robot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fmr-robot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fmr-robot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ry-ops","download_url":"https://codeload.github.com/ry-ops/mr-robot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fmr-robot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33514912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","claude-code","hackthebox","kali-linux","mcp","multi-agent","offensive-security","pentest","security"],"created_at":"2026-05-26T10:02:26.997Z","updated_at":"2026-05-26T10:02:38.015Z","avatar_url":"https://github.com/ry-ops.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagrams/hero.svg\" alt=\"Mr. Robot — two-layer architecture: an orchestrator spawns Hat robots that work a shared arcade and memory layer.\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Mr. Robot\n\nAn orchestrated, ADR-driven security framework for Kali — a HackTheBox co-pilot\nthat runs multiple \"Hat\" personas concurrently to compress a weekend of boxes\ninto hours. Named for the TV series.\n\n## The idea\n\nMr. Robot does not hard-code its behavior. Every operating mode is an **ADR**,\nand every ADR prefaces a **Hat** — a persona defined along three axes: intent,\nethics, and behavior. The orchestrator points Hat _robots_ at a box; they work\na shared task board (the **arcade**); a declarative **playbook** turns findings\ninto new tasks; and the campaign adapts as it runs — spreading robots across\nthe attack surface or ganging up on one tough target.\n\nThe differentiator isn't the tooling — Kali already has the tools. The\ndifferentiator is **judgment that compounds across boxes**, which is what the\nmemory layer (ADR-0014) is for.\n\n## The control loop\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagrams/loop.svg\" alt=\"The control loop: a heartbeat ticks; the brain reads the arcade and decides per robot (leave, reinforce, repurpose, or assign); robots work; findings post; the playbook unlocks new tasks; repeat.\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nA tick is a turn. The brain reads the arcade, decides per-robot, robots act,\nfindings come back, the playbook unlocks new tasks. \"Assist vs. gang up\" is\nnot a policy switch — it's emergent from the same `ready` / `blocker`\nmachinery.\n\n## Architecture\n\nTwo layers.\n\n- **The arsenal** (layer 1, [ADR-0012](adr/ADR-0012-the-arcade.md)) — the\n  `mr-robot` MCP server: the arcade (SQLite findings store + task board), the\n  playbook engine, the Hat registry, and a scope guard.\n- **The orchestrator** (layer 2, [ADR-0013](adr/ADR-0013-the-orchestrator.md)) —\n  \"Mr. Robot\": spawns Hat robots as real Claude agents, runs a heartbeat\n  control loop, and adapts.\n\n## The memory\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagrams/memory.svg\" alt=\"The memory layer: one adapter at server/memory.py routes calls to aiana (SQLite + FTS5), Qdrant (semantic), and Redis (cache). Reads merge FTS5 + Qdrant via reciprocal rank fusion. Writes invalidate the cache via a generation counter.\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nA single adapter at `server/memory.py` over three independently feature-detected\nbackends. The arcade stays per-engagement; cross-engagement state lives here.\nCold recall ≈ 17 ms (FTS5 + Qdrant + embedding); cached ≈ 0.1 ms. See\n[ADR-0014](adr/ADR-0014-the-memory.md).\n\n## The Co-op *(proposed)*\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagrams/coop.svg\" alt=\"The Co-op: a host operator creates a join key; participants point at the host's local Qdrant as the shared source of truth for the event. An htb-api MCP server feeds HackTheBox challenge metadata to the host. All participants share scrubbed solved-only progress and read recollections back. A Qdrant Cloud mode is also available for asynchronous cross-time sharing.\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nA second tier above the memory so judgment compounds across **operators**,\nnot just engagements on one host. Two federation modes:\n\n- **Cloud mode** — opted-in instances write solved progress to a hosted\n  Qdrant Cloud collection and read it back at triage / reinforce time.\n  Async, global, always-on; best for cross-time learning.\n- **Event mode** *(planned)* — for time-bounded collaborative challenges\n  (HTB Battlegrounds, a new-release box drop, a CTF). The operator who\n  starts the session becomes the **host**; their *local* Qdrant becomes\n  the shared source of truth for the event. The host shares a **join key**\n  out of band; participants attach and their writes/reads route through\n  the host's vault for the duration of the event.\n\nBoth modes reuse the memory adapter, embedding pipeline, and `Recollection`\nshape, and gate writes through a single auditable scrubber on the\nsolved-only path. ADR-0015 also proposes **`htb-api`**, an upcoming sibling\nMCP server that wraps the HackTheBox v4 API so the orchestrator and the\nco-op can ground themselves in what's actually live on the platform. See\n[ADR-0015](adr/ADR-0015-the-co-op.md) for the full proposal and promotion\ncriteria.\n\n## The Hats\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagrams/hats.svg\" alt=\"The Hat constellation: eleven personas orbit the Mr. Robot core. White, Black, Blue, Purple, and Red Team are Accepted. Gray, Red, Green, Script Kiddie, Blue Team, and Purple Team are Proposed pending runtime support.\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nEight individual Hats plus three teams. A Hat is **Accepted** iff its contract\nreduces to \"operate within the engagement's `box_ip` scope using the wired\ntoolset\" — i.e., what `server/scope.py` already enforces universally. Others\nstay **Proposed** with a named promotion criterion (per-Hat tool gating,\nlab-mode flag, destructive-action throttling, defensive tooling).\n\n| ADR | Hat | Class | Status |\n|-----|-----|-------|--------|\n| [0001](adr/ADR-0001-white-hat.md)     | White Hat      | Individual | Accepted |\n| [0002](adr/ADR-0002-black-hat.md)     | Black Hat      | Individual | Accepted |\n| [0003](adr/ADR-0003-gray-hat.md)      | Gray Hat       | Individual | Proposed |\n| [0004](adr/ADR-0004-red-hat.md)       | Red Hat        | Individual | Proposed |\n| [0005](adr/ADR-0005-blue-hat.md)      | Blue Hat       | Individual | Accepted |\n| [0006](adr/ADR-0006-green-hat.md)     | Green Hat      | Individual | Proposed |\n| [0007](adr/ADR-0007-purple-hat.md)    | Purple Hat     | Individual | Accepted |\n| [0008](adr/ADR-0008-script-kiddie.md) | Script Kiddie  | Individual | Proposed |\n| [0009](adr/ADR-0009-red-team.md)      | Red Team       | Team       | Accepted |\n| [0010](adr/ADR-0010-blue-team.md)     | Blue Team      | Team       | Proposed |\n| [0011](adr/ADR-0011-purple-team.md)   | Purple Team    | Team       | Proposed |\n\n## Layout\n\n```\nMr. Robot/\n  adr/             architecture decision records — the Hats + the components\n  server/          the MCP server + orchestrator   (see server/README.md)\n  docs/diagrams/   the SVGs embedded above\n  vault/           Obsidian vault for ongoing project journeys\n  engagements/     per-box workspaces + arcade.db   (created at run time)\n~/playbooks/       the unlock-rule playbooks (Obsidian vault, versioned apart)\n```\n\n## Status\n\n| Component | State |\n|-----------|-------|\n| Layer 1 — arsenal ([ADR-0012](adr/ADR-0012-the-arcade.md))         | Built · connected to Claude Code · verified |\n| Layer 2 — orchestrator ([ADR-0013](adr/ADR-0013-the-orchestrator.md)) | Built · verified with mock + real agents |\n| The Memory ([ADR-0014](adr/ADR-0014-the-memory.md))                 | Built · verified end-to-end with aiana + Qdrant + Redis live |\n| The Co-op ([ADR-0015](adr/ADR-0015-the-co-op.md))                   | Proposed · cross-operator tier on Qdrant Cloud, opt-in + solved-only |\n| Lifecycle / Deadlines / Constraint IDs ([ADR-0016](adr/ADR-0016-lifecycle-deadlines-constraints.md)) | Built · event bus, env-tunable deadlines, `C-NNNN-NNN` IDs on ADR-0014 / ADR-0015 |\n| Hat ADRs — Accepted    | 0001 White · 0002 Black · 0005 Blue · 0007 Purple · 0009 Red Team |\n| Hat ADRs — Proposed    | 0003 Gray · 0004 Red · 0006 Green · 0008 Script Kiddie · 0010 Blue Team · 0011 Purple Team |\n| Robot toolset          | Recon only — web / exploitation wrappers not yet built |\n\n## Quick start\n\n\u003e **First time?** Follow [how-to-install.md](how-to-install.md) for the full setup — prerequisites, Python deps, aiana, Redis, Qdrant, MCP registration, and a verified mock run.\n\n```bash\n# mock run — free, deterministic, exercises the whole loop\npython3 \"server/orchestrator.py\" Lame 10.10.10.3 --mock\n\n# real run — spawns Claude-agent robots (costs tokens)\npython3 \"server/orchestrator.py\" \u003cbox\u003e \u003cip\u003e\n```\n\nThe memory layer is optional but recommended for any non-mock run:\n\n```bash\n# Redis — recall cache, ADR-0014's deferred backend\nredis-server --daemonize yes --port 6379 --bind 127.0.0.1 \\\n  --dir ~/redis-data --save \"\" --appendonly no\n\n# Qdrant — vector recall, via Docker\ndocker run -d --name mr-robot-qdrant -p 6333:6333 \\\n  -v ~/qdrant_storage:/qdrant/storage qdrant/qdrant\n```\n\nEach backend is feature-detected; missing services are logged once at init and\nthe adapter falls back to whichever subset is available.\n\nSee [`server/README.md`](server/README.md) for detail and [`adr/`](adr/) for\nthe design.\n\n## Contributing\n\nThe project is ADR-driven on purpose: a new behavior is a new ADR, not a new\nflag. The shortest path to a contribution is\n\n1. Read [`adr/README.md`](adr/README.md) for the ADR lifecycle and structure.\n2. Open a new ADR for the change (or propose a status flip on an existing one).\n3. Implement against the runtime; the runtime is the source of truth for\n   whether an ADR is Proposed or Accepted.\n\n## Built on\n\nMr. Robot leans on two sibling projects of mine:\n\n- **[aiana](https://github.com/ry-ops/aiana)** — the cross-engagement memory\n  layer (ADR-0014). aiana owns the SQLite + FTS5 + Qdrant storage; Mr. Robot\n  drives it through a single adapter at `server/memory.py`.\n- **[git-steer](https://github.com/ry-ops/git-steer)** — a rate-limit-hardened\n  MCP server for autonomous repo management. Mr. Robot borrows parts of its\n  patterns for shaping an MCP surface that an agent can drive without\n  babysitting.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fry-ops%2Fmr-robot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fry-ops%2Fmr-robot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fry-ops%2Fmr-robot/lists"}