redpilot 2.0.0

AI-orchestrated offensive security — one target in, a written assessment out.
_{Built for Kali, bug bounty, and red-team work · authorized testing only}

_{AI engines  ·  Google Gemini  ·  Anthropic Claude  ·  Ollama  ·  LM Studio  ·  Shodan}

Point RedPilot at a target and it runs the engagement. The AI plans the recon, RedPilot runs the tools on your machine, and you get the findings plus a written assessment — built for Kali, bug bounty, and red-team work.

pip install "redpilot[ai]"        # RedPilot + the AI providers
redpilot setup                    # pick your AI + database (SQLite = zero setup)
redpilot agent target.com         # the AI plans → runs → reports, end to end

_{⚠️ Authorized testing only — see the Legal Disclaimer.}

What you get

• redpilot agent — an autonomous agent: the AI chooses which modules to run, chains them, and writes the assessment.
• Recon toolkit — one pipeline wrapping subfinder, httpx, nuclei, katana, dnsx, ffuf and more.
• AI threat analysis after every scan — Gemini, Claude, Ollama, or LM Studio — plus PoC and remediation code on demand.
• Full attack surface — recon, network + CVE mapping, web audit, crawler, passive Shodan intel.
• Scope-safe & stealthy — engagement-scope enforcement, TOR, proxy rotation, UA randomization.
• Zero-setup storage — MongoDB, or a local SQLite file with nothing to install.
• Share it — dark-mode HTML/JSON reports, CSV export, and scan diffing.
• Run it as a platform — a headless HTTP API (REST + WebSocket), an MCP server/client, a built-in web dashboard + Prometheus metrics, a plugin SDK, a hardened Docker/Caddy deploy, and multi-engagement workspaces with RBAC.

◇ How it works

One target in, a written assessment out. Reach RedPilot from any surface — the CLI, the HTTP API, the web dashboard, or an MCP host — and they all drive the same engine: every active step is scope-gated and audit-logged, runs the modules on your machine, and the AI writes it up.

%%{init: {'theme':'base','themeVariables':{'fontFamily':'JetBrains Mono, ui-monospace, monospace','primaryColor':'#11161a','primaryTextColor':'#E0A82E','primaryBorderColor':'#C98B1C','lineColor':'#5B6672','clusterBkg':'#0a0e12','clusterBorder':'#1c2630'}}}%%
flowchart TD
  subgraph SURF [ surfaces ]
    direction LR
    CLI[redpilot CLI]:::box
    API[HTTP API<br/>REST · WebSocket]:::box
    DASH[web dashboard<br/>+ /metrics]:::box
    MCP[MCP server<br/>Claude Desktop]:::box
  end

  CLI --> SVC
  API --> SVC
  DASH --> API
  MCP --> SVC

  SVC{{ service engine }}:::hot
  SVC --> GATE[/ scope check · RBAC · audit /]:::dim
  GATE --> A{{ AI plans the assessment }}:::hot

  A --> R[recon<br/>subdomains · DNS · WHOIS]:::box
  A --> TK
  A --> W[web audit<br/>headers · TLS · paths]:::box
  A --> N[network<br/>nmap · CVE mapping]:::box

  subgraph TK [recon toolkit]
    direction LR
    s1[subfinder<br/>assetfinder] --> s2[dnsx] --> s3[httpx] --> s4[katana<br/>hakrawler] --> s5[wayback<br/>gau] --> s6[ffuf] --> s7[nuclei]
  end

  R --> F[( findings )]:::hot
  TK --> F
  W --> F
  N --> F

  F --> DB[( MongoDB / SQLite )]:::dim
  F --> AI[[ AI assessment<br/>router · cache · budget ]]:::hot
  AI --> REP[report<br/>HTML · JSON · CSV]:::hot

  classDef hot fill:#0a0e12,stroke:#E0A82E,color:#E0A82E,stroke-width:1px;
  classDef box fill:#11161a,stroke:#C98B1C,color:#C6D0DA;
  classDef dim fill:#11161a,stroke:#2b3a2f,color:#9AA6B2;

