AI Summary: RedAmon is an autonomous AI framework designed for seamless cybersecurity operations that integrate reconnaissance, exploitation, and post-exploitation processes into a streamlined pipeline. It stands out by automatically triaging findings, applying code fixes, and generating pull requests in repositories, ensuring human oversight at critical junctures. Its notable features include support for over 38 security tools, integration with major vulnerability scanners, and configurable autonomy to adapt to various security assessment needs.

README

Unmask the hidden before the world does

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.

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

Three AI agents test in parallel — one validates credential policies via Hydra, one verifies a CVE exploit path through privilege escalation, one maps XSS vulnerabilities across the frontend.

Offense meets defense — one pipeline, full visibility.

Reconnaissance ➜ Exploitation ➜ Post-Exploitation ➜ AI Triage ➜ CodeFix Agent ➜ GitHub PR

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.

Roadmap & Community Contributions

We maintain a public Project Board with upcoming features open for community contributions. Pick a task and submit a PR!

Want to contribute? See CONTRIBUTING.md for how to get started.

Maintainers

Samuele Giampieri — Creator, Maintainer & AI Platform Architect 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. LinkedIn · GitHub · Devergo Labs

Ritesh Gohil — Maintainer & Lead Security Researcher 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. LinkedIn · GitHub

Quick Start

Prerequisites

• Docker & Docker Compose v2+

That’s it. No Node.js, Python, or security tools needed on your host.

Minimum System Requirements

Without OpenVAS runs 6 containers: webapp, postgres, neo4j, agent, kali-sandbox, recon-orchestrator. 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.

1. Clone & Install

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. When done, open http://localhost:3000.

2. 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). 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 wiki page for detailed setup instructions.

3. 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.

Having issues? See the Troubleshooting guide or the Wiki Troubleshooting page.

Management Commands

All lifecycle management is handled by a single script:

Updating to a New Version

Just run:

./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.

The webapp also checks for updates automatically and shows a notification in the UI when a new version is available.

Development Mode

For contributors and active development with Next.js fast refresh:

Build tool images:

docker compose --profile tools build

Start dev environment (without GVM):

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres neo4j recon-orchestrator kali-sandbox agent webapp

Start dev environment (with GVM):

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

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

Rebuild a single service:

docker compose build <service>                    # Rebuild one image
docker compose up -d --no-deps <service>          # Restart only that service

Common dev commands:

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

For a complete development reference – hot-reload rules, common commands, important rules, and AI-assisted coding guidelines – see the Developer Guide.

Table of Contents

• Full Wiki Documentation
• Overview
• Feature Highlights
• System Architecture
• Components
• Documentation
• Troubleshooting
• Community Showcase
• 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.

The platform is built around six pillars:

Feature Highlights

Reconnaissance Pipeline

A fully automated, parallelized scanning engine running inside a Kali Linux container. Given a root domain, subdomain list, or IP/CIDR ranges, it maps the complete external attack surface using a fan-out / fan-in pipeline architecture: subdomain discovery (crt.sh, HackerTarget, Subfinder, Amass, Knockpy — all 5 tools run concurrently), puredns wildcard filtering (validates subdomains against public DNS resolvers and removes wildcard/poisoned entries), parallel DNS resolution (20 workers), Shodan + port scanning (Masscan / Naabu — both run in parallel), passive threat intelligence enrichment (7 tools: Censys, FOFA, OTX, Netlas, VirusTotal, ZoomEye, CriminalIP — all run in parallel with port scanning) in parallel, Nmap service version detection and NSE vulnerability scripts on discovered ports, HTTP probing with technology fingerprinting (httpx + Wappalyzer), resource enumeration (Katana, Hakrawler, GAU, ParamSpider, Kiterunner — internally parallel, followed by jsluice JavaScript analysis, FFuf directory fuzzing with custom wordlist support, and Arjun hidden parameter discovery with multi-method parallel execution), and vulnerability scanning (Nuclei with 9,000+ templates + DAST fuzzing). Neo4j graph updates run in a dedicated background thread so the main pipeline is never blocked. Results are stored as JSON and imported into the Neo4j graph.

