Autonomous AI red team framework that chains reconnaissance, exploitation, and post-exploitation into a single pipeline, then triages findings, implements code fixes, and opens pull requests.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/71/d9c21d41c6f604ee08cdf4108938e45f01e82006f887a93450dd5f6c74902c9e/e60b7424951a4e3ae217e88c536e28667802751d4f25477511c8ebef21c4f51e-display-v1.webp" alt="RedAmon Logo" width="120"/>
<br/>
<img src="https://raw.githubusercontent.com/samugit83/redamon/master/docs/assets/title.svg" alt="RedAmon" width="340"/>
<br/>
<b><i><big><big>Unmask the hidden before the world does</big></big></i></b>
</p>
<p align="center" style="font-size: 120%;">
An autonomous AI framework that chains reconnaissance, exploitation, and post-exploitation into a single pipeline, then goes further by triaging every finding, implementing code fixes, and opening pull requests on your repository. From first packet to merged patch, with human oversight at every critical step.
</p>
<br/>
<p align="center">
<a href="https://www.nviso.eu/" target="_blank" rel="sponsored noopener noreferrer"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/nviso-logo-dark.svg"/><img src="https://raw.githubusercontent.com/samugit83/redamon/master/docs/assets/nviso-logo.svg" alt="Sponsored by NVISO" height="55"/></picture></a>
<a href="https://trendshift.io/repositories/21794?utm_source=trendshift-badge&utm_medium=badge&utm_campaign=badge-trendshift-21794" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/21794/daily?language=Python" alt="samugit83%2Fredamon | Trendshift" width="250" height="55"/></a>
</p>
<p align="center">
<a href="https://www.redamon.org/"><img height="34" src="https://img.shields.io/badge/%F0%9F%8C%90_Website-redamon.org-A01025?style=for-the-badge&labelColor=000000" alt="RedAmon Website"/></a>
<a href="https://discord.gg/5Zyff6PrUF"><img height="34" src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=for-the-badge&logo=discord&logoColor=white&labelColor=000000" alt="Discord Community"/></a>
<a href="https://t.me/redamon_ai"><img height="34" src="https://img.shields.io/badge/Telegram-Join_Channel-26A5E4?style=for-the-badge&logo=telegram&logoColor=white&labelColor=000000" alt="Telegram Channel"/></a>
<a href="https://youtu.be/XJyQHa4RTbI"><img height="34" src="https://img.shields.io/badge/YouTube-Platform_Tour-FF0000?style=for-the-badge&logo=youtube&logoColor=white&labelColor=000000" alt="RedAmon Platform Tour"/></a>
</p>
<p align="center">
<a href="https://github.com/samugit83/redamon/stargazers"><img height="24" src="https://img.shields.io/github/stars/samugit83/redamon?style=flat&color=2E8B57&label=Stars" alt="GitHub Stars"/></a>
<img height="24" src="https://img.shields.io/badge/v7.2.0-release-2E8B57?style=flat" alt="Version 7.2.0"/>
<img height="24" src="https://img.shields.io/badge/WARNING-SECURITY%20TOOL-B22222?style=flat" alt="Security Tool Warning"/>
<img height="24" src="https://img.shields.io/badge/LICENSE-MIT-4169A1?style=flat" alt="MIT License"/>
<img height="24" src="https://img.shields.io/badge/AI-AUTONOMOUS%20AGENT-6A5ACD?style=flat&logo=openai&logoColor=white" alt="AI Powered"/>
<a href="https://github.com/samugit83/redamon/wiki/AI-Gauntlet"><img height="24" src="https://img.shields.io/badge/%F0%9F%86%95%20AI%20GAUNTLET-OFFENSIVE%20AI%20TESTING-FF6B35?style=flat" alt="AI Gauntlet — Offensive AI Testing"/></a>
<a href="https://github.com/samugit83/redamon/wiki/Fireteam-Parallel-Specialists"><img height="24" src="https://img.shields.io/badge/%F0%9F%94%A5%20FIRETEAM-PARALLEL%20MULTI--AGENT-7C3AED?style=flat" alt="Fireteam Parallel Multi-Agent"/></a>
<a href="https://github.com/samugit83/redamon/blob/master/redamon.wiki/Deploying-to-a-Server.md"><img height="24" src="https://img.shields.io/badge/%F0%9F%9A%80%20ONE%20COMMAND-DEPLOY%20ON%20SERVER-CC7722?style=flat" alt="One Command Deploy on Server"/></a>
<a href="https://github.com/samugit83/redamon/wiki/TrafficMind"><img height="24" src="https://img.shields.io/badge/%F0%9F%95%B8%20TRAFFICMIND-mitmproxy%20CAPTURE-1F6FEB?style=flat" alt="TrafficMind mitmproxy HTTP Capture"/></a>
<img height="24" src="https://img.shields.io/badge/100+-SECURITY%20TOOLS-CC8F00?style=flat&logo=hack-the-box&logoColor=white" alt="100+ Security Tools"/>
<img height="24" src="https://img.shields.io/badge/185,000+-DETECTION%20RULES-8B1142?style=flat" alt="185,000+ Detection Rules"/>
<img height="24" src="https://img.shields.io/badge/400+-AI%20MODELS-04A878?style=flat&logo=huggingface&logoColor=white" alt="400+ AI Models"/>
<img height="24" src="https://img.shields.io/badge/Metasploit-Framework-1A6DAA?style=flat" alt="Metasploit Framework"/>
<img height="24" src="https://img.shields.io/badge/OpenVAS-Scanner-66B245?style=flat" alt="OpenVAS Scanner"/>
<img height="24" src="https://img.shields.io/badge/CypherFix-Auto%20Remediation-00B894?style=flat" alt="CypherFix Auto Remediation"/>
<a href="https://github.com/samugit83/redamon/wiki"><img height="24" src="https://img.shields.io/badge/%F0%9F%93%96_WIKI-FULL%20DOCUMENTATION-1A73E8?style=flat" alt="Wiki Documentation"/></a>
</p>
> **LEGAL DISCLAIMER**: This tool is intended for **authorized security testing**, **educational purposes**, and **research only**. Never use this system to scan, probe, or attack any system you do not own or have explicit written permission to test. Unauthorized access is **illegal** and punishable by law. By using this tool, you accept **full responsibility** for your actions. **[Read Full Disclaimer](https://github.com/samugit83/redamon/blob/master/DISCLAIMER.md)**
> 🏆 **Flagship result:** RedAmon solves **101 / 104 (97.1%)** of the XBOW web-security benchmark **fully black-box**. Every solve ships a complete, unedited raw agent session **and** a reproducible, step-by-step walkthrough: open any row and read exactly how the flag fell, tool call by tool call. Auditable, line by line. See the **[XBOW Validation Benchmark scorecard](https://github.com/samugit83/redamon/wiki/XBOW-Validation-Benchmark)**.
> 📊 **Coverage, measured and self-scored:** the **[Bug Bounty Coverage — The Full Taxonomy Audit (PDF, 124 pages)](https://raw.githubusercontent.com/wiki/samugit83/redamon/docs/RedAmon_Bug_Bounty_Coverage.pdf)** audits RedAmon against all **397** classes of web bug-bounty finding, one line at a time, naming the exact module, skill or scanner behind every verdict, and scoring the recon pipeline and the agentic system separately against their own remit. It is deliberately self-critical, it records what is missing as plainly as what is covered: **134** classes complete, **210** in the build backlog, **44** deliberately excluded, with one explicit decision for every class.
<p align="center">
<img src="https://raw.githubusercontent.com/samugit83/redamon/master/docs/assets/agent.gif" alt="RedAmon Agent Demo" width="100%"/>
</p>
<p align="center">
<a href="https://www.youtube.com/playlist?list=PLKBUWnoi9aaA"><img height="24" src="https://img.shields.io/badge/YouTube-Demos-FF0000?style=flat&logo=youtube&logoColor=white" alt="YouTube - Demos"/></a>
<a href="https://www.youtube.com/playlist?list=PLXp03AyYNPWE"><img height="24" src="https://img.shields.io/badge/YouTube-XBOW_Bench-FF0000?style=flat&logo=youtube&logoColor=white" alt="YouTube - XBOW Bench"/></a>
<a href="https://www.youtube.com/playlist?list=PL_HcrMfo9rCc7HaWIGk-J1YZRPQXSfPIi"><img height="24" src="https://img.shields.io/badge/YouTube-Hacklab-FF0000?style=flat&logo=youtube&logoColor=white" alt="YouTube - Hacklab"/></a>
</p>
<br/>
<h2 align="center">Dynamic Multi-Tool Parallel Recon Pipeline</h2>
<p align="center">
<img src="https://raw.githubusercontent.com/samugit83/redamon/master/docs/assets/recon-pipeline.gif" alt="Parallel recon pipeline in action" width="100%"/>
</p>
<p align="center">
<em>RedAmon launches multiple reconnaissance tools in parallel, each feeding results into a shared knowledge graph in real time. Tools spin up, adapt their scope based on live discoveries, and coordinate without manual intervention. The entire attack surface -- subdomains, ports, endpoints, parameters -- materializes in minutes, not hours.</em>
</p>
<br/>
<h2 align="center">Recon as a Living Knowledge Graph</h2>
<p align="center">
<img src="https://raw.githubusercontent.com/samugit83/redamon/master/docs/assets/redamon-graph.gif" alt="RedAmon Neo4j attack-surface graph rendered in 2D" width="100%"/>
</p>
<p align="center">
<em>Industry-standard scanners chained so each tool's output feeds the next, then merged into a single Neo4j knowledge graph. Findings are deduplicated, relationships are explicit, and the agent inherits a structured, fully connected attack surface ready to query in natural language.</em>
</p>
<br/>
<h1 align="center"><span style="color:#D48A8A">Offense</span> meets <span style="color:#8AAED4">defense</span>. One pipeline, full visibility.</h1>
<p align="center">
<b><samp><big>Reconnaissance ➜ Exploitation ➜ Post-Exploitation ➜ AI Triage ➜ CodeFix Agent ➜ GitHub PR</big></samp></b>
<br/><br/>
RedAmon doesn't stop at finding vulnerabilities, it fixes them. The pipeline starts with a 6-phase reconnaissance engine that maps your target's entire attack surface, then hands control to an autonomous AI agent that validates CVE exploitability, tests credential policies, and maps lateral movement paths. Every finding is recorded in a Neo4j knowledge graph. When the offensive phase completes, CypherFix takes over: an AI triage agent correlates hundreds of findings, deduplicates them, and ranks them by exploitability. Then a CodeFix agent clones your repository, navigates the codebase with 11 code-aware tools, implements targeted fixes, and opens a GitHub pull request, ready for review and merge.
</p>
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/71/83190db39f664102e4ab6ed34689a10c33a918a1c07af0d800beb77cb7722816/973c51766890b123267b2c4392012aa1c1c2f10ff0fa41f37c8a815a0cecb78c-display-v1.webp" alt="CypherFix demo" width="100%"/>
</p>
---
## Roadmap & Community Contributions
We maintain a public **[Project Board](https://github.com/users/samugit83/projects/1)** with upcoming features open for community contributions. Pick a task and submit a PR!
> **Want to contribute?** See [CONTRIBUTING.md](https://github.com/samugit83/redamon/blob/master/CONTRIBUTING.md) for how to get started.
### Maintainers
<table>
<tr>
<td align="center" valign="top" width="50%">
<img src="https://assets.kitploit.com/production/public/readmes/71/a67f24fddf70d34fa9ef754f52bc34a02dc42fad4785cb89dcb5a51f86c7e7d0/bb0d418f304baabe9c1c85d21293415b150502b53e8a1d751932b53f4046ba87-display-v1.webp" alt="Samuele Giampieri" width="120"/><br/>
<b>Samuele Giampieri</b>: Creator, Maintainer & AI Platform Architect<br/><br/>
<small>AI Platform Architect & Full-Stack Lead with 15+ years of freelancing experience and more than 30 projects shipped to production, including enterprise-scale AI agentic systems. AWS-certified (DevOps Engineer, ML Specialty) and IBM-certified AI Engineer. Designs end-to-end ML solutions spanning deep learning, NLP, Computer Vision, and AI Agent systems with LangChain/LangGraph.</small><br/><br/>
<a href="https://www.linkedin.com/in/samuele-giampieri-b1b67597/">LinkedIn</a> · <a href="https://github.com/samugit83">GitHub</a> · <a href="https://www.devergolabs.com/">Devergo Labs</a><br/><br/>
<a href="https://pathbreak.io/"><img src="https://assets.kitploit.com/production/public/readmes/71/862de99d91f21d038f5e87c21b4fd262871f7acba25d3e6649ad8f26dbf8dcc6/e9b3eefb12b852a1fb2cd732e9e037a38c0c07c37783f58e28182240d9464c43-display-v1.webp" alt="Pathbreak - Agentic Cloud Security" width="90"/></a><br/>
<b>From the same creator: <a href="https://pathbreak.io/">Pathbreak - Agentic Cloud Security</a></b><br/>
<i>See the attack path. Then break it.</i><br/><br/>
<small>Pathbreak is an agentic cloud security platform that discovers and validates the real attack paths a threat actor would exploit across your cloud. It catches the control-plane chains most tools miss.</small><br/><br/>
<a href="https://pathbreak.io/"><b>Pathbreak - agentic cloud security</b></a><br/>
<small>pathbreak.io</small>
</td>
<td align="center" valign="top" width="50%">
<img src="https://assets.kitploit.com/production/public/readmes/71/b8073f47305b6ec41e7d3a2ba3ed0002a5d73a014a187e95e314ad96b2fb1127/b229e0005b6101f8ae1b0a532b0ee762973695b24b6899622dfd4a3b148086a6-display-v1.webp" alt="Ritesh Gohil" width="120"/><br/>
<b>Ritesh Gohil</b>: Maintainer & Lead Security Researcher<br/><br/>
<small>Cyber Security Engineer at Workday with over 7 years of experience in Web, API, Mobile, Network, and Cloud penetration testing. Published 11 CVEs in MITRE, with security acknowledgements from Google (4×) and Apple (6×). Secured 200+ web and mobile applications and contributed to Exploit Database, Google Hacking Database, and the AWS Community. Holds AWS Security Specialty, eWPTXv2, eCPPTv2, CRTP, and CEH certifications with expertise in red teaming, cloud security, CVE research, and security architecture review.</small><br/><br/>
<a href="https://www.linkedin.com/in/riteshgohil25/">LinkedIn</a> · <a href="https://github.com/L4stPL4Y3R">GitHub</a>
</td>
</tr>
</table>
> **Anthropic Cyber Verification Program:** the team behind RedAmon is approved under Anthropic's **[Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet)**.
---
## Quick Start
### Prerequisites
- [Docker](https://docs.docker.com/get-docker/) Engine 28.0.0 or newer & Docker Compose v2+ (check with `docker version --format '{{.Server.Version}}'`)
- **macOS:** Docker Desktop, with Memory raised to at least 4 GB (8 GB with `--gvm`) in Settings → Resources. Clone under `~/` so the path is inside the default File Sharing list.
- **Windows:** Docker Desktop with the WSL2 backend, run from inside the WSL2 filesystem (`~/`), not `/mnt/c/`.
That's it. No Node.js, Python, or security tools needed on your host.
#### Minimum System Requirements
| Resource | Without OpenVAS | With OpenVAS (full stack) |
|----------|----------------|--------------------------|
| **CPU** | 2 cores | 4 cores |
| **RAM** | 4 GB | 8 GB (16 GB recommended) |
| **Disk** | 80 GB free | 110 GB free |
> **Without OpenVAS** runs 7 containers: webapp, postgres, neo4j, agent, kali-sandbox, recon-orchestrator, and docker-broker (a filtering Docker-socket proxy that the recon orchestrator's spawned scan containers go through, so they can only launch the known tool images).
> **With OpenVAS** adds 4 more runtime containers (gvmd, ospd-openvas, gvm-postgres, gvm-redis) plus ~8 one-shot data-init containers for vulnerability feeds (~170K+ NVTs). First launch takes ~30 minutes for GVM feed synchronization.
> Dynamic recon and scan containers are spawned on-demand during operations and require additional resources.
> **Disk sizing for a real deployment.** The figures above are bare minimums to build and run the stack (fixed platform footprint: ~70 GB without OpenVAS, ~95 GB with - measured by true on-disk image size after deduplicating the shared Kali base layers). For an **always-on server running real engagements**, add **~100 GB of free space for operational data** - the Neo4j attack graph, scan artifacts/outputs, Postgres, and container logs all grow with use. That means **200 GB without OpenVAS, 250 GB with OpenVAS**, each leaving well over 100 GB free for operations. See the [deployment guide](https://github.com/samugit83/redamon/wiki/Deploying-to-a-Server) for the full breakdown.
### 1. Clone & Install
```bash
git clone https://github.com/samugit83/redamon.git
cd redamon
# Without GVM (lighter, faster startup):
./redamon.sh install
# With GVM / OpenVAS (full stack, ~30 min first run):
./redamon.sh install --gvm
```
The script builds all images and starts the services.
### 2. Create Admin Account
At the end of the install (and on every `./redamon.sh up` or `./redamon.sh update` if no admin exists), you will be prompted in the terminal:
```
[WARN] No admin user found. Let's create one.
Admin name: Your Name
Admin email: [email protected]
Admin password: ********
Confirm password: ********
```
- **Admin name** -- display name shown in the UI (e.g. `Admin`, your name, anything you want).
- **Admin email** -- used to log in at `http://localhost:3000/login`.
- **Admin password** -- minimum 12 characters.
After creation, open **http://localhost:3000** and sign in with the email and password you just set.
> **No prompt appeared?** On a heavy first boot (especially `--gvm`, or a small VM) the webapp can take a while to come up, so the automatic prompt may be skipped. Create the admin at any time with:
>
> ```bash
> ./redamon.sh create-admin
> ```
>
> It waits for the webapp, then prompts for the same details. It is safe to re-run: reusing an existing admin's email resets that password, a new email adds another admin.
**What the admin can do:**
- Switch between all users via the user dropdown in the header (including users without a password).
- Create new users (with or without a password) and assign them `admin` or `standard` roles.
- Set or change any user's password.
- Delete users (except themselves).
- Access the **Users** management page from the header navigation.
**Standard users** can only log in (if they have a password set by an admin), change their own password, and use the app within their own scope. They cannot switch users, create users, or access user management.
If you forget the admin password, reset it from the terminal:
```bash
./redamon.sh reset-password # reset an EXISTING user's password
./redamon.sh create-admin # create the first admin, or reset an admin by re-entering its email
```
Use `create-admin` when no admin exists yet (it upserts on email); `reset-password` only updates a user that already exists.
### 3. Configure
Open **http://localhost:3000/settings** (gear icon in the header) to configure everything. No `.env` file is needed.
- **LLM Providers** -- add API keys for OpenAI, Anthropic, OpenRouter, AWS Bedrock, or any OpenAI-compatible endpoint (Ollama, vLLM, Groq, etc.). Each provider can be tested before saving. The model selector in project settings **dynamically fetches** available models from configured providers.
- **API Keys** -- Tavily, Shodan, SerpAPI, NVD, Vulners, URLScan, and threat intelligence keys (Censys, FOFA, OTX, Netlas, VirusTotal, ZoomEye, CriminalIP) to enable extended agent capabilities (web search, OSINT, CVE lookups, passive threat intel). **Uncover multi-engine search** keys (Quake, Hunter, PublicWWW, HunterHow, Google, Onyphe, Driftnet) expand target discovery across 13 search engines -- shared keys (Shodan, Censys, FOFA, etc.) are automatically reused. Supports **key rotation** -- configure multiple keys per tool with automatic round-robin rotation to avoid rate limits.
- **Tunneling** -- configure ngrok or chisel for reverse shell tunneling. Changes apply immediately without container restarts.
All settings are stored per-user in the database. See the **[AI Model Providers](https://github.com/samugit83/redamon/wiki/AI-Model-Providers)** wiki page for detailed setup instructions.
### 4. Open the Webapp
Go to **http://localhost:3000** -- create a project, configure your target, and start scanning.
> For a detailed walkthrough of every feature, check the **[Wiki](https://github.com/samugit83/redamon/wiki)**.
>
> Prefer video? Watch the **[Product Demos playlist](https://www.youtube.com/playlist?list=PLKBUWnoi9aaA)** on YouTube for step-by-step tutorials.
>
> Having issues? See the **[Troubleshooting](https://github.com/samugit83/redamon/blob/master/docs/readmes/TROUBLESHOOTING.md)** guide or the **[Wiki Troubleshooting](https://github.com/samugit83/redamon/wiki/Troubleshooting)** page.
### Management Commands
All lifecycle management is handled by a single script:
| Command | Description |
|---------|-------------|
| `./redamon.sh install` | Build + start lightweight (no GVM, no Knowledge Base, Tavily-only web search) |
| `./redamon.sh install --kbase` | Build + start with the local Knowledge Base (~4.4 GB heavier) |
| `./redamon.sh install --gvm` | Build + start with GVM/OpenVAS |
> Flags can be combined: `./redamon.sh install --gvm --kbase`
| Command | Description |
|---------|-------------|
| **`./redamon.sh update`** | **Pull latest version, smart-rebuild only changed services (preserves your install-time GVM/KB choice)** |
| `./redamon.sh up` | Start services (auto-detects GVM and KB mode from install) |
| `./redamon.sh up dev` | Start in dev mode with hot-reload (auto-detects GVM and KB mode) |
| `./redamon.sh down` | Stop services (preserves data) |
| `./redamon.sh status` | Show running services, version, GVM mode, KB state, plugin platform state (and why it cannot run on this host, when it cannot) |
| `./redamon.sh clean` | Remove containers + images, keep data |
| `./redamon.sh create-admin` | Create the admin login (or reset it) -- use if no prompt appeared at install |
| `./redamon.sh reset-password` | Reset an existing user's password from the terminal |
| `./redamon.sh supply-chain-sync [ecosystems]` | Populate the offline OSV database for the supply-chain feature (default: `npm`; e.g. `npm PyPI Go`) |
| `./redamon.sh purge` | Remove everything including all data |
### Updating to a New Version
Just run:
```bash
./redamon.sh update
```
The script pulls the latest code from GitHub, detects which Dockerfiles and source files changed, rebuilds only the affected images, and restarts the updated services. Your databases, scan results, and reports are preserved -- volumes are never deleted.
> **One-time note when a release adds a new background service.** `update` re-execs the freshly-pulled script so new build/start rules apply automatically -- but only for the script version you are updating *from*. When updating *from a version that predates this self-heal* (i.e. your first update onto it), run `./redamon.sh up` once right after `update` so any newly added core service is started:
>
> ```bash
> ./redamon.sh update && ./redamon.sh up
> ```
>
> `up` is idempotent -- it starts only what is missing and leaves running containers untouched. After this one-time step, plain `./redamon.sh update` handles everything on its own.
> **Upgrading across 6.9 (repository reorganization).** 6.9 grouped the top-level directories under `scanners/`, `services/`, `testing/`, `tooling/` and `docs/`. `git pull` moves only tracked files, so data that git does not track -- the knowledge-base index, past scan outputs, and the single-host deploy `.env` and TLS material -- would otherwise be left behind at the old paths. `update` (and `up`/`status`) migrate it for you automatically and print what moved. If any file was written by a container as root and could not be moved, finish it with:
>
> ```bash
> sudo ./redamon.sh migrate-layout
> ```
The webapp also checks for updates automatically and shows a notification in the UI when a new version is available.
### Deploy to a Server (Production)
The Quick Start above runs RedAmon locally on `localhost`. To run a shared, internet-reachable instance on a Linux server (EC2, DigitalOcean, Hetzner, or bare metal), use the **single-host deploy** in [`tooling/deploy/single-host/`](https://github.com/samugit83/redamon/blob/master/tooling/deploy/single-host). It drives `redamon.sh` over SSH from your laptop and wraps the stack in the internet-facing security layer RedAmon omits by default: nginx + TLS (Let's Encrypt), a host firewall, SSH hardening, and fail2ban, with a single public HTTPS origin so only the login page is reachable and everything else stays bound to loopback.
```bash
cd tooling/deploy/single-host
cp .env.example .env # set HOST_IP, DOMAIN, SSH_KEY_PATH, OPERATOR_ALLOW_CIDRS,
# LETSENCRYPT_EMAIL, ADMIN_* ...
./deploy.sh init # first build takes 30-60 min, then log in at https://<domain>/
```
Full walkthrough: [Wiki: Deploying to a Server](https://github.com/samugit83/redamon/wiki/Deploying-to-a-Server). Complete reference: [tooling/deploy/single-host/README.md](https://github.com/samugit83/redamon/blob/master/tooling/deploy/single-host/README.md).
### Development Mode
For contributors and active development with **Next.js fast refresh**:
```bash
./redamon.sh up dev # auto-detects GVM mode from install
```
Tool images are built automatically on first run if they don't exist yet. The dev override swaps the production webapp image for a dev container with your source code volume-mounted. Every file save triggers instant hot-reload in the browser.
#### When to Rebuild vs Restart
| What changed | Action needed |
|-------------|---------------|
| `webapp/src/` (frontend code) | Nothing -- Next.js hot-reload handles it in dev mode |
| `agentic/*.py` (agent Python code) | `docker compose build agent && docker compose up -d agent` (source is baked into the image, so `restart` alone won't pick up `.py` changes) |
| `recon_orchestrator/*.py` | `docker compose restart recon-orchestrator` |
| `mcp/servers/*.py` (MCP servers) | `docker compose restart kali-sandbox` |
| `agentic/Dockerfile` or `agentic/requirements.txt` | `docker compose build agent && docker compose up -d agent` |
| `recon_orchestrator/Dockerfile` or its `requirements.txt` | `docker compose build recon-orchestrator && docker compose up -d recon-orchestrator` |
| `mcp/kali-sandbox/Dockerfile` | `docker compose build kali-sandbox && docker compose up -d kali-sandbox` |
| `webapp/Dockerfile` or `webapp/package.json` | `docker compose build webapp && docker compose up -d webapp` |
| `recon/Dockerfile` | `docker compose --profile tools build recon` |
| `scanners/gvm_scan/Dockerfile` | `docker compose --profile tools build vuln-scanner` |
| `scanners/github_secret_hunt/Dockerfile` | `docker compose --profile tools build github-secret-hunter` |
| `scanners/trufflehog_scan/Dockerfile` (Secret Multiscanner) | `docker compose --profile tools build trufflehog-scanner` |
| `scanners/baddns_scan/Dockerfile` or `scanners/baddns_scan/entrypoint.sh` | `docker compose --profile tools build baddns-scanner` |
| `scanners/wcvs/Dockerfile` (web cache poisoning engine) | `docker compose --profile tools build wcvs` |
| `scanners/supply_chain_scan/Dockerfile` (L1 scanner) | `docker compose --profile tools build supply-chain` |
| `scanners/supply_chain_analyzer/` (DIRTY analyzer; entrypoint is baked) | `docker compose --profile tools build supply-chain-analyzer` |
| `docker-compose.yml` | `docker compose up -d` (re-creates affected containers) |
| `prisma/schema.prisma` | `docker compose exec webapp npx prisma db push` |
**Rebuild a single service:**
```bash
docker compose build <service> # Rebuild one image
docker compose up -d --no-deps <service> # Restart only that service
```
**Common dev commands:**
```bash
docker compose ps # Check service status
docker compose logs -f <service> # Follow logs for a service
docker compose down # Stop all (preserves volumes)
docker compose --profile tools down --rmi local # Remove built images
docker compose --profile tools down --rmi local --volumes --remove-orphans # Full cleanup
```
**Reclaim disk space:**
```bash
docker system df # Show Docker disk usage (add -v for per-image breakdown)
docker image prune -f # Remove dangling images (auto-run by `./redamon.sh install` and `update`)
docker builder prune -f # Drop unused build cache (auto-run after every successful build; opt out with REDAMON_NO_AUTO_PRUNE=1)
docker builder prune -af # Drop ALL build cache, including what the current images reuse -- frees no extra disk and makes the next rebuild cold
docker container prune -f # Remove stopped containers
```
> For a complete development reference -- hot-reload rules, common commands, important rules, and AI-assisted coding guidelines -- see the **[Developer Guide](https://github.com/samugit83/redamon/blob/master/docs/readmes/README.DEV.md)**.
---
### Knowledge Base (RAG-Enhanced Web Search)
The agent's `web_search` tool includes a local **Knowledge Base** -- a RAG pipeline that searches curated security datasets (GTFOBins, LOLBAS, OWASP WSTG, NVD CVEs, ExploitDB, Nuclei templates, and agent skill docs) before falling back to Tavily web search. When the KB returns a high-confidence match, Tavily is skipped entirely for faster, offline-capable results.
**How it works:** When the KB is enabled, `install` / `up` / `update` builds a lightweight KB index (~1,200 chunks in 10-15 min on CPU). At query time, the agent runs a hybrid retrieval pipeline (FAISS vector search + Neo4j fulltext), reranks with a cross-encoder, and checks a confidence threshold. If the score is high enough, results come from the local KB. Otherwise, it falls back to Tavily or merges both.
**Default behavior:** The KB is **opt-in**. `./redamon.sh install` produces a lightweight install (~4.4 GB lighter, Tavily-only web search). To enable the local KB, pass `--kbase`:
```bash
./redamon.sh install --kbase
```
On first install with `--kbase`, RedAmon detects your hardware (GPU / CPU / API) and offers a quick-start profile. The choice is persisted, so subsequent `update` / `up` commands respect it without re-passing the flag.
**Speed up ingestion with API embeddings:** By default, embeddings run locally on CPU/GPU. On CPU-only machines, large datasets (ExploitDB, NVD) can take hours. You can offload embedding to an external API by creating a `.env` file from the template:
```bash
cp .env.example .env
```
Then configure the embedding API in `.env`:
| Variable | Default | Description |
|----------|---------|-------------|
| `KB_EMBEDDING_USE_API` | `false` | Set to `true` to use API-based embeddings instead of local model |
| `KB_EMBEDDING_API_BASE_URL` | *(empty = OpenAI)* | Any OpenAI-compatible endpoint (Ollama, vLLM, LiteLLM, Together AI, Azure) |
| `KB_EMBEDDING_API_KEY` | *(empty)* | API key for the embedding provider |
| `KB_EMBEDDING_API_MODEL` | `text-embedding-3-small` | Model name (provider-specific) |
| `NVD_API_KEY` | *(empty)* | Free NVD API key for 10x faster CVE ingestion |
Example with Ollama (free, local, no API key cost):
```bash
KB_EMBEDDING_USE_API=true
KB_EMBEDDING_API_BASE_URL=http://host.docker.internal:11434/v1
KB_EMBEDDING_API_KEY=ollama
KB_EMBEDDING_API_MODEL=nomic-embed-text
```
> **Important:** Ingestion and query must use the same model. If you switch models, rebuild the index: `make -C services/knowledge_base kb-rebuild-lite MODE=docker`
**Manage the KB:**
```bash
./redamon.sh kb build lite # Build with lite profile (~30-60s with API)
./redamon.sh kb build standard # Add NVD CVEs
./redamon.sh kb update nvd # Incremental NVD refresh
./redamon.sh kb stats # Show index statistics
./redamon.sh kb rebuild lite # Wipe and rebuild from scratch
```
> For full technical documentation -- query pipeline, data sources, ingestion profiles, scoring, security model -- see the **[Knowledge Base Technical Reference](https://github.com/samugit83/redamon/blob/master/docs/readmes/README.KBASE.md)** or the **[Wiki: Knowledge Base & Web Search](https://github.com/samugit83/redamon/wiki/Knowledge-Base-Web-Search)**.
---
## Table of Contents
- [Full Wiki Documentation](https://github.com/samugit83/redamon/wiki)
- [Overview](#overview)
- [Built for Enterprise, Secure by Design](#built-for-enterprise-secure-by-design)
- [Security & Threat Model](#security--threat-model)
- [Feature Highlights](#feature-highlights)
- [System Architecture](#system-architecture)
- [Components](#components)
- [Documentation](#documentation)
- [Troubleshooting](#troubleshooting)
- [RedAmon HackLab](#redamon-hacklab)
- [Community Showcase](#community-showcase)
- [Legal](#legal)
---
## Overview
RedAmon is a modular, containerized penetration testing framework that chains automated reconnaissance, AI-driven exploitation, and graph-powered intelligence into a single, end-to-end offensive security pipeline. Every component runs inside Docker (no tools installed on your host) and communicates through well-defined APIs so each layer can evolve independently.
---
[Read more](https://github.com/samugit83/redamon)