_{Run the whole chain with redpilot agent target.com (AI-planned) or redpilot pipeline target.com (deterministic discovery → validation → remediation → report), any single stage on its own (redpilot recon, redpilot toolkit, redpilot scan, …), or the same over the API / dashboard / MCP — all scope-gated and audit-logged through one engine.}

◇ Core feature set

subfinder / assetfinder  →  dnsx  →  httpx  →  katana / hakrawler
                                             →  waybackurls / gau  →  ffuf  →  nuclei

◇ Demo

A 60-second tour — safe to run offline against example.com:

redpilot tools                       # see which recon binaries are installed
redpilot tools --install             # install the Go recon suite (requires Go)
redpilot scope add example.com       # define engagement scope
redpilot toolkit example.com         # subfinder → httpx → katana → nuclei pipeline
redpilot report example.com --format html --with-ai   # shareable HTML report + AI analysis

▶️ Generate a walkthrough GIF for your fork with scripts/demo.sh — recipe in docs/demo.md.

◇ Installation

From PyPI (recommended)

pip install redpilot                 # core
pip install "redpilot[ai]"           # + Google / Claude / OpenAI-compatible providers
pip install "redpilot[intel]"        # + Shodan passive intelligence
pip install "redpilot[ai,intel]"     # everything

From source (for development)

git clone https://github.com/geevarghesekthomas84-sys/redpilot.git
cd redpilot
python -m venv venv
source venv/bin/activate         # Windows: venv\Scripts\activate
pip install -e ".[ai,intel,dev]" # editable install with all extras + test tools

First run

cp .env.example .env             # configure providers / MongoDB / stealth
redpilot --install-completion        # shell tab-completion (optional)
redpilot tools --install             # install the recon toolkit binaries (needs Go)
redpilot setup                       # interactive configuration wizard

Requirements: Python 3.11+, Nmap, MongoDB (local or remote)

Optional: RustScan for ultra-fast port discovery · the recon toolkit binaries (redpilot tools to check) · Shodan via the intel extra above

◇ Docker / Podman

The fastest way to get running — no manual setup of MongoDB or Python environment needed.

# 1. Start MongoDB + RedPilot in one command
docker-compose up -d

# 2. Run any scan
docker-compose run redpilot recon target.com
docker-compose run redpilot scan target.com --scanner rustscan --ports 1-65535

# 3. Drop into interactive AI shell
docker-compose run redpilot shell

# Override the entire command
docker-compose run redpilot export target.com --format csv

Note: docker-compose.yml uses network_mode: host so Nmap/RustScan can reach real targets.
.env is automatically mounted from the project root — add your API keys there.

Podman works with the same files — swap the command:

podman compose up -d                 # Podman 4.4+ (uses the compose provider)
# or: podman-compose up -d
podman compose run redpilot recon target.com

On SELinux hosts (Fedora/RHEL), if a bind mount gives "permission denied", add a :z (shared) / :Z (private) suffix to the volume — e.g. ./scope.json:/app/scope.json:z — or run with --security-opt label=disable. Rootless Podman already has host networking; network_mode: host is honored.

◇ Configuration

Copy .env.example to .env and configure your providers:

# ─── AI Provider (choose one) ────────────────────────────────────
AI_PROVIDER=google            # google | claude | ollama | lmstudio

# Remote providers
GOOGLE_API_KEY=your_key
ANTHROPIC_API_KEY=your_key

# Model overrides (optional — defaults shown)
GOOGLE_MODEL=gemini-2.0-flash
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# Local providers
OLLAMA_URL=http://localhost:11434/v1
OLLAMA_MODEL=llama3.2             # optional, auto-detected
LM_STUDIO_URL=http://localhost:1234/v1
LM_STUDIO_MODEL=your-model        # optional, auto-detected from loaded model

# ─── APIs ────────────────────────────────────────────────────────
NIST_API_KEY=your_key             # free: https://nvd.nist.gov/developers/request-an-api-key
SHODAN_API_KEY=your_key           # free: https://account.shodan.io/register

# ─── Stealth / OpsSec ────────────────────────────────────────────
USE_TOR=false
PROXY_FILE=./proxies.txt
RANDOM_USER_AGENT=true

