AI copilot for authorized red-team & internal-pentest engagements.
Install · Quick Start · Architecture · CLI Integration · Legal
An operator-assisted AI copilot for authorized offensive-security engagements (penetration tests, bug-bounty research, internal red-team exercises). It transforms a workspace into a structured Recon → Collect → Test → Exploit+OSINT → Report pipeline, backed by 8 specialized AI agents, per-engagement scope guardrails, and a reference library of OWASP / API-security / AD / tooling methodology.
This is not an autonomous attack tool. The human operator approves every active step. The orchestrator is a force-multiplier, not a decider.
- 5-phase engagement pipeline — Recon → Collect → Test → Exploit+OSINT → Report.
- 8 specialized AI agents —
operator·recon-specialist·source-analyzer·vulnerability-analyst·exploit-developer·fuzzer·osint-analyst·report-writer. - Web orchestrator (Next.js) — chat UI with scope-gated modes (OSINT, Reconnaissance, Vulnerability Analysis, Internal Pentest, Reporting, Defense).
- CLI integration — works with Claude Code, OpenCode, and Codex out of the box
via
agent/.claude/,agent/.opencode/, andagent/.codex/configurations. - Engagement workspaces — per-engagement
scope.json,intel.md,findings/,artifacts/,reports/. Resumable. - Scope-aware guardrails —
agent/scripts/hooks/scope-check.shblocks commands that target hosts outside the authorized list. - Reference library — OWASP Top 10 (Web), OWASP API Security Top 10, AD methodology (enumeration, Kerberos, ADCS), tool cheat-sheets (nmap, ffuf, nuclei, httpx, subfinder, amass).
- Containerized toolbox (optional) — Kali + mitmproxy + all-in-one Docker images.
- Report-ready output — VRT-classified findings, CVSS 3.1 vectors, exec summary, remediation backlog.
red-team-ai-agent/
├── README.md # this file
├── install.sh # bootstrapper
├── LICENSE # MIT
├── SECURITY.md # responsible-disclosure policy
├── CONTRIBUTING.md
├── docs/ # architecture, methodology, usage
│
├── orchestrator/ # Next.js web UI
│ ├── app/ # routes (Next 14 app router)
│ │ ├── page.tsx # main page
│ │ ├── layout.tsx
│ │ ├── globals.css
│ │ └── api/chat/route.ts # server-side proxy to Anthropic (API key stays here)
│ ├── components/ # React components
│ │ ├── RedTeamAgent.tsx
│ │ ├── AuthorizationGate.tsx # scope-acceptance modal
│ │ ├── ScopeBanner.tsx
│ │ ├── PhaseTimeline.tsx
│ │ ├── ModeSelector.tsx
│ │ ├── QuickActions.tsx
│ │ └── ChatPanel.tsx
│ ├── lib/ # types, modes, system prompts
│ └── package.json
│
└── agent/ # CLI agent + reference library
├── CLAUDE.md # entry point for Claude Code
├── AGENTS.md # agent roster + role matrix
├── operator-core.md # canonical orchestrator prompt
├── .claude/agents/ # Claude Code subagent definitions
├── .codex/agents/ # Codex agent configs
├── .opencode/
│ ├── opencode.json
│ ├── commands/ # /auth /engage /recon /vuln-analyze /report ...
│ ├── prompts/agents/ # 8 specialist agent prompts (.txt)
│ ├── plugins/ # engagement-hooks
│ └── instructions/
├── engagements/ # per-engagement workspaces (gitignored)
├── references/ # methodology & checklists
│ ├── INDEX.md
│ ├── handoff-protocols.md
│ ├── wildcard-mode.md
│ ├── vuln-checklists/ # OWASP A01–A10
│ ├── api-security/ # OWASP API1–API10
│ ├── active-directory/ # enumeration, Kerberos, ADCS
│ └── tools/recon/ # nmap, ffuf, nuclei, httpx, subfinder, amass
├── scripts/ # engagement-management shell helpers
│ ├── hooks/scope-check.sh
│ ├── allocate_finding_id.sh
│ ├── append_finding.sh
│ ├── append_log_entry.sh
│ ├── finalize_engagement.sh
│ ├── check_findings_integrity.sh
│ ├── schema.sql
│ ├── templates/intel.md
│ └── proxy_addon.py # mitmproxy engagement-aware addon
└── docker/ # Optional Kali / mitmproxy / allinone images
├── docker-compose.yml
├── kali-redteam/Dockerfile
├── mitmproxy/Dockerfile
└── redteam-allinone/
- Node.js >= 18.18 (for the orchestrator)
- An Anthropic API key (https://console.anthropic.com/)
- Optional: one or more AI CLIs (Claude Code, OpenCode, Codex)
- Optional: Docker (for the containerized toolbox)
git clone https://github.com/Forbidden30/Red-Team-Ai-Agent-.git
cd Red-Team-Ai-Agent-
./install.shThen edit orchestrator/.env.local and set:
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-6cd orchestrator
npm run devOpen http://localhost:3000.
./install.sh --with-docker
docker compose -f agent/docker/docker-compose.yml up -d
docker compose -f agent/docker/docker-compose.yml exec kali-toolbox bash- Open the web orchestrator at http://localhost:3000.
- Click Define scope and fill in:
- Engagement name (e.g.
acme-q2-pentest) - Authorizer name + email
- In-scope targets (one per line;
*.example.com,10.20.0.0/16, etc.) - Out-of-scope rules (optional)
- Tick the authorization confirmation.
- Engagement name (e.g.
- Select a mode (OSINT / Recon / Vuln Analysis / Internal / Report / Defense).
- Pick a Quick prompt or type your own. Output streams from the operator agent.
For CLI use, see CLI Integration.
The same engagement workspace works from any of three CLIs.
cd Red-Team-Ai-Agent-
claudeagent/.claude/agents/operator.md is loaded automatically. Subagents
(recon-specialist, vulnerability-analyst, …) are available via prompt switching.
cd Red-Team-Ai-Agent-/agent
opencodeopencode.json wires up the operator + slash commands (/auth, /engage, /recon,
/vuln-analyze, /exploit, /report, /status, /resume, /stop, …).
cd Red-Team-Ai-Agent-
codex --agent agent/.codex/agents/operator.toml| Agent | Phase(s) | Purpose |
|---|---|---|
operator |
all | Orchestrates the engagement, routes work to specialists |
recon-specialist |
recon, collect | External & active recon, attack-surface mapping |
source-analyzer |
collect, test | Code / artifact review (source, JS, mobile, binaries) |
vulnerability-analyst |
test | Vulnerability triage, CVE lookup, CVSS / VRT scoring |
exploit-developer |
exploit | Minimal proof-of-impact, in-scope only, advisory-style |
fuzzer |
test, exploit | Targeted fuzzing strategy (web / binary / protocol) |
osint-analyst |
recon, exploit | Open-source intel — leaks, dorks, breach data, infra DNA |
report-writer |
report | Findings, exec summary, remediation backlog, VRT/CVSS scoring |
See agent/AGENTS.md for details.
/auth — confirm written authorization, set scope
/engage NAME — initialize agent/engagements/NAME/
/recon — passive + active recon
/enumerate — surface enumeration
/vuln-analyze — triage findings
/exploit F-NN — proof of impact
/osint — OSINT enrichment
/report — draft findings + exec summary
/stop /resume — pause/restart cleanly
This tool is for authorized security testing only. Unauthorized access to computer systems is illegal under the CFAA (US), Computer Misuse Act (UK), IT Act (India), and similar laws worldwide. By using this software you agree to:
- Operate only against systems you own or have explicit written authorization to test.
- Stay within the documented engagement scope.
- Follow responsible-disclosure norms when reporting findings.
See SECURITY.md for the project's responsible-disclosure policy.
MIT — see LICENSE.
Structure inspired by NeoTheCapt/RedteamAgent. References derive from OWASP, PortSwigger Web Security Academy, HackTricks, SpecterOps research, MITRE ATT&CK, and ProjectDiscovery tool documentation.