{"id":"11f149a8-5612-49a6-b270-f6a76ac19f0a","slug":"redpilot","kind":"mcp","name":"redpilot","summary":"🎯 AI-orchestrated offensive security framework. Automated recon, CVE mapping, exploit POC generation & remediation across a discovery β†’ validation β†’ report pipeline. CLI Β· API Β· MCP Β· dashboard. Powe","owner":"geevarghesekthomas84-sys","repoUrl":"https://github.com/geevarghesekthomas84-sys/redpilot","license":"MIT","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-05-03T13:04:17.000Z","addedAt":"2026-10-21T17:19:00.518Z","logoUrl":"https://avatars.githubusercontent.com/u/228019183?u=c7c967364547cd653a557317d686476cbd186e7f&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics","developer-tools"],"tags":["ai","asynchronous","cybersecurity","exploit-automation","offensive-security","pentesting","python","reconnaissance"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T15:57:14.917Z","sample":false,"url":"https://conduits.dev/tools/redpilot","language":"Python","transports":["stdio"],"install":{"pypi":"redpilot"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"\n
\n\n\"RedPilot\n\n\n \"AI\n\n\n

AI-orchestrated offensive security β€” one target in, a written assessment out.
\nBuilt for Kali, bug bounty, and red-team work Β· authorized testing only

\n\n

\n \"PyPI\"\n \"ci\"\n \"python\"\n \"license\"\n \"stars\"\n \"Buy\n

\n\n

\n \"CLI\"\n \"HTTP\n \"MCP\"\n \"Dashboard\"\n \"Metrics\"\n \"Deploy\"\n \"RBAC\"\n

\n\nAI engines  Β·  Google Gemini  Β·  Anthropic Claude  Β·  Ollama  Β·  LM Studio  Β·  Shodan\n\n
\n\n---\n\n> **Point RedPilot at a target and it runs the engagement.** The AI plans the recon,\n> RedPilot runs the tools on your machine, and you get the findings plus a written\n> assessment β€” built for Kali, bug bounty, and red-team work.\n\n```bash\npip install \"redpilot[ai]\" # RedPilot + the AI providers\nredpilot setup # pick your AI + database (SQLite = zero setup)\nredpilot agent target.com # the AI plans β†’ runs β†’ reports, end to end\n```\n\n⚠️ Authorized testing only β€” see the Legal Disclaimer.\n\n### What you get\n\n- **`redpilot agent`** β€” an autonomous agent: the AI chooses which modules to run, chains them, and writes the assessment.\n- **Recon toolkit** β€” one pipeline wrapping `subfinder`, `httpx`, `nuclei`, `katana`, `dnsx`, `ffuf` and more.\n- **AI threat analysis** after every scan β€” Gemini, Claude, Ollama, or LM Studio β€” plus PoC and remediation code on demand.\n- **Full attack surface** β€” recon, network + CVE mapping, web audit, crawler, passive Shodan intel.\n- **Scope-safe & stealthy** β€” engagement-scope enforcement, TOR, proxy rotation, UA randomization.\n- **Zero-setup storage** β€” MongoDB, or a local SQLite file with nothing to install.\n- **Share it** β€” dark-mode HTML/JSON reports, CSV export, and scan diffing.\n- **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**.\n\n---\n\n## β—‡ How it works\n\nOne target in, a written assessment out. Reach RedPilot from any **surface** β€” the\nCLI, the HTTP API, the web dashboard, or an MCP host β€” and they all drive the\n**same engine**: every active step is scope-gated and audit-logged, runs the\nmodules on your machine, and the AI writes it up.\n\n```mermaid\n%%{init: {'theme':'base','themeVariables':{'fontFamily':'JetBrains Mono, ui-monospace, monospace','primaryColor':'#11161a','primaryTextColor':'#E0A82E','primaryBorderColor':'#C98B1C','lineColor':'#5B6672','clusterBkg':'#0a0e12','clusterBorder':'#1c2630'}}}%%\nflowchart TD\n subgraph SURF [ surfaces ]\n direction LR\n CLI[redpilot CLI]:::box\n API[HTTP API
REST Β· WebSocket]:::box\n DASH[web dashboard
+ /metrics]:::box\n MCP[MCP server
Claude Desktop]:::box\n end\n\n CLI --> SVC\n API --> SVC\n DASH --> API\n MCP --> SVC\n\n SVC{{ service engine }}:::hot\n SVC --> GATE[/ scope check Β· RBAC Β· audit /]:::dim\n GATE --> A{{ AI plans the assessment }}:::hot\n\n A --> R[recon
subdomains Β· DNS Β· WHOIS]:::box\n A --> TK\n A --> W[web audit
headers Β· TLS Β· paths]:::box\n A --> N[network
nmap Β· CVE mapping]:::box\n\n subgraph TK [recon toolkit]\n direction LR\n s1[subfinder
assetfinder] --> s2[dnsx] --> s3[httpx] --> s4[katana
hakrawler] --> s5[wayback
gau] --> s6[ffuf] --> s7[nuclei]\n end\n\n R --> F[( findings )]:::hot\n TK --> F\n W --> F\n N --> F\n\n F --> DB[( MongoDB / SQLite )]:::dim\n F --> AI[[ AI assessment
router Β· cache Β· budget ]]:::hot\n AI --> REP[report
HTML Β· JSON Β· CSV]:::hot\n\n classDef hot fill:#0a0e12,stroke:#E0A82E,color:#E0A82E,stroke-width:1px;\n classDef box fill:#11161a,stroke:#C98B1C,color:#C6D0DA;\n classDef dim fill:#11161a,stroke:#2b3a2f,color:#9AA6B2;\n```\n\nRun 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.\n\n---\n\n## β—‡ Core feature set\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\n\n### 🧠 AI Intelligence Suite\nConnect to any leading AI model for Red Team-grade analysis. After **every scan**, RedPilot automatically sends findings to your configured AI and generates a module-specific intelligence report covering attack paths, exploitation techniques, CVE correlation, and actionable remediation β€” printed directly in the terminal.\n\n**Supported providers (all work with every command):**\n| Provider | Type | Shortcut |\n|---|---|---|\n| Google Gemini 2.0 Flash | ☁️ Remote | `redpilot gemini` |\n| Anthropic Claude 3.5 | ☁️ Remote | `redpilot claude` |\n| Ollama (local) | πŸ’» Streaming | `redpilot ollama` |\n| LM Studio (local) | πŸ’» Streaming | `redpilot lmstudio` |\n\n> Local providers (**Ollama / LM Studio**) stream tokens in real-time as they are generated. \n> Add `--no-ai` to any scan command to skip AI analysis.\n\n\n\n### πŸ•΅οΈ Stealth & OpsSec Engine\nEvery single request is wrapped in configurable operational security layers.\n\n- Native **TOR** integration (`socks5://`)\n- Rotating **SOCKS5/HTTP proxy** chains\n- Dynamic **User-Agent** fingerprint rotation\n- Per-module **concurrency** & request delay controls\n\n### πŸ“‘ Passive Shodan Intel\nSet `SHODAN_API_KEY` in `.env` to enrich every recon scan with passive Shodan data β€” open ports, org, ISP, and country β€” **without sending a single packet to the target**.\n\n
\n\n### πŸ” Reconnaissance Module\nBuild a complete attack surface map before firing a single payload.\n\n- Passive subdomain enumeration via `crt.sh`\n- Active DNS brute-forcing (12+ common prefixes)\n- DNS Record audit: SPF, DMARC, AXFR zone transfer\n- WHOIS registrant email exposure analysis\n- **Shodan passive IP intelligence** (optional)\n- **External recon toolkit** (`redpilot toolkit`) β€” chains `subfinder`, `assetfinder`, `dnsx`, `httpx`, `katana`, `hakrawler`, `waybackurls`, `gau`, `ffuf` & `nuclei` into one pipeline (run `redpilot tools` to check installs)\n\n\n\n### 🌐 Web Security Auditor\nDeep-dive assessment of web application security posture.\n\n- Security headers: CSP, HSTS, XFO, X-Content-Type\n- Cookie flags: `Secure`, `HttpOnly`, `SameSite`\n- Sensitive path probing: `.env`, `.git`, admin portals\n- TLS/SSL: protocol versions, certificate expiry\n\n
\n\n### πŸ”Œ Network Intelligence\nHigh-speed, configurable port scanning with automated threat correlation.\n\n- **Nmap** integration with `light`, `normal`, `aggressive` profiles\n- **RustScan** turbo-discovery (async TCP) β†’ hand-off to Nmap for deep analysis\n- Service version detection & OS fingerprinting\n- Automated CVE mapping via **NIST NVD API** (rate-limited, supports API key)\n\n\n\n### πŸ“Š Reporting & Export\nGenerate executive-grade deliverables.\n\n- πŸŒ‘ **Dark-mode HTML Dashboard** with severity-ranked findings\n- πŸ“„ **Structured JSON** output for pipelines\n- πŸ“‹ **CSV Export** (`redpilot export`) for client-ready spreadsheets\n- πŸ” **Scan Diff** (`redpilot diff`) β€” compare any two scans visually\n\n
\n\n### 🧰 External Recon Toolkit\nChain a suite of best-in-class open-source recon binaries into a single pipeline with `redpilot toolkit`. Each stage feeds the next, and every tool is **optional** β€” missing binaries are skipped gracefully (check status with `redpilot tools`).\n\n```\nsubfinder / assetfinder β†’ dnsx β†’ httpx β†’ katana / hakrawler\n β†’ waybackurls / gau β†’ ffuf β†’ nuclei\n```\n\n| Tool | Role | Tool | Role |\n|---|---|---|---|\n| `subfinder` | Passive subdomain enum | `waybackurls` | Wayback URL harvesting |\n| `assetfinder` | Passive asset discovery | `gau` | getallurls historical fetch |\n| `dnsx` | Fast DNS resolution | `ffuf` | Content / directory fuzzing |\n| `httpx` | HTTP probing & fingerprinting | `nuclei` | Template-based vuln scanning |\n| `katana` | Next-gen crawling | `hakrawler` | Fast endpoint crawler |\n\n
\n\n---\n\n## β—‡ Demo\n\nA 60-second tour β€” safe to run offline against `example.com`:\n\n```bash\nredpilot tools # see which recon binaries are installed\nredpilot tools --install # install the Go recon suite (requires Go)\nredpilot scope add example.com # define engagement scope\nredpilot toolkit example.com # subfinder β†’ httpx β†’ katana β†’ nuclei pipeline\nredpilot report example.com --format html --with-ai # shareable HTML report + AI analysis\n```\n\n> ▢️ Generate a walkthrough GIF for your fork with [`scripts/demo.sh`](scripts/demo.sh) β€” recipe in [`docs/demo.md`](docs/demo.md).\n\n---\n\n## β—‡ Installation\n\n### From PyPI (recommended)\n\n```bash\npip install redpilot # core\npip install \"redpilot[ai]\" # + Google / Claude / OpenAI-compatible providers\npip install \"redpilot[intel]\" # + Shodan passive intelligence\npip install \"redpilot[ai,intel]\" # everything\n```\n\n### From source (for development)\n\n```bash\ngit clone https://github.com/geevarghesekthomas84-sys/redpilot.git\ncd redpilot\npython -m venv venv\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\npip install -e \".[ai,intel,dev]\" # editable install with all extras + test tools\n```\n\n### First run\n\n```bash\ncp .env.example .env # configure providers / MongoDB / stealth\nredpilot --install-completion # shell tab-completion (optional)\nredpilot tools --install # install the recon toolkit binaries (needs Go)\nredpilot setup # interactive configuration wizard\n```\n\n> **Requirements:** Python 3.11+, [Nmap](https://nmap.org), MongoDB (local or remote)\n>\n> **Optional:** [RustScan](https://github.com/RustScan/RustScan) for ultra-fast port discovery\n> Β· the [recon toolkit](#-external-recon-toolkit) binaries (`redpilot tools` to check)\n> Β· Shodan via the `intel` extra above\n\n---\n\n## β—‡ Docker / Podman\n\nThe fastest way to get running β€” no manual setup of MongoDB or Python environment needed.\n\n```bash\n# 1. Start MongoDB + RedPilot in one command\ndocker-compose up -d\n\n# 2. Run any scan\ndocker-compose run redpilot recon target.com\ndocker-compose run redpilot scan target.com --scanner rustscan --ports 1-65535\n\n# 3. Drop into interactive AI shell\ndocker-compose run redpilot shell\n\n# Override the entire command\ndocker-compose run redpilot export target.com --format csv\n```\n\n> **Note:** `docker-compose.yml` uses `network_mode: host` so Nmap/RustScan can reach real targets. \n> `.env` is automatically mounted from the project root β€” add your API keys there.\n\n**Podman** works with the same files β€” swap the command:\n\n```bash\npodman compose up -d # Podman 4.4+ (uses the compose provider)\n# or: podman-compose up -d\npodman compose run redpilot recon target.com\n```\n\n> On **SELinux** hosts (Fedora/RHEL), if a bind mount gives \"permission denied\",\n> add a `:z` (shared) / `:Z` (private) suffix to the volume β€” e.g.\n> `./scope.json:/app/scope.json:z` β€” or run with `--security-opt label=disable`.\n> Rootless Podman already has host networking; `network_mode: host` is honored.\n\n---\n\n## β—‡ Configuration\n\nCopy `.env.example` to `.env` and configure your providers:\n\n```bash\n# ─── AI Provider (choose one) ────────────────────────────────────\nAI_PROVIDER=google # google | claude | ollama | lmstudio\n\n# Remote providers\nGOOGLE_API_KEY=your_key\nANTHROPIC_API_KEY=your_key\n\n# Model overrides (optional β€” defaults shown)\nGOOGLE_MODEL=gemini-2.0-flash\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022\n\n# Local providers\nOLLAMA_URL=http://localhost:11434/v1\nOLLAMA_MODEL=llama3.2 # optional, auto-detected\nLM_STUDIO_URL=http://localhost:1234/v1\nLM_STUDIO_MODEL=your-model # optional, auto-detected from loaded model\n\n# ─── APIs ────────────────────────────────────────────────────────\nNIST_API_KEY=your_key # free: https://nvd.nist.gov/developers/request-an-api-key\nSHODAN_API_KEY=your_key # free: https://account.shodan.io/register\n\n# ─── Stealth / OpsSec ────────────────────────────────────────────\nUSE_TOR=false\nPROXY_FILE=./proxies.txt\nRANDOM_USER_AGENT=true\n\n# ─── Database ────────────────────────────────────────────────────\nREDPILOT_DB_BACKEND=mongo # mongo (default) | sqlite\nREDPILOT_MONGO_URI=mongodb://localhost:27017 # used when backend = mongo\nREDPILOT_SQLITE_PATH=redpilot.db # used when backend = sqlite\n```\n\n> **No MongoDB? Use the SQLite fallback.** Set `REDPILOT_DB_BACKEND=sqlite` (or pick\n> it in `redpilot setup`) and RedPilot stores everything in a local file β€” no database\n> server needed. Great for quick/offline use.\n\n---\n\n## β—‡ Usage\n\n> πŸ“– **Full command reference with all flags and examples β†’ [COMMANDS.md](COMMANDS.md)**\n\n```bash\n# ─── Autonomous Agent (AI plans & chains the modules) ────────────\nredpilot agent target.com # plan β†’ confirm β†’ run β†’ AI assessment\nredpilot agent target.com --goal \"find web vulns\" -y # steer it, skip the prompt\nredpilot agent target.com --dry-run # preview the plan only\n\n# ─── Reconnaissance ──────────────────────────────────────────────\nredpilot recon target.com # Recon + AI + Shodan (if key set)\nredpilot recon target.com --passive --no-ai # Passive OSINT only\n\n# ─── Network Scanning ────────────────────────────────────────────\nredpilot scan target.com # Nmap + AI analysis\nredpilot scan target.com --scanner rustscan --ports 1-65535 # RustScan β†’ Nmap\nredpilot scan target.com --intensity aggressive # Deep scan (-sV -sC -O -A)\n\n# ─── Web Security ────────────────────────────────────────────────\nredpilot webscan https://target.com # Full web audit + AI\nredpilot crawl https://target.com --depth 3 # Spider + AI\n\n# ─── External Recon Toolkit ──────────────────────────────────────\nredpilot tools # Show which recon tools are installed\nredpilot toolkit target.com # Full pipeline: subfinderβ†’httpxβ†’katanaβ†’nuclei\nredpilot toolkit target.com --no-nuclei --no-crawl # Passive recon only (no active scan)\nredpilot toolkit target.com --fuzz --wordlist wl.txt # Add ffuf content fuzzing\nredpilot toolkit target.com --nuclei-severity critical,high --output recon.json\n\n# ─── AI Provider Shortcuts (all context-safe) ────────────────────\nredpilot test-ai # Health check + status table\nredpilot chat \"How do I bypass a WAF?\" # Configured provider\nredpilot gemini \"Explain CVE-2024-1234\" # Google Gemini\nredpilot claude \"Write an Ansible remediation task\" # Anthropic Claude\nredpilot ollama \"List SMB exploitation paths\" # Ollama β€” live streaming\nredpilot lmstudio \"Analyze these HTTP headers\" # LM Studio β€” live streaming\n\n# ─── AI Analysis on past scans ───────────────────────────────────\nredpilot ai # Re-analyze (no re-scan)\nredpilot ai --provider ollama # Use Ollama for this run\n\n# ─── Exploit & Remediation ───────────────────────────────────────\nredpilot poc # Generate Python exploit script\nredpilot poc --output exploit.py\nredpilot remediate --format ansible # Fix code (ansible/terraform/bash)\n\n# ─── Operations ──────────────────────────────────────────────────\nredpilot export target.com --format csv # Export findings to CSV\nredpilot export target.com --format json # Export findings to JSON\nredpilot diff # Compare two scans\nredpilot scope show # View engagement scope\nredpilot scope add target.com # Add to scope\nredpilot scope remove target.com # Remove from scope\nredpilot watch target.com --interval 3600 --module webscan # 24/7 monitoring\nredpilot report target.com --format html # Premium HTML report\nredpilot history # Past scan records\nredpilot shell # Interactive AI shell\nredpilot update # Update RedPilot to latest\n```\n\n---\n\n## β—‡ MCP server new in 1.5\n\nRun RedPilot as an **MCP server** so Claude Desktop (or any MCP host) can drive it\nwith natural language β€” recon, the toolkit, scans, and the autonomous agent, all\nas native tools, locally.\n\n```bash\npip install \"redpilot[mcp]\" # installs the MCP support\nredpilot scope add target.com # authorize a target first\nredpilot mcp # serve over stdio\n```\n\nAdd it to **Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"redpilot\": { \"command\": \"redpilot\", \"args\": [\"mcp\"] }\n }\n}\n```\n\nThen ask Claude things like *\"recon target.com and summarize the risks.\"*\n\n**Safety model** (a model is calling these):\n- Scope is enforced **inside every tool** β€” out-of-scope targets are refused, and\n there is **no bypass flag** exposed to the model.\n- `agent_run` is **plan-only by default**; active execution needs an explicit\n `dry_run=false` and an in-scope target.\n- **No raw-command tool** β€” the model only selects RedPilot's fixed modules.\n- Every active call is written to an **audit log** (`logs/audit.jsonl`).\n\n> See [`docs/ROADMAP_V2.md`](docs/ROADMAP_V2.md) for the full platform plan\n> (HTTP API, model router, secure gateway, dashboard).\n\n---\n\n## β—‡ HTTP API new in 1.6\n\nRun RedPilot as a service β€” everything the CLI does, over REST, with **live scan\nevents over WebSocket**. Secure by default: every endpoint except `/health` and\n`/version` needs an API key, and active scans are scope-gated.\n\n```bash\npip install \"redpilot[api]\"\nexport REDPILOT_API_KEYS=\"your-secret-key\" # or let it print a generated one\nredpilot serve # http://127.0.0.1:8000 (docs at /docs)\n```\n\n```bash\n# start a scan (returns a job id), then stream it\ncurl -s -XPOST localhost:8000/scans -H \"X-API-Key: $KEY\" \\\n -H 'content-type: application/json' \\\n -d '{\"module\":\"toolkit\",\"target\":\"example.com\"}'\n# β†’ {\"job_id\":\"…\",\"status\":\"running\"}\n# GET /jobs/{id} β†’ status + typed findings\n# WS /ws/jobs/{id} β†’ live step/finding events\n```\n\n| Endpoint | What it does |\n|---|---|\n| `GET /health`, `GET /version` | open health/version |\n| `GET /metrics` | open Prometheus metrics (aggregate only) |\n| `GET /`, `GET /dashboard` | built-in web console (open) |\n| `GET /whoami` | your principal (role + engagements) |\n| `GET /engagements`, `POST /engagements` | list / create engagements (create = lead) |\n| `GET /scope`, `POST /scope` | view / add engagement scope |\n| `GET /tools` | external-tool install status |\n| `GET /audit` | recent active-action audit entries |\n| `POST /scans`, `POST /agent` | start a scan / agent job (202 + job id) |\n| `GET /jobs/{id}` | job status + typed result |\n| `WS /ws/jobs/{id}` | live progress & findings |\n| `GET /scans/recent`, `GET /findings/{id}` | history / findings |\n\n> Bind `--host 0.0.0.0` only behind the reverse-proxy gateway (TLS/auth) β€” see\n> the roadmap. Interactive API docs are at `/docs`.\n\n---\n\n## β—‡ Dashboard & metrics new in 1.10\n\nThe API ships a **self-contained web console** and **Prometheus metrics** β€” no\nextra install beyond `redpilot[api]`.\n\n```bash\nredpilot serve\nopen http://127.0.0.1:8000/ # the dashboard (enter your API key to connect)\ncurl -s localhost:8000/metrics # Prometheus scrape target\n```\n\n- **Dashboard (`/`)** β€” a single vanilla-JS page in the CLI's amber/steel theme:\n connect with your `X-API-Key`, see scope/tools status, launch a scan or an\n agent run (with dry-run), watch **live events over WebSocket**, and read the\n findings and audit tables as they fill.\n- **Metrics (`/metrics`)** β€” scans started/completed/failed by module, findings\n by severity, agent runs by mode, and auth failures, in Prometheus text format.\n Labels are **aggregate only** (no target names), so the endpoint is safe to\n scrape without leaking engagement data. Left open so scrapers need no key.\n- **Audit (`/audit`)** β€” key-protected tail of the JSONL audit log: the\n who/what/target/when record written for every active action.\n\n---\n\n## β—‡ Secure deploy new in 1.8\n\nRun the API hardened, behind a TLS reverse-proxy gateway β€” one command.\n\n```bash\ncd deploy\ncp .env.example .env # set REDPILOT_API_KEYS (and REDPILOT_DOMAIN for real TLS)\ndocker compose up -d --build # Caddy gateway + API (SQLite, zero-setup)\ncurl -k https://localhost/health\n```\n\n- **Caddy gateway** β€” automatic TLS, security headers, request-size cap; opt-in\n **mTLS** and rate-limiting. Only the gateway is exposed; the API is internal.\n- **Hardened API container** β€” non-root, read-only root FS (state under `/data`),\n `cap_drop: ALL`, `no-new-privileges`, resource limits, healthcheck.\n- **CI image scanning** (Trivy) + **sops/age** secrets.\n\n> Full guide β€” mTLS, rate-limiting, secrets, and the authorized-egress note β€”\n> in [`SECURITY_HARDENING.md`](SECURITY_HARDENING.md).\n\n---\n\n## β—‡ Extend it new in 1.9\n\n**Plugins** β€” add your own scan module by subclassing `PluginModule` and\nadvertising it via the `redpilot.modules` entry-point group:\n\n```toml\n# your plugin's pyproject.toml\n[project.entry-points.\"redpilot.modules\"]\nmyscan = \"my_pkg.module:MyScanModule\"\n```\n\n```bash\nredpilot plugins # list discovered plugins\nredpilot myscan target.com # runs like a built-in (CLI / API / MCP)\n```\n\n**Consume external MCP servers** β€” point RedPilot at other MCP servers (CVE/OSINT\nfeeds, your own tools) in Claude-Desktop shape (`mcp_servers.json`):\n\n```bash\nredpilot mcp-tools # list tools exposed by the configured servers\n```\n\n> Plugins and external MCP tools run through the CLI/API/service β€” they are not\n> auto-added to the autonomous agent's fixed action set (that stays curated).\n\n**Machine-readable output** β€” every surface returns the same typed models; emit\ntheir **JSON Schema** so downstream tooling can validate RedPilot output:\n\n```bash\nredpilot schema --write docs/schemas # or: GET /schema over the API\n```\n\n> Architecture, request flow, and all three extension seams (modules, providers,\n> output consumers) are documented in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md);\n> the checked-in schemas live in [`docs/schemas/`](docs/schemas/).\n\n---\n\n## β—‡ Engagements & RBAC new in 1.11\n\nRun multiple **isolated engagements** with **role-based access control** β€” for\nteams and concurrent client work. Each engagement has its own scope, audit\ntrail, and report storage; nothing leaks between them.\n\n```bash\n# create an engagement (optionally with a signed client authorization)\nexport REDPILOT_AUTH_SIGNING_KEY=\"…\" # minting key for authorizations\nredpilot engagements --create \"Acme Corp\" --scope \"acme.com,api.acme.com\" \\\n --authorized-by \"ciso@acme.com\" --retention-days 90\nredpilot engagements # list them\n```\n\n**Roles** β€” map API keys to a role and the engagements they may touch:\n\n```bash\nexport REDPILOT_PRINCIPALS='{\n \"LEAD_KEY\": {\"name\":\"lead\",\"role\":\"lead\",\"engagements\":[\"*\"]},\n \"OP_KEY\": {\"name\":\"op\",\"role\":\"operator\",\"engagements\":[\"acme-corp\"]},\n \"VIEW_KEY\": {\"name\":\"client\",\"role\":\"viewer\",\"engagements\":[\"acme-corp\"]}\n}'\nredpilot serve\n```\n\n| Role | Can |\n|---|---|\n| **viewer** | read scope, tools, findings, audit |\n| **operator** | + launch scans & active agent runs (in allowed engagements) |\n| **lead** | + manage scope, create engagements, sign authorizations |\n\nOver the API, send `X-API-Key` (β†’ your role) and `X-Engagement: ` to pick the\nworkspace. `GET /whoami` shows your identity; `GET/POST /engagements` list/create\nthem. A **viewer** gets `403` on active endpoints; access outside your granted\nengagements is `403`; an unknown engagement is `404`.\n\n- **Signed authorizations** β€” with `REDPILOT_AUTH_SIGNING_KEY` set, an engagement's\n authorization is a tamper-evident HMAC over its id, scope hash, authorizer, and\n expiry. Editing the stored scope or expiry invalidates it, and active runs are\n refused without a valid, unexpired signature.\n- **Backwards-compatible** β€” with no `REDPILOT_PRINCIPALS` set, your existing\n `REDPILOT_API_KEYS` act as all-access **leads** and a single default engagement is\n used, so nothing changes until you opt in.\n\n---\n\n## β—‡ AI providers\n\n> **Model routing, caching & budgets** (1.7+): the agent routes each task to a\n> model you choose (`REDPILOT_MODEL_PLAN`, `REDPILOT_MODEL_ANALYZE`, …, comma-separated\n> for fallbacks), caches responses (`REDPILOT_CACHE=off` to disable), and bounds each\n> run (`REDPILOT_BUDGET_CALLS` / `REDPILOT_BUDGET_SECONDS`). Unset = your provider's default.\n\n### Quick Comparison\n\n| Provider | Type | Model | Privacy | Streaming | Best For |\n| :--- | :---: | :--- | :---: | :---: | :--- |\n| **Google Gemini** | ☁️ Remote | `gemini-2.0-flash` | Low | ❌ | Fastest, largest context |\n| **Anthropic Claude** | ☁️ Remote | `claude-3-5-sonnet-20241022` | Low | ❌ | Report writing, remediation |\n| **Ollama** | πŸ’» Local | auto-detected | βœ… High | βœ… Live | Air-gapped, unlimited usage |\n| **LM Studio** | πŸ’» Local | auto-detected | βœ… High | βœ… Live | Private, no data leaves host |\n\n### Ollama Setup\n\n```bash\n# 1. Install Ollama β†’ https://ollama.com\n# 2. Pull a model\nollama pull llama3.2\nollama pull qwen2.5-coder # great for exploit/remediation code\n\n# 3. Set in .env\nAI_PROVIDER=ollama\nOLLAMA_URL=http://localhost:11434/v1 # default, change if remote\nOLLAMA_MODEL=llama3.2 # optional β€” auto-detected if not set\n\n# 4. Test connection\nredpilot test-ai\n\n# 5. Use shortcut (tokens stream in real-time)\nredpilot ollama \"List exploitation paths for open SMB ports\"\n```\n\n### LM Studio Setup\n\n```bash\n# 1. Download LM Studio β†’ https://lmstudio.ai\n# 2. Load any GGUF model in the app\n# 3. Go to: Local Server tab β†’ Start Server\n\n# 4. Set in .env\nAI_PROVIDER=lmstudio\nLM_STUDIO_URL=http://localhost:1234/v1 # default\nLM_STUDIO_MODEL=your-model-name # optional β€” auto-detected from loaded model\n\n# 5. Test connection\nredpilot test-ai\n\n# 6. Use shortcut (tokens stream in real-time)\nredpilot lmstudio \"Analyze these HTTP headers for security risks\"\n```\n\n> **All AI name variants accepted:** `lmstudio`, `lm-studio`, `lm_studio` all work as `AI_PROVIDER` values.\n\n---\n\n## β—‡ Shodan intel\n\nEnrich every `redpilot recon` scan with **passive Shodan intelligence** β€” open ports, org, ISP, and country β€” without sending any packets to the target.\n\n```bash\n# 1. Get a free API key β†’ https://account.shodan.io/register\n# 2. Add to .env\nSHODAN_API_KEY=your_api_key\n\n# 3. Install the Shodan library\npip install shodan\n\n# 4. Run recon β€” Shodan data is fetched automatically\nredpilot recon target.com\n```\n\n---\n\n## β—‡ Diff & export\n\n```bash\n# View scan history to get IDs\nredpilot history\n\n# Compare two scans β€” see what's new, fixed, or unchanged\nredpilot diff \n\n# Export all findings for a target to CSV (for clients)\nredpilot export target.com --format csv\nredpilot export target.com --format json --output /tmp/findings.json\n```\n\n---\n\n## β—‡ Safety & hardening\n\nRedPilot is **authorized-testing-only** tooling, built fail-safe. Layered controls:\n\n- **Scope enforcement** β€” out-of-scope targets are refused (fail-closed when a\n scope is set); **signed authorizations** gate active runs.\n- **Overly-broad-scan rejection** β€” wildcards, `0.0.0.0/0`, and huge CIDRs are\n refused at the input boundary, so you can't accidentally scan the internet.\n- **RBAC + rate limiting** β€” roles (viewer/operator/lead) and per-key limits\n (`429`) over the API.\n- **No shell execution of untrusted text** β€” external tools run as argument\n lists (never `shell=True`), guarded by a destructive-command denylist;\n AI/target output is sanitized before it's logged, stored, or shown.\n- **Secret redaction** β€” API keys and tokens are scrubbed from every log sink.\n- **Supply chain** β€” Trivy + `pip-audit` + a CycloneDX SBOM in CI.\n\n```bash\n# Dry-run the pipeline without touching any target (synthetic findings):\nREDPILOT_MOCK=1 redpilot webscan target.com # any module / the agent honor it\nREDPILOT_MOCK=1 redpilot agent target.com -y # or over the API: options {\"mock\": true}\n```\n\n> Full detail β€” assets, trust boundaries, and a per-workflow **risk\n> classification** β€” in [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md). Deploy\n> hardening in [`SECURITY_HARDENING.md`](SECURITY_HARDENING.md).\n\n---\n\n## β—‡ Engagement scope\n\n```bash\n# Initialise scope (creates scope.json in current directory)\nredpilot scope add target.com\nredpilot scope add 10.0.0.0/24\n\n# View current scope\nredpilot scope show\n\n# Remove a target\nredpilot scope remove 10.0.0.0/24\n\n# Use a custom scope file\nredpilot scope show --file engagement_scope.json\n```\n\n---\n\n## β—‡ Project structure\n\n```\nredpilot/\nβ”œβ”€β”€ redpilot/\nβ”‚ β”œβ”€β”€ cli/ # Typer CLI β€” all commands\nβ”‚ β”œβ”€β”€ core/ # Async engine & BaseModule\nβ”‚ β”œβ”€β”€ agent/ # autonomous AI orchestrator (redpilot agent)\nβ”‚ β”œβ”€β”€ pipeline/ # staged workflow: discoveryβ†’validationβ†’remediationβ†’report\nβ”‚ β”œβ”€β”€ orchestration/# model router, response cache, run budgets\nβ”‚ β”œβ”€β”€ modules/ # recon, network, webscan, crawler, toolkit\nβ”‚ β”œβ”€β”€ service/ # UI-free facade (scope, audit, events) shared by API/MCP\nβ”‚ β”œβ”€β”€ api/ # FastAPI REST + WebSocket, metrics, dashboard\nβ”‚ β”œβ”€β”€ mcp/ # MCP server (expose tools) + client (consume servers)\nβ”‚ β”œβ”€β”€ plugins/ # third-party scan-module SDK + registry\nβ”‚ β”œβ”€β”€ workspaces/ # multi-engagement workspaces + RBAC + signed auth\nβ”‚ β”œβ”€β”€ utils/ # AI orchestrator, proxy, risk, validator, scope, logger\nβ”‚ β”œβ”€β”€ database/ # MongoDB (Motor) / SQLite async backends\nβ”‚ └── reports/ # HTML & JSON report generator\nβ”œβ”€β”€ deploy/ # hardened Docker image + Caddy TLS gateway + compose\nβ”œβ”€β”€ tests/ # Pytest test suite\nβ”œβ”€β”€ docs/ # roadmap, demo recipe, extra docs\nβ”œβ”€β”€ .github/ # CI + release + security workflows, issue/PR templates\nβ”œβ”€β”€ Dockerfile # Python 3.12-slim + nmap + Go recon suite\nβ”œβ”€β”€ docker-compose.yml # MongoDB 7 + RedPilot with healthcheck\nβ”œβ”€β”€ scope.json # Engagement scope (auto-created)\nβ”œβ”€β”€ COMMANDS.md # Full command reference\n└── .env.example # Configuration template\n```\n\n---\n\n## β—‡ Contributing & releasing\n\nContributions are welcome β€” see [CONTRIBUTING.md](CONTRIBUTING.md) and the\n[Code of Conduct](CODE_OF_CONDUCT.md). In short:\n\n```bash\npip install -e \".[dev]\"\npytest -q # tests\nruff check redpilot tests # lint\npython -m build # wheel\n```\n\nCI runs these on every push and pull request. Notable changes go in\n[CHANGELOG.md](CHANGELOG.md).\n\n**Releasing to PyPI** is automated via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/):\ntag a version and push, and the `Release` workflow builds and publishes it.\n\n```bash\ngit tag v1.0.1\ngit push origin v1.0.1 # β†’ builds, checks, and publishes to PyPI\n```\n\n> One-time setup: on PyPI, add a trusted publisher for this repo pointing at\n> the `workflow.yml` workflow and the `pypi` environment.\n\n---\n\n## β—‡ Stealth & OpsSec\n\n| Variable | Description |\n|---|---|\n| `USE_TOR=true` | Route all requests through TOR (`socks5://127.0.0.1:9050`) |\n| `PROXY_FILE=./proxies.txt` | Rotating SOCKS5/HTTP proxy chain file |\n| `RANDOM_USER_AGENT=true` | Randomise browser User-Agent per request |\n| `NIST_API_KEY=` | NIST NVD API key (10Γ— CVE lookup rate β€” free signup) |\n| `SHODAN_API_KEY=` | Passive Shodan intel in recon (free tier available) |\n\n---\n\n## β—‡ Support\n\nRedPilot is free and MIT-licensed. If it saves you time, you can support development:\n\n\"Buy\n\n[buymeacoffee.com/geevarghes2](https://buymeacoffee.com/geevarghes2)\n\n---\n\n## β—‡ Legal disclaimer\n\n> 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.\n\n---\n\n
\n\nBuilt with πŸ”₯ by **[geevarghesekthomas84-sys](https://github.com/geevarghesekthomas84-sys)**\n\n⭐ If you find RedPilot useful, please consider starring the repository β€” it helps a lot!\n\n
\n"}