# ─── Database ────────────────────────────────────────────────────
REDPILOT_DB_BACKEND=mongo                      # mongo (default) | sqlite
REDPILOT_MONGO_URI=mongodb://localhost:27017   # used when backend = mongo
REDPILOT_SQLITE_PATH=redpilot.db                   # used when backend = sqlite

No MongoDB? Use the SQLite fallback. Set REDPILOT_DB_BACKEND=sqlite (or pick it in redpilot setup) and RedPilot stores everything in a local file — no database server needed. Great for quick/offline use.

◇ Usage

📖 Full command reference with all flags and examples → COMMANDS.md

# ─── Autonomous Agent (AI plans & chains the modules) ────────────
redpilot agent target.com                                # plan → confirm → run → AI assessment
redpilot agent target.com --goal "find web vulns" -y     # steer it, skip the prompt
redpilot agent target.com --dry-run                      # preview the plan only

# ─── Reconnaissance ──────────────────────────────────────────────
redpilot recon target.com                                # Recon + AI + Shodan (if key set)
redpilot recon target.com --passive --no-ai              # Passive OSINT only

# ─── Network Scanning ────────────────────────────────────────────
redpilot scan target.com                                 # Nmap + AI analysis
redpilot scan target.com --scanner rustscan --ports 1-65535  # RustScan → Nmap
redpilot scan target.com --intensity aggressive          # Deep scan (-sV -sC -O -A)

# ─── Web Security ────────────────────────────────────────────────
redpilot webscan https://target.com                      # Full web audit + AI
redpilot crawl https://target.com --depth 3              # Spider + AI

# ─── External Recon Toolkit ──────────────────────────────────────
redpilot tools                                           # Show which recon tools are installed
redpilot toolkit target.com                              # Full pipeline: subfinder→httpx→katana→nuclei
redpilot toolkit target.com --no-nuclei --no-crawl       # Passive recon only (no active scan)
redpilot toolkit target.com --fuzz --wordlist wl.txt     # Add ffuf content fuzzing
redpilot toolkit target.com --nuclei-severity critical,high --output recon.json

# ─── AI Provider Shortcuts (all context-safe) ────────────────────
redpilot test-ai                                         # Health check + status table
redpilot chat "How do I bypass a WAF?"                   # Configured provider
redpilot gemini "Explain CVE-2024-1234"                  # Google Gemini
redpilot claude "Write an Ansible remediation task"      # Anthropic Claude
redpilot ollama "List SMB exploitation paths"            # Ollama — live streaming
redpilot lmstudio "Analyze these HTTP headers"           # LM Studio — live streaming

# ─── AI Analysis on past scans ───────────────────────────────────
redpilot ai <scan_id>                                    # Re-analyze (no re-scan)
redpilot ai <scan_id> --provider ollama                  # Use Ollama for this run

# ─── Exploit & Remediation ───────────────────────────────────────
redpilot poc <finding_id>                                # Generate Python exploit script
redpilot poc <finding_id> --output exploit.py
redpilot remediate <finding_id> --format ansible         # Fix code (ansible/terraform/bash)

# ─── Operations ──────────────────────────────────────────────────
redpilot export target.com --format csv                  # Export findings to CSV
redpilot export target.com --format json                 # Export findings to JSON
redpilot diff <scan_id_1> <scan_id_2>                    # Compare two scans
redpilot scope show                                      # View engagement scope
redpilot scope add target.com                            # Add to scope
redpilot scope remove target.com                         # Remove from scope
redpilot watch target.com --interval 3600 --module webscan   # 24/7 monitoring
redpilot report target.com --format html                 # Premium HTML report
redpilot history                                         # Past scan records
redpilot shell                                           # Interactive AI shell
redpilot update                                          # Update RedPilot to latest

◇ MCP server ^{new in 1.5}

Run RedPilot as an MCP server so Claude Desktop (or any MCP host) can drive it with natural language — recon, the toolkit, scans, and the autonomous agent, all as native tools, locally.

pip install "redpilot[mcp]"           # installs the MCP support
redpilot scope add target.com         # authorize a target first
redpilot mcp                          # serve over stdio

Add it to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "redpilot": { "command": "redpilot", "args": ["mcp"] }
  }
}

Then ask Claude things like "recon target.com and summarize the risks."

