Ateebshaikh21/red-team-ai

# 🔴 Autonomous Red Team AI [](https://python.org) [](LICENSE) [](https://owasp.org/Top10/) ## 📌 What It Does Autonomous Red Team AI is a full **penetration testing recon pipeline** that chains together: 1. **Nmap** — Port scanning & service/version fingerprinting 2. **NIST NVD API v2.0** — CVE lookup mapped to discovered services 3. **Anthropic Claude LLM** — Intelligent attack surface analysis & exploit path generation 4. **Multi-format Reports** — JSON + Markdown + styled HTML Tested against **DVWA**, **Metasploitable2**, and **HackTheBox** machines. ## 🏗️ Architecture Target IP/Host │ ▼ ┌─────────────┐ │ NmapScanner │ ← python-nmap, service/version detection └──────┬──────┘ │ [open ports + service banners] ▼ ┌─────────────┐ │ CVEMapper │ ← NIST NVD API v2.0, rate-limited, cached └──────┬──────┘ │ [enriched services + CVE list] ▼ ┌──────────────────┐ ┌─────────────────────┐ │ LLMAnalyzer │ │ ExploitSuggester │ │ (Claude API) │ │ (rule-based, fast) │ └──────┬───────────┘ └──────────┬──────────┘ └──────────┬───────────────┘ │ [analysis + exploit paths + OWASP mapping] ▼ ┌──────────────────┐ │ ReportGenerator │ ← JSON + Markdown + HTML └──────────────────┘ ## ⚡ Quick Start ### 1. Clone & Install git clone https://github.com/yourname/red-team-ai.git cd red-team-ai # Install dependencies pip install -r requirements.txt # Install nmap (required system dependency) # Ubuntu/Debian: sudo apt install nmap # macOS: brew install nmap ### 2. Configure API Keys cp .env.example .env # Edit .env and add your keys: # ANTHROPIC_API_KEY=sk-ant-... # NVD_API_KEY=... (optional, but increases NVD rate limits) Get API keys: - **Anthropic:** https://console.anthropic.com - **NVD (optional):** https://nvd.nist.gov/developers/request-an-api-key ### 3. Run Your First Scan # Quick scan (fast, no LLM) python main.py quick --target 192.168.56.101 # Full pipeline (Nmap + CVE + LLM analysis) python main.py scan --target 192.168.56.101 # Deep scan with full analysis python main.py scan --target 192.168.56.101 --mode deep --output ./reports ## 🎯 Commands ### `scan` — Full Pipeline python main.py scan --target [--mode quick|deep] [--output DIR] Runs the complete pipeline: Nmap → CVE lookup → LLM analysis → reports. | Flag | Default | Description | |------|---------|-------------| | `--target` | required | Target IP or hostname | | `--mode` | `quick` | `quick` (top 1000 ports) or `deep` (all ports + OS) | | `--output` | `./reports` | Report output directory | ### `quick` — Fast Recon Only python main.py quick --target [--output DIR] Nmap + CVE lookup only. No LLM call. Fastest mode for rapid triage. ### `report` — Regenerate from JSON python main.py report --input ./reports/report_192_168_56_101.json Regenerates Markdown + HTML from an existing JSON scan result. ## 🧪 Testing with DVWA DVWA (Damn Vulnerable Web Application) is the easiest way to test locally. # 1. Start DVWA via Docker bash test-configs/setup_lab.sh # 2. Scan it python main.py scan --target 127.0.0.1 # 3. View HTML report open reports/report_127_0_0_1_*.html Expected findings on DVWA: - Port 80: Apache HTTP → SQL injection, XSS (OWASP A03, A01) - Port 3306: MySQL → weak auth, remote root (OWASP A07) ## 🧪 Testing with Metasploitable2 Metasploitable2 is a deliberately vulnerable Linux VM with ~20+ services. # Run in VirtualBox with Host-Only networking # Default IP: 192.168.56.101, creds: msfadmin/msfadmin python main.py scan --target 192.168.56.101 --mode deep Expected findings: FTP, SSH, Telnet, SMB (EternalBlue), MySQL, PostgreSQL, VNC, SMTP... ## 📊 Performance | Metric | Value | |--------|-------| | Manual recon baseline | ~3 hours | | Automated pipeline (quick) | ~8–12 minutes | | Automated pipeline (deep) | ~20–35 minutes | | **Recon time reduction** | **~60%** | The reduction comes from: - Parallel CVE lookups with caching (no repeated NVD queries) - LLM instantly correlating findings vs manual research - Structured report generation vs manual write-up ### Run Benchmarks python benchmarks/benchmark_runner.py --target 192.168.56.101 --runs 3 ## 📁 Project Structure red-team-ai/ ├── main.py # CLI entrypoint (Typer) ├── src/ │ ├── scanner.py # Nmap wrapper & parser │ ├── cve_mapper.py # NVD API v2.0 CVE lookup │ ├── llm_analyzer.py # Claude API integration │ ├── exploit_suggester.py # Rule-based exploit mapping │ ├── report_generator.py # JSON + Markdown + HTML output │ └── utils.py # Timing, logging, helpers ├── tests/ │ ├── test_scanner.py # Mocked nmap tests │ └── test_cve_mapper.py # Mocked NVD API tests ├── test-configs/ │ ├── dvwa_config.json │ ├── metasploitable_config.json │ └── setup_lab.sh # Docker lab setup ├── benchmarks/ │ └── benchmark_runner.py ├── reports/ # Generated reports (git-ignored) ├── .env.example ├── requirements.txt └── CLAUDE.md # Claude Code project context ## 🔒 CVE Mapping & OWASP Coverage The pipeline maps discovered services to: | Service | Common CVEs | OWASP Category | |---------|-------------|----------------| | OpenSSH | CVE-2018-15473, CVE-2016-6210 | A07 - Auth Failures | | Apache HTTP | CVE-2021-41773, CVE-2017-7679 | A03 - Injection | | SMB/Samba | CVE-2017-0144 (EternalBlue) | A05 - Misconfiguration | | MySQL | CVE-2012-2122, CVE-2016-6662 | A03 - Injection | | VNC | CVE-2006-2369 | A07 - Auth Failures | | FTP | CVE-2011-2523 (vsftpd backdoor) | A05 - Misconfiguration | ## 🚀 Running Tests # All tests pytest tests/ -v # With coverage pip install pytest-cov pytest tests/ --cov=src --cov-report=term-missing ## ⚠️ Legal & Ethics **This tool is for authorized penetration testing only.** - Only scan systems you own or have explicit written permission to test - Never run against production systems without a signed scope agreement - All testing in this repo uses intentionally vulnerable VMs (DVWA, Metasploitable) - The authors are not responsible for misuse ## 🛠️ Tech Stack | Component | Technology | |-----------|-----------| | Language | Python 3.10+ | | Port Scanning | python-nmap (Nmap wrapper) | | CVE Data | NIST NVD REST API v2.0 | | LLM | Anthropic Claude (claude-sonnet-4-20250514) | | CLI | Typer + Rich | | Testing | pytest + pytest-mock | | Reports | JSON + Markdown + HTML | ## 📄 License MIT — See [LICENSE](LICENSE)