Wiki: Running Reconnaissance | Technical: README.RECON.md

_{*Amass can run in active mode when configured. Knockpy performs active DNS probing.}

GVM Vulnerability Scanner

GVM/OpenVAS performs deep network-level vulnerability assessment with 170,000+ NVTs — probing services at the protocol layer for misconfigurations, outdated software, default credentials, and known CVEs. Complements Nuclei’s web-layer findings. Seven pre-configured scan profiles from quick host discovery (~2 min) to exhaustive deep scanning (~8 hours). Findings are stored as Vulnerability nodes in Neo4j alongside the recon graph.

Wiki: GVM Vulnerability Scanning | Technical: README.GVM.md

AI Agent Orchestrator

A LangGraph-based autonomous agent implementing the ReAct pattern. It progresses through three phases — Informational (intelligence gathering, graph queries, Shodan, Google dorking), Exploitation (Metasploit, Hydra credential testing, social engineering simulation), and Post-Exploitation (enumeration, lateral movement). The agent executes 13 security tools via MCP servers inside a Kali sandbox, supports parallel tool execution via Wave Runner, and provides real-time chat interaction with guidance, stop/resume, and approval workflows. Deep Think mode enables structured strategic analysis before acting.

Wiki: AI Agent Guide | Technical: README.PENTEST_AGENT.md

AI Model Providers

Supports 5 providers and 400+ models: OpenAI (GPT-5.2, GPT-5, GPT-4.1), Anthropic (Claude Opus 4.6, Sonnet 4.5), OpenRouter (300+ models), AWS Bedrock, and any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, Groq, etc.). Models are dynamically fetched — no hardcoded lists.

Wiki: AI Model Providers

Attack Surface Graph

A Neo4j knowledge graph with 17 node types and 20+ relationship types — the single source of truth for the target’s attack surface. The agent queries it before every decision via natural language → Cypher translation.

Wiki: Attack Surface Graph | Technical: GRAPH.SCHEMA.md

EvoGraph — Attack Chain Evolution

A persistent, evolutionary graph tracking everything the AI agent does — tool executions, discoveries, failures, and strategic decisions. Structured chain context replaces flat execution traces, improving agent efficiency by 25%+. Cross-session memory means the agent never starts from zero.

Wiki: EvoGraph | Technical: README.PENTEST_AGENT.md

Multi-Session Parallel Attack Chains

Launch multiple concurrent agent sessions against the same project. Each session creates its own AttackChain in EvoGraph. New sessions automatically load findings and failure lessons from all prior sessions, avoiding redundant work.

Wiki: AI Agent Guide

Reverse Shells

Unified view of active sessions — meterpreter, reverse/bind shells, and listeners. Built-in terminal with a Command Whisperer that translates plain English into shell commands.

Wiki: Reverse Shells

RedAmon Terminal

Full interactive PTY shell access to the Kali sandbox container directly from the graph page via xterm.js. Access all pre-installed pentesting tools (Metasploit, Nmap, Nuclei, Hydra, sqlmap) without leaving the browser. Features dark terminal theme, connection status indicator, auto-reconnect with exponential backoff, fullscreen mode, and browser-side keepalive.

Wiki: The Graph Dashboard

CypherFix — Automated Vulnerability Remediation

Two-agent pipeline: a Triage Agent runs 9 hardcoded Cypher queries then uses an LLM to correlate, deduplicate, and prioritize findings. A CodeFix Agent clones the target repo, explores the codebase with 11 tools, implements fixes, and opens a GitHub PR — replicating Claude Code’s agentic design.

Wiki: CypherFix | Technical: README.CYPHERFIX_AGENTS.md

Agent Skills

An LLM-powered Intent Router classifies user requests into agent skills: CVE (MSF), SQL Injection, Credential Testing, Social Engineering, Availability Testing, or custom user-defined skills uploaded as Markdown files. Ready-to-use community skills are available for API testing, XSS, SQLi, and SSRF – download the .md file and upload it via Global Settings > Agent Skills to activate it for your user. You can also contribute your own by opening a PR.

