redamon

RedAmon is an open-source, self-hosted AI penetration testing framework, positioned as "revealing hidden vulnerabilities before the world discovers them." It chains reconnaissance, exploitation, and post-exploitation into an automated pipeline, and further triages each finding, implements code fixes, and ultimately opens pull requests on code repositories, from the first packet to the merged patch, retaining human oversight at every key step.

Purpose and Positioning

RedAmon is intended for authorized security testing, educational purposes, and research. The official statement explicitly declares: never use this system to scan, probe, or attack any system you do not own or do not have explicit written permission to test; unauthorized access is illegal and will be punished by law; by using this tool, you accept full responsibility for your actions.

Main Capabilities

• Dynamic multi-tool parallel reconnaissance pipeline: launches multiple reconnaissance tools in parallel, with each tool feeding results into a shared knowledge graph in real time; tools adjust scope based on real-time findings and automatically coordinate, so the attack surface (subdomains, ports, endpoints, parameters) can be presented within minutes.
• Reconnaissance as a live knowledge graph: chains industry-standard scanners, with each tool's output feeding into the next and then merged into a single Neo4j knowledge graph; findings are deduplicated, relationships are clear, and agents inherit a structured, fully connected attack surface that can be queried in natural language.
• Complete pipeline: reconnaissance (6-stage reconnaissance engine) → exploitation (autonomous AI agents verify CVE exploitability, test credential strategies, map lateral movement paths) → post-exploitation → AI triage (CypherFix correlates hundreds of findings, deduplicates them, and ranks them by exploitability) → CodeFix agent (clones repositories, navigates the codebase using 11 code-aware tools, implements targeted fixes) → GitHub PR.
• Bidirectional MCP: can connect any MCP server as a tool, and can also be driven by Claude Code or custom-built agents.
• Knowledge base (RAG-enhanced web search): the web_search tool includes a local knowledge base, and before falling back to Tavily web search, it first searches curated security datasets (GTFOBins, LOLBAS, OWASP WSTG, NVD CVEs, ExploitDB, Nuclei templates, and agent skill documentation). When the knowledge base returns high-confidence matches, Tavily is skipped entirely, enabling faster, offline-capable results. At query time, it runs a hybrid retrieval pipeline (FAISS vector search + Neo4j full-text search), reranks with a cross-encoder, and checks confidence thresholdsvalue.

How to Use

Environment requirements: Docker Engine 28.0.0 or newer, Docker Compose v2+. On macOS, Docker Desktop is required with memory increased to at least 4 GB (8 GB when using --gvm), and clone under ~/; on Windows, Docker Desktop with the WSL2 backend is required, running within the WSL2 file system (~/), not /mnt/c/. The host does not need Node.js, Python, or security tools.

Installation steps:

1. Clone and install: run the installation script to build all images and start the services.
2. Create an administrator account: at the end of installation (and on every ./redamon.sh up or ./redamon.sh update when no administrator exists), the terminal prompts for the administrator name, email (used for login http://localhost:3000/login）和密码（至少 12 characters). If the prompt does not appear, you can create an administrator at any time with a command.
3. Configuration: open http://localhost:3000/settings to configure LLM providers (OpenAI, Anthropic, OpenRouter, AWS Bedrock, or any OpenAI-compatible endpoint such as Ollama, vLLM, Groq, etc.), API keys (Tavily, Shodan, SerpAPI, NVD, Vulners, URLScan, and threat intelligence keys, etc.), and tunnels (ngrok or chisel). All settings are stored per user in the database; no .env file is needed.
4. Open the web app: visit http://localhost:3000，创建项目、配置目标并开始扫描。

Management commands: all lifecycle management is handled by a single script, and flags can be combined, e.g. ./redamon.sh install --gvm --kbase. During updates, the script pulls the latest code, detects changed Dockerfiles and source files, rebuilds only the affected images, and restarts the services; the database, scan results, and reports are all preserved.

Production deployment: use the single-host deployment in tooling/deploy/single-host/, driving redamon.sh from a laptop over SSH, and wrapping it with internet-facing security layers such as nginx + TLS (Let's Encrypt), host firewall, SSH hardening, and fail2ban.

Development mode: supports Next.js fast refresh, automatically builds tool images on first run, and the development override replaces the production webapp image with a development container that mounts the source code volume, triggering instant browser hot reload every time a file is saved.

Knowledge base enablement: the knowledge base is opt-in. The default installation is a lightweight installation (about 4.4 GB lighter, Tavily web search only). Enabling the local knowledge base requires passing the --kbase flag. On the first installation with --kbase, RedAmon detects the hardware (GPU/CPU/API) and provides a quick-start configuration, and the choice is persisted. Embeddings can be offloaded to an external API via .env to speed up ingestion, for example using Ollama. Note: ingestion and querying must use the same model, and switching models requires rebuilding the index.

Use Cases

• Authorized penetration testing and red team exercises
• Security research and vulnerability validation
• Enterprise security assessment (officially described as "built for enterprises, secure by design")
• Bug bounty coverage audit (officially provides a 124-page PDF audit report, auditing line by line against all 397 web bug bounty finding categories and scoring the reconnaissance pipeline and the agent system separately: 134 categories completed, 210 categories in the build backlog, 44 categories intentionally excluded)

Limitations and Notes

• Authorized security testing, education, and research only; unauthorized use is strictly prohibited.
• Resource requirements: 7 containers run without OpenVAS (webapp, postgres, neo4j, agent, kali-sandbox, recon-orchestrator, docker-broker); including OpenVAS adds 4 runtime containers and about 8 one-off data initialization containers (about 170k+ NVT), the first startup of GVM source synchronization takes about 30 minutes. Dynamic reconnaissance and scanning containers are generated on demand and require additional resources.
• Disk: the fixed platform footprint is about 70 GB (excluding OpenVAS) or about 95 GB (including OpenVAS); for an always-on server running real tasks, an additional about 100 GB of free space is recommended for operational data (Neo4j attack graphs, scan artifacts/output, Postgres, container logs), i.e. 200 GB excluding OpenVAS and 250 GB including OpenVAS.
• The knowledge base is disabled by default. Once enabled, the first index build is about 1,200 chunks and takes 10-15 minutes on CPU; embedding large datasets on a CPU machine may take several hours.
• The official team has passed the Anthropic Cyber Verification Program.
• The project maintains a public Project Board and welcomes community contributions. See CONTRIBUTING.md for the contribution guidelines.
• See the Wiki for detailed documentation, the YouTube playlist for product demos, and the Troubleshooting guide for troubleshooting.