Safety model (a model is calling these):

• Scope is enforced inside every tool — out-of-scope targets are refused, and there is no bypass flag exposed to the model.
• agent_run is plan-only by default; active execution needs an explicit dry_run=false and an in-scope target.
• No raw-command tool — the model only selects RedPilot's fixed modules.
• Every active call is written to an audit log (logs/audit.jsonl).

See docs/ROADMAP_V2.md for the full platform plan (HTTP API, model router, secure gateway, dashboard).

◇ HTTP API ^{new in 1.6}

Run RedPilot as a service — everything the CLI does, over REST, with live scan events over WebSocket. Secure by default: every endpoint except /health and /version needs an API key, and active scans are scope-gated.

pip install "redpilot[api]"
export REDPILOT_API_KEYS="your-secret-key"   # or let it print a generated one
redpilot serve                               # http://127.0.0.1:8000  (docs at /docs)

# start a scan (returns a job id), then stream it
curl -s -XPOST localhost:8000/scans -H "X-API-Key: $KEY" \
     -H 'content-type: application/json' \
     -d '{"module":"toolkit","target":"example.com"}'
# → {"job_id":"…","status":"running"}
#   GET /jobs/{id}         → status + typed findings
#   WS  /ws/jobs/{id}      → live step/finding events

Bind --host 0.0.0.0 only behind the reverse-proxy gateway (TLS/auth) — see the roadmap. Interactive API docs are at /docs.

◇ Dashboard & metrics ^{new in 1.10}

The API ships a self-contained web console and Prometheus metrics — no extra install beyond redpilot[api].

redpilot serve
open http://127.0.0.1:8000/          # the dashboard (enter your API key to connect)
curl -s localhost:8000/metrics       # Prometheus scrape target

• Dashboard (/) — a single vanilla-JS page in the CLI's amber/steel theme: connect with your X-API-Key, see scope/tools status, launch a scan or an agent run (with dry-run), watch live events over WebSocket, and read the findings and audit tables as they fill.
• Metrics (/metrics) — scans started/completed/failed by module, findings by severity, agent runs by mode, and auth failures, in Prometheus text format. Labels are aggregate only (no target names), so the endpoint is safe to scrape without leaking engagement data. Left open so scrapers need no key.
• Audit (/audit) — key-protected tail of the JSONL audit log: the who/what/target/when record written for every active action.

◇ Secure deploy ^{new in 1.8}

Run the API hardened, behind a TLS reverse-proxy gateway — one command.

cd deploy
cp .env.example .env            # set REDPILOT_API_KEYS (and REDPILOT_DOMAIN for real TLS)
docker compose up -d --build    # Caddy gateway + API (SQLite, zero-setup)
curl -k https://localhost/health

• Caddy gateway — automatic TLS, security headers, request-size cap; opt-in mTLS and rate-limiting. Only the gateway is exposed; the API is internal.
• Hardened API container — non-root, read-only root FS (state under /data), cap_drop: ALL, no-new-privileges, resource limits, healthcheck.
• CI image scanning (Trivy) + sops/age secrets.

Full guide — mTLS, rate-limiting, secrets, and the authorized-egress note — in SECURITY_HARDENING.md.

◇ Extend it ^{new in 1.9}

Plugins — add your own scan module by subclassing PluginModule and advertising it via the redpilot.modules entry-point group:

# your plugin's pyproject.toml
[project.entry-points."redpilot.modules"]
myscan = "my_pkg.module:MyScanModule"

redpilot plugins            # list discovered plugins
redpilot myscan target.com  # runs like a built-in (CLI / API / MCP)

Consume external MCP servers — point RedPilot at other MCP servers (CVE/OSINT feeds, your own tools) in Claude-Desktop shape (mcp_servers.json):

redpilot mcp-tools          # list tools exposed by the configured servers

Plugins and external MCP tools run through the CLI/API/service — they are not auto-added to the autonomous agent's fixed action set (that stays curated).

Machine-readable output — every surface returns the same typed models; emit their JSON Schema so downstream tooling can validate RedPilot output:

redpilot schema --write docs/schemas     # or: GET /schema over the API