Wiki: Agent Skills | Community Skills

GitHub Secret Hunter

Scans GitHub repositories, gists, and commit history for exposed secrets using 40+ regex patterns and Shannon entropy analysis.

Wiki: GitHub Secret Hunting

TruffleHog Deep Secret Scanner

Scans GitHub repositories for leaked credentials using 700+ detectors with automatic verification of whether discovered secrets are still active. Powered by the TruffleHog engine (trufflesecurity/trufflehog), it detects API keys, passwords, tokens, certificates, and more across full commit history. Results are stored as TrufflehogScan → TrufflehogRepository → TrufflehogFinding nodes in the Neo4j graph. Both GitHub Hunt and TruffleHog are accessible from the “Other Scans” modal in the graph toolbar.

Project Settings

196+ configurable parameters across 14 tabs controlling every tool’s behavior — from scan modules to agent approval gates. Managed through the webapp UI.

Wiki: Project Settings Reference

Rules of Engagement (RoE)

Upload a RoE document (PDF, TXT, MD, DOCX) to auto-configure project settings and enforce engagement constraints. Enforcement at both the recon pipeline (excluded hosts, rate limits, time windows) and AI agent (prompt injection, severity phase cap, tool restrictions) layers.

Wiki: Rules of Engagement

Insights Dashboard

30+ interactive charts across 4 sections — attack chains & exploits, attack surface, vulnerabilities & CVE intelligence, and graph overview. All data pulled live from Neo4j and PostgreSQL.

Wiki: Insights Dashboard

Target Guardrail

LLM-based guardrail preventing targeting of unauthorized domains — blocks government sites, major tech companies, financial institutions, and social media platforms. Operates at both project creation and agent initialization. Government, military, educational, and international organization domains (.gov, .mil, .edu, .int) are permanently blocked by a deterministic hard guardrail that cannot be disabled.

Wiki: Creating a Project

Tool Confirmation

Per-tool human-in-the-loop gate for dangerous operations. When enabled, the agent pauses before executing high-impact tools (Nmap, Nuclei, Metasploit, Hydra, Kali shell, code execution) and presents an inline Allow / Deny prompt in the chat timeline. Supports both single-tool and parallel-wave (plan) confirmation modes. Users can approve, reject, or modify tool arguments before execution proceeds. Disabled via the Require Tool Confirmation toggle in Project Settings.

Wiki: Pentest Agent — Tool Confirmation

Pentest Reports

Professional, client-ready HTML reports with 11 sections. When an AI model is configured, 6 sections receive LLM-generated narratives including executive summary, risk analysis, and prioritized remediation triage. View example report.

Wiki: Pentest Reports

Data Export & Import

Full project backup and restore through the web interface — settings, conversations, graph data, recon/GVM/GitHub hunt results as a portable ZIP archive.

Wiki: Data Export & Import

System Architecture

