red-run - Offensive security toolkit for Claude Code

项目说明

red-run

Security assessment toolkit for Claude Code.

<p align="center">
<img src="docs/banner.png" width="700" alt="red-run banner">
</p>

red-run combines skills, MCP servers, and Claude Code agent teams with routing logic that guides Claude and the operator through the phases of a security assessment — recon, initial access, lateral mo, pri escalation, and post-access. It tracks engagement state in a SQLite database that persists across context compactions, routes to skills search (RAG), and delegates execution to persistent domain teammates that accumulate context across tasks.

The orchestrator (team lead) presents the assessment surface, chain analysis, and a paths — you choose what to test next. Teammates work in their own tmux panes where you can watch them, press Escape to interrupt, and type directly to redirect. See Agent Teams below for setup.

Orchestrators

red-run supports multiple orchestrator that share the same skills, MCP servers, and engagement state. Each targets a different use case. Community contributions welcome.

| Orchestrator | Trigger | Status | Purpose |
|---|---|---|---|
| /red-run-ctf | /red-run-ctf | Active | CTF and lab en. Agent teams with persistent teammates, full autonomy. |
| /red-run-legacy | /red-run-legacy only | Legacy | Original subagent-based orchestrator. Ephemeral agents, one skill per in. |
| /red-run-notouch | /red-run-notouch only | Planned | DLP-safe mode. The operator executes commands in separate tmux panes and reports sanitized output back to the orchestrator. No client data touches Anthropic servers. |
| /red-run-train | /red-run-train only | Planned | Training mode. Guided walkthrough with explanations at each step. Designed for learning security assessment methodology with AI assistance. |

All orchestrators write to the same engagement/state.db — an engagement started with one can be resumed with another.

Documentation

Full documentation is a at the docs site:

See also: Skills In for the full skill in.

Installation

Prerequisites: Linux VM with pentesting tools, Claude Code, uv, Docker. Optional: Sliver for C2 integration.

The installer sets up the orchestrator, teammate templates, and MCP servers, indexes skills/ into ChromaDB for semantic retrieval, and starts the shell-server. The repo must stay in place — skill-router reads from skills/ at runtime.

After installing, run the preflight check to attackbox dependencies (nmap, ffuf, sqlmap, hashcat, impacket, etc.):

Then launch:

C2 integration (optional)

red-run works out of the box with shell-server (raw TCP reverse shells + interacti). For C2 support, run the config wizard before launching:

config.sh writes engagement/config.yaml and patches .mcp.json with the C2 MCP ser. The orchestrator skips its built-in config wizard when config.yaml exists. Currently supported: Sliver. Custom C2 integration MCP servers is also supported.

The shell-server runs as a persistent SSE service (127.0.0.1:8022) shared across all teammates — sessions created by one teammate are to all others. run.sh starts it automatically and is idempotent (safe to re-run). A SessionStart hook also attempts auto-start as a fallback.

See dependencies for the full list of required tools.

Agent Teams

red-run uses Claude Code agent teams to coordinate multiple Claude Code sessions working together. The orchestrator runs as the team lead, spawning persistent domain teammates that each get their own tmux pane. Teammates are split into enumeration (net-enum, web-enum, ad-enum, lin-enum, win-enum) and operations (web-ops, ad-ops, lin-ops, win-ops) pairs for parallel discovery and technique execution, plus on-demand specialists (bypass, spray, recover, research). Benefits over the legacy subagent model:

Agent teams requires the Claude Code experimental feature flag. The repo's .claude/settings.json already includes this:

No manual setup needed — cloning the repo and running ./install.sh is sufficient. For split-pane teammate , start Claude Code inside a tmux session. Without tmux, teammates run in-process (cycle with Shift+Down - this is not recommended for optimal control).

Agent teams works in standard permission mode — teammate permission requests surface to the operator for approval. The orchestrator's AskUserQuestion gates provide human-in-the-loop control for all routing decisions.

State Dashboard

Browser-based read-only dashboard for engagement/state.db with an access chain graph and live SSE updates:

Open to see targets, credentials, access, vulns, pivots, tunnels, blocked techniques, and an event timeline — all updating in real-time as teammates work. The access chain graph supports fullscreen mode for detailed review.

To access from a host machine (when red-run is in a VM), generate an auth token — the server will bind to 0.0.0.0 and require the token to access any page:

See operator/state-/README.md for details.

Running

Send any message (e.g., a target IP) to activate the orchestrator. The orchestrator presents routing decisions for operator appro assigning any task. Run from an isolated VM or dedicated pentesting machine. You are responsible for containing Claude on your systems and for any legal consequences under the CFAA or equi legislation.

Disclaimer

By using red-run you accept full responsibility for its actions. This tool runs fully autonomous AI agents that execute offensi techniques — port scanning, exploitation, credential attacks, pri escalation, and lateral mo — against targets you specify.

项目信息

开发语言：Python

Star 数：284

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Offensive security toolkit for Claude Code展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。