Architecture, request flow, and all three extension seams (modules, providers, output consumers) are documented in docs/ARCHITECTURE.md; the checked-in schemas live in docs/schemas/.

◇ Engagements & RBAC ^{new in 1.11}

Run multiple isolated engagements with role-based access control — for teams and concurrent client work. Each engagement has its own scope, audit trail, and report storage; nothing leaks between them.

# create an engagement (optionally with a signed client authorization)
export REDPILOT_AUTH_SIGNING_KEY="…"      # minting key for authorizations
redpilot engagements --create "Acme Corp" --scope "acme.com,api.acme.com" \
                 --authorized-by "ciso@acme.com" --retention-days 90
redpilot engagements                       # list them

Roles — map API keys to a role and the engagements they may touch:

export REDPILOT_PRINCIPALS='{
  "LEAD_KEY":  {"name":"lead","role":"lead","engagements":["*"]},
  "OP_KEY":    {"name":"op","role":"operator","engagements":["acme-corp"]},
  "VIEW_KEY":  {"name":"client","role":"viewer","engagements":["acme-corp"]}
}'
redpilot serve

Over the API, send X-API-Key (→ your role) and X-Engagement: <id> to pick the workspace. GET /whoami shows your identity; GET/POST /engagements list/create them. A viewer gets 403 on active endpoints; access outside your granted engagements is 403; an unknown engagement is 404.

• Signed authorizations — with REDPILOT_AUTH_SIGNING_KEY set, an engagement's authorization is a tamper-evident HMAC over its id, scope hash, authorizer, and expiry. Editing the stored scope or expiry invalidates it, and active runs are refused without a valid, unexpired signature.
• Backwards-compatible — with no REDPILOT_PRINCIPALS set, your existing REDPILOT_API_KEYS act as all-access leads and a single default engagement is used, so nothing changes until you opt in.

◇ AI providers

Model routing, caching & budgets (1.7+): the agent routes each task to a model you choose (REDPILOT_MODEL_PLAN, REDPILOT_MODEL_ANALYZE, …, comma-separated for fallbacks), caches responses (REDPILOT_CACHE=off to disable), and bounds each run (REDPILOT_BUDGET_CALLS / REDPILOT_BUDGET_SECONDS). Unset = your provider's default.

Quick Comparison

Ollama Setup

# 1. Install Ollama → https://ollama.com
# 2. Pull a model
ollama pull llama3.2
ollama pull qwen2.5-coder   # great for exploit/remediation code

# 3. Set in .env
AI_PROVIDER=ollama
OLLAMA_URL=http://localhost:11434/v1   # default, change if remote
OLLAMA_MODEL=llama3.2                  # optional — auto-detected if not set

# 4. Test connection
redpilot test-ai

# 5. Use shortcut (tokens stream in real-time)
redpilot ollama "List exploitation paths for open SMB ports"

LM Studio Setup

# 1. Download LM Studio → https://lmstudio.ai
# 2. Load any GGUF model in the app
# 3. Go to: Local Server tab → Start Server

# 4. Set in .env
AI_PROVIDER=lmstudio
LM_STUDIO_URL=http://localhost:1234/v1  # default
LM_STUDIO_MODEL=your-model-name         # optional — auto-detected from loaded model

# 5. Test connection
redpilot test-ai

# 6. Use shortcut (tokens stream in real-time)
redpilot lmstudio "Analyze these HTTP headers for security risks"

All AI name variants accepted: lmstudio, lm-studio, lm_studio all work as AI_PROVIDER values.

◇ Shodan intel

Enrich every redpilot recon scan with passive Shodan intelligence — open ports, org, ISP, and country — without sending any packets to the target.

# 1. Get a free API key → https://account.shodan.io/register
# 2. Add to .env
SHODAN_API_KEY=your_api_key

# 3. Install the Shodan library
pip install shodan

# 4. Run recon — Shodan data is fetched automatically
redpilot recon target.com

◇ Diff & export

# View scan history to get IDs
redpilot history

# Compare two scans — see what's new, fixed, or unchanged
redpilot diff <older_scan_id> <newer_scan_id>

# Export all findings for a target to CSV (for clients)
redpilot export target.com --format csv
redpilot export target.com --format json --output /tmp/findings.json

