red-run is a Black Lantern Security toolkit that wires Claude Code agent teams, MCP servers, and RAG-routed skills into a persistent, operator-supervised assessment workflow for CTF and lab environments.
| Tool | blacklanternsecurity/red-run — security assessment orchestrator for Claude Code agent teams |
| Category | AI-driven offensive security framework |
| Primary Use | Automating recon, enumeration, and technique execution across CTF/lab targets via persistent Claude Code teammates coordinated through an operator-approved routing loop |
| Safe Use | Documented for CTF and lab environments only, under explicit written authorization; the disclaimer states it has no OPSEC guarantees and must not be used against systems without permission |
| Telemetry Note | The authors explicitly warn that agents run with no stealth considerations and all activity should be assumed logged and detectable — noisy scanning via nmap/ffuf/sqlmap-style tooling makes engagements highly visible to defenders |
red-run is Black Lantern Security's attempt to answer one of the harder problems in AI-assisted offensive work: how do you keep an LLM-driven agent useful across a whole engagement instead of losing context every time a session compacts or a subagent exits? Their answer is architectural rather than prompt-level. The tool combines Claude Code skills, MCP servers, and agent teams into an orchestrator that tracks engagement state in a persistent engagement/state.db SQLite database, routes tasks to skills via semantic search over a ChromaDB index, and delegates execution to persistent domain teammates that accumulate knowledge across tasks. At roughly 300 stars and written in Python under AGPL-3.0, it is one of the more serious entries in the emerging agent-orchestration space.
The core design separates an orchestrator (team lead) from teammates. The lead presents the assessment surface, chain analysis, and available paths, and the human operator chooses what to test next — this is a deliberate human-in-the-loop decision, enforced through AskUserQuestion gates before any task is assigned. Routing itself is handled by a skill-router MCP server that performs RAG-style retrieval over the indexed skills/ directory, which means the framework scales by adding skill files rather than by growing a monolithic prompt. The README's documentation map (architecture, installation, mcp-servers, writing-skills) reinforces that this is meant as a platform, not a one-shot script.
Red-run ships with four orchestrator variants that all share the same skills, MCP servers, and engagement state. /red-run-ctf is the active one: agent teams with persistent teammates and full autonomy, aimed squarely at CTF and lab environments. /red-run-legacy is the original subagent model with ephemeral agents and one skill per invocation. Two more are planned: /red-run-notouch, a DLP-safe mode where the operator executes commands in separate tmux panes and reports sanitized output back so no client data touches Anthropic servers, and /red-run-train, a guided walkthrough mode for learning methodology. The neat trick is that all variants write to the same state.db, so an engagement started with one can be resumed with another.
The teammate topology is worth studying. Enumeration roles (net-enum, web-enum, ad-enum, lin-enum, win-enum) are paired with operations roles (web-ops, ad-ops, lin-ops, win-ops) for parallel discovery and technique execution, plus on-demand specialists (bypass, spray, recover, research). Teammates run in their own tmux panes, where the operator can watch them work, press Escape to interrupt, or type directly to redirect. The README highlights teammate messaging as the key advantage over the legacy model: a web teammate that finds domain credentials reports to the lead, which routes the finding to the AD teammate — cross-domain reasoning that ephemeral subagents structurally cannot do. A shared task list coordinates the parallel work.
Agent teams require the Claude Code experimental feature flag, and the repo's .claude/settings.json already sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, so a clone plus install is sufficient. Permission posture matters here: teams run in standard permission mode, so teammate permission requests surface to the operator for approval, and the --yolo flag that skips prompts exists but is clearly the riskier path. For an authorized professional evaluating this tool, the permission-gated default and the routing approval gates are the main containment mechanisms — the README is explicit that you are responsible for containing Claude on your own systems.
Installation follows a conventional pattern for this class of tool: ./install.sh for a symlink-based setup (edits to skills reflect immediately) or ./install.sh --copy for standalone machines, with ./uninstall.sh to remove everything. The installer sets up orchestrator templates, teammates, and the MCP servers, indexes skills/ into ChromaDB, and starts the shell-server. A preflight.sh script verifies attackbox dependencies — the README names nmap, ffuf, sqlmap, hashcat, and impacket among others — which tells you the skill library leans on standard offensive tooling executed under agent control. Prerequisites are a Linux pentesting VM, Claude Code itself, uv, and Docker.
The MCP layer is where execution actually happens, and the documented set is compact: nmap, shell, browser, state, and skill-router. The shell-server is the interesting piece — it runs as a persistent SSE service on 127.0.0.1:8022, shared across all teammates, so sessions created by one teammate are visible to all others. That shared-session model is what enables handoffs like an enumeration teammate spawning a shell that an operations teammate later reuses. run.sh starts it idempotently, and a SessionStart hook attempts auto-start as a fallback, which is a sensible resilience touch for long engagements.
C2 integration is optional and currently supports Sliver, with custom operator-provided MCP servers also possible. Running bash config.sh before launch selects the C2 backend, writes engagement/config.yaml, and patches .mcp.json with the C2 MCP entry — the orchestrator skips its own wizard when config.yaml exists, and run.sh then starts the C2 daemon plus its MCP server automatically. Out of the box, though, the shell-server handles raw TCP reverse shells and interactive processes with no C2 required, which fits the stated CTF focus.
Situational awareness for the operator is handled by a browser-based state dashboard: bash operator/state-viewer/start.sh serves a read-only view of state.db on http://127.0.0.1:8099, with live SSE updates showing targets, credentials, access, vulns, pivots, tunnels, blocked techniques, and an event timeline as teammates work. An access chain graph with fullscreen mode visualizes how access propagates. When red-run lives in a VM and you want to view the dashboard from the host, generate-token.sh binds the server to 0.0.0.0 behind token auth — a small detail that shows the authors thought about the practical isolation model.
What the README does not oversell is honesty. The disclaimer section is unusually blunt for this space: the current version is described as a CTF solver with no OPSEC considerations, skills are baseline templates built by AI and not thoroughly reviewed by human eyes, and users should expect gaps, false positives, and techniques needing validation before any use on real infrastructure. There is a production engagement roadmap in the architecture docs, but the tool's authors are clear about where it stands today. That transparency is a useful signal of maturity even if the codebase is not production-hardened.
From a defensive perspective, red-run is also worth knowing about for what it predicts. Agents running with no stealth considerations means engagements driven by this tool will be noisy — dense nmap and ffuf patterns, repeated credential attempts, and rapid cross-host pivoting are exactly what detection engineering should already catch. The shared state.db model is mirrored conceptually by what defenders can log: every teammate action passes through permission gates or the shell-server, leaving local artifacts. And the planned DLP-safe mode (/red-run-notouch) is a signal worth watching, since it reflects the compliance concerns consultancies will face when letting third-party LLM APIs near engagement data.
The stated authorization posture is unambiguous: explicit written permission required, unauthorized access illegal under the CFAA (18 U.S.C. § 1030) and equivalents, CTF and lab use only for the current version, and full user responsibility for the agents' actions — plus a warning that autonomous offensive command generation may trigger Anthropic content policy flags on your account. For authorized professionals, red-run is best read as an architecture reference for how persistent, stateful, human-gated AI agents can be composed for offensive workflows in contained environments, and as a preview of the orchestration patterns that will likely become standard in this space.
blacklanternsecurity/red-run.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.