flowchart TB
    subgraph User["👤 User Layer"]
        Browser[Web Browser]
        CLI[Terminal/CLI]
    end

    subgraph Frontend["🖥️ Frontend Layer"]
        Webapp[Next.js Webapp<br/>:3000]
    end

    subgraph Backend["⚙️ Backend Layer"]
        Agent[AI Agent Orchestrator<br/>FastAPI + LangGraph<br/>:8090]
        ReconOrch[Recon Orchestrator<br/>FastAPI + Docker SDK<br/>:8010]
    end

    subgraph Tools["🔧 MCP Tools Layer"]
        NetworkRecon[Network Recon Server<br/>Curl + Naabu<br/>:8000]
        Nuclei[Nuclei Server<br/>:8002]
        Metasploit[Metasploit Server<br/>:8003]
        Nmap[Nmap Server<br/>:8004]
    end

    subgraph Scanning["🔍 Scanning Layer"]
        Recon[Recon Pipeline<br/>Docker Container]
        GVM[GVM/OpenVAS Scanner<br/>Network Vuln Assessment]
        GHHunt[GitHub Secret Hunter<br/>Credential Scanning]
        TruffleHog[TruffleHog Scanner<br/>700+ Secret Detectors]
    end

    subgraph Data["💾 Data Layer"]
        Neo4j[(Neo4j Graph DB<br/>:7474/:7687)]
        Postgres[(PostgreSQL<br/>Project Settings<br/>:5432)]
    end

    subgraph LLMProviders["🧠 LLM Providers"]
        OpenAI[OpenAI]
        Anthropic[Anthropic]
        LocalLLM[Local Models<br/>Ollama · vLLM · LM Studio]
        OpenRouter[OpenRouter<br/>300+ Models]
        Bedrock[AWS Bedrock]
    end

    subgraph External["🌐 External APIs"]
        GitHubAPI[GitHub API<br/>Repos & Code Search]
    end

    subgraph Targets["🎯 Target Layer"]
        Target[Target Systems]
        GuineaPigs[Guinea Pigs<br/>Test VMs]
    end

    Browser --> Webapp
    CLI --> Recon
    Webapp <-->|WebSocket| Agent
    Webapp -->|REST + SSE| ReconOrch
    Webapp --> Neo4j
    Webapp --> Postgres
    ReconOrch -->|Docker SDK| Recon
    ReconOrch -->|Docker SDK| GVM
    ReconOrch -->|Docker SDK| GHHunt
    ReconOrch -->|Docker SDK| TruffleHog
    Recon -->|Fetch Settings| Webapp
    GHHunt -->|GitHub API| GitHubAPI
    TruffleHog -->|GitHub API| GitHubAPI
    TruffleHog --> Neo4j
    Agent -->|API| OpenAI
    Agent -->|API| Anthropic
    Agent -->|API| LocalLLM
    Agent -->|API| OpenRouter
    Agent -->|API| Bedrock
    Agent --> Neo4j
    Agent -->|MCP Protocol| NetworkRecon
    Agent -->|MCP Protocol| Nuclei
    Agent -->|MCP Protocol| Metasploit
    Agent -->|MCP Protocol| Nmap
    Recon --> Neo4j
    GVM -->|Reads Recon Output| Recon
    GVM --> Neo4j
    GVM --> Target
    GVM --> GuineaPigs
    NetworkRecon --> Target
    Nuclei --> Target
    Metasploit --> Target
    Nmap --> Target
    NetworkRecon --> GuineaPigs
    Nuclei --> GuineaPigs
    Metasploit --> GuineaPigs
    Nmap --> GuineaPigs

Full architecture diagrams (data flow, Docker containers, recon pipeline, agent workflow, MCP integration): ARCHITECTURE.md

Technology stack (70+ technologies across frontend, backend, AI, databases, security tools): TECH_STACK.md

Components

Documentation

Troubleshooting

RedAmon is fully Dockerized and runs on any OS with Docker Compose v2+. For OS-specific fixes (Linux, Windows, macOS), see Troubleshooting Guide or the Wiki.

Community Showcase

Videos, writeups, and real-world experiences from security professionals using RedAmon in the field. Want to be featured? See the Content Creator track in CONTRIBUTING.md.

Videos

Real-World Case Studies

Community Guides

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to get started, code style conventions, and the pull request process.

Maintainers

Samuele Giampieri — creator, maintainer & AI platform architect · LinkedIn · GitHub · Devergo Labs

Ritesh Gohil — maintainer & lead security researcher · LinkedIn · GitHub

Contact

For questions, feedback, or collaboration inquiries: devergo.sam@gmail.com

Legal

This project is released under the MIT License.

RedAmon integrates several third-party tools under their own licenses (AGPL-3.0, GPL, BSD, and others). Source code for all AGPL-licensed components is available at their upstream repositories. See THIRD-PARTY-LICENSES.md for the complete list.

See DISCLAIMER.md for full terms of use, acceptable use policy, and legal compliance requirements.

Use responsibly. Test ethically. Defend better.