◇ Safety & hardening

RedPilot is authorized-testing-only tooling, built fail-safe. Layered controls:

• Scope enforcement — out-of-scope targets are refused (fail-closed when a scope is set); signed authorizations gate active runs.
• Overly-broad-scan rejection — wildcards, 0.0.0.0/0, and huge CIDRs are refused at the input boundary, so you can't accidentally scan the internet.
• RBAC + rate limiting — roles (viewer/operator/lead) and per-key limits (429) over the API.
• No shell execution of untrusted text — external tools run as argument lists (never shell=True), guarded by a destructive-command denylist; AI/target output is sanitized before it's logged, stored, or shown.
• Secret redaction — API keys and tokens are scrubbed from every log sink.
• Supply chain — Trivy + pip-audit + a CycloneDX SBOM in CI.

# Dry-run the pipeline without touching any target (synthetic findings):
REDPILOT_MOCK=1 redpilot webscan target.com        # any module / the agent honor it
REDPILOT_MOCK=1 redpilot agent target.com -y       # or over the API: options {"mock": true}

Full detail — assets, trust boundaries, and a per-workflow risk classification — in docs/THREAT_MODEL.md. Deploy hardening in SECURITY_HARDENING.md.

◇ Engagement scope

# Initialise scope (creates scope.json in current directory)
redpilot scope add target.com
redpilot scope add 10.0.0.0/24

# View current scope
redpilot scope show

# Remove a target
redpilot scope remove 10.0.0.0/24

# Use a custom scope file
redpilot scope show --file engagement_scope.json

◇ Project structure

redpilot/
├── redpilot/
│   ├── cli/          # Typer CLI — all commands
│   ├── core/         # Async engine & BaseModule
│   ├── agent/        # autonomous AI orchestrator (redpilot agent)
│   ├── pipeline/     # staged workflow: discovery→validation→remediation→report
│   ├── orchestration/# model router, response cache, run budgets
│   ├── modules/      # recon, network, webscan, crawler, toolkit
│   ├── service/      # UI-free facade (scope, audit, events) shared by API/MCP
│   ├── api/          # FastAPI REST + WebSocket, metrics, dashboard
│   ├── mcp/          # MCP server (expose tools) + client (consume servers)
│   ├── plugins/      # third-party scan-module SDK + registry
│   ├── workspaces/   # multi-engagement workspaces + RBAC + signed auth
│   ├── utils/        # AI orchestrator, proxy, risk, validator, scope, logger
│   ├── database/     # MongoDB (Motor) / SQLite async backends
│   └── reports/      # HTML & JSON report generator
├── deploy/           # hardened Docker image + Caddy TLS gateway + compose
├── tests/            # Pytest test suite
├── docs/             # roadmap, demo recipe, extra docs
├── .github/          # CI + release + security workflows, issue/PR templates
├── Dockerfile        # Python 3.12-slim + nmap + Go recon suite
├── docker-compose.yml # MongoDB 7 + RedPilot with healthcheck
├── scope.json        # Engagement scope (auto-created)
├── COMMANDS.md       # Full command reference
└── .env.example      # Configuration template

◇ Contributing & releasing

Contributions are welcome — see CONTRIBUTING.md and the Code of Conduct. In short:

pip install -e ".[dev]"
pytest -q                 # tests
ruff check redpilot tests     # lint
python -m build           # wheel

CI runs these on every push and pull request. Notable changes go in CHANGELOG.md.

Releasing to PyPI is automated via Trusted Publishing: tag a version and push, and the Release workflow builds and publishes it.

git tag v1.0.1
git push origin v1.0.1        # → builds, checks, and publishes to PyPI

One-time setup: on PyPI, add a trusted publisher for this repo pointing at the workflow.yml workflow and the pypi environment.

◇ Stealth & OpsSec

◇ Support

RedPilot is free and MIT-licensed. If it saves you time, you can support development:

buymeacoffee.com/geevarghes2

◇ Legal disclaimer

This tool is intended strictly for authorized security testing, research, and educational purposes only. The developer assumes no liability for any misuse or damage caused. Always obtain explicit written permission from the target organization before conducting any security tests.