AGI is just a swarm away. A multi-agent penetration testing system that orchestrates 8 active security agents plus reporting, 67+ security tools with Python-native fallbacks, and an automated AI Agent repair loop spanning VS Code, Codex, Claude, and Antigravity.
For authorized security testing only.
- System Overview
- Architecture
- File Structure
- Installation
- Running the System
- Dashboard Usage
- Pentest-Fix Loop Flow
- AI Agent Repair Integration
- Agent Details
- Two-Tier Tool Execution
- Code Notation
- Function Map
- Source Provenance
- API Reference
- Troubleshooting
- Operator Guide (AI Agent Instructions)
- Hackathon Tracks
This system runs a pentest swarm — 9 specialist agents that each control a category of security tools. The swarm scans a target (domain, IP, or web app), produces real findings, dispatches those findings to the selected repair backend, verifies code changes happened, then re-scans to confirm fixes worked.
┌─────────────────────────────────────────────────────────┐
│ PENTEST-FIX LOOP │
│ │
│ 1. SCAN ──→ 2. FINDINGS ──→ 3. DISPATCH TO VS CODE │
│ ↑ │ │
│ │ ▼ │
│ 5. RE-SCAN ←── 4. COPILOT APPLIES FIXES │
│ │
│ Loop exits when: user stops manually or │
│ max iterations hit (if set). │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────┐
│ SWARM ORCHESTRATOR │
│ (5-phase execution) │
└────┬──┬──┬──┬──┬──┬─────┘
┌──────────────┘ │ │ │ │ └──────────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ RECON │ │ VULN │ │ EXPLOIT │ │ REPORT │
│ AGENT │ │ SCANNER │ │ AGENT │ │ AGENT │
├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤
│ nmap ▸◦ │ │ nuclei │ │ sqlmap ▸◦│ │ SARIF │
│ subfndr◦ │ │ nikto ◦ │ │ hydra │ │ JSON │
│ whatweb ◦│ │ sslyze ▸ │ │ │ │ markdown │
│ wafw00f▸ │ │ wapiti │ │ │ │ │
│ tavily ▸ │ │ │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ NETWORK │ │ WIRELESS │ │ SOCIAL │ │ FORENSIC │
│ AGENT │ │ AGENT │ │ ENGINEER │ │ AGENT │
├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤
│ tshark ◦ │ │ aircrack │ │ harvest◦ │ │ volatily │
│ hping3 │ │ kismet │ │ tavily ▸ │ │ │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
▸ = installed (CLI on PATH) ◦ = Python-native fallback
| Component | File | Purpose |
|---|---|---|
| Orchestrator | core/swarm_orchestrator.py |
Runs 9 agents in 5 phases, manages findings |
| Loop Controller | core/loop_controller.py |
Pentest → VS Code repair → retest cycle |
| VS Code Bridge | core/vscode_bridge.py |
Writes prompt files, opens VS Code |
| API Server | web/server.py |
FastAPI backend + REST endpoints |
| Dashboard | web/index.html |
React 18 cyberpunk UI (single-file) |
| CLI | main.py |
scan, loop, serve, doctor commands |
hackathon-swarm-2026/
├── main.py # CLI entry point
├── install.ps1 # Windows tool installer (PowerShell)
├── install.sh # Linux/macOS tool installer (bash)
├── requirements.txt # Python dependencies (includes security tools)
├── README.md # This file
│
├── core/
│ ├── swarm_orchestrator.py # 9 agents + Python-native scanning fallbacks
│ ├── loop_controller.py # Pentest → fix → retest loop
│ └── vscode_bridge.py # Dispatches findings to VS Code
│
├── web/
│ ├── server.py # FastAPI REST API (all endpoints)
│ └── index.html # React dashboard (single HTML file)
│
├── config/ # Configuration files
├── agents/ # Agent config (reserved)
├── tools/ # Tool wrappers (reserved)
├── reports/ # Generated reports
│
├── .copilot-fix-request.md # Auto-generated: repair prompt for Copilot
└── .pentest-findings.json # Auto-generated: machine-readable findings
The repo includes install scripts that fetch all tools automatically:
Windows (PowerShell):
powershell -ExecutionPolicy Bypass -File install.ps1Linux / macOS:
chmod +x install.sh && ./install.shThese scripts install:
- App-local Python runtime in
runtime/venvwith all pip dependencies - Bundled tool directory in
runtime/tools/bin - Nmap — port scanner (via winget / apt / brew)
- Wireshark (tshark) — packet capture (via winget / apt / brew)
- subfinder, nuclei, katana — ProjectDiscovery tools (downloaded from GitHub releases)
- pentagi — optional external recon orchestrator (source install, CLI on PATH)
- sqlmap, wapiti, sslyze, wafw00f, theHarvester, volatility3 — via pip
- Linux/macOS only: nikto, hydra, hping3, aircrack-ng via system package manager
After install, run runtime/venv/Scripts/python.exe main.py doctor to confirm tool status.
Build a standalone launcher exe that always creates a fresh loop workspace instance:
powershell -ExecutionPolicy Bypass -File build_exe.ps1Then run:
.\dist\swarm-runner.exe loop example.com --repo https://github.com/user/repoIf --workspace is omitted, the launcher generates a unique session directory under
~/pentest-repairs/instances/ every run.
- Python 3.10+ (tested on 3.13)
- pip package manager
- VS Code with GitHub Copilot extension (for auto-repair)
cd hackathon-swarm-2026
pip install -r requirements.txtThis installs the core framework AND security tools shipped with the repo:
sslyze— TLS/SSL analyzer (CLI binary)wafw00f— WAF detection (CLI binary)python-nmap— Nmap Python bindingsdnspython— DNS resolver for subdomain enumerationhttpx— HTTP client for web probingfastapi+uvicorn— Dashboard servertavily-python— OSINT search APIlangsmith— Agent tracingdaytona-sdk— Cloud sandbox provisioning
# Windows
winget install --id Insecure.Nmap
# Linux
sudo apt install nmap
# macOS
brew install nmappython main.py doctorExpected output shows 3 tiers:
- ✅ CLI binary on PATH (fastest, most comprehensive)
- 🐍 Python-native fallback (real scanning via socket/ssl/dns/httpx)
- ❌ Not available (agent skips this tool)
doctor also checks optional external tools such as pentagi and prints install hints if missing.
Pentagi is integrated as an optional recon tool. Packaging varies by environment,
so use the official repository and ensure the pentagi executable is on PATH.
Official repository:
https://github.com/vxcontrol/pentagi
Recommended install path:
- Follow Quick Start in the PentAGI repo (
Using Installersection) - Complete environment configuration (
.envand provider keys) - Re-run this project doctor command to confirm integration visibility
After installing, validate with:
python main.py doctorYou should see pentagi in the tool table as installed.
Set environment variables for enhanced capabilities:
# Tavily OSINT deep search
set TAVILY_API_KEY=tvly-xxxxx
# LangSmith agent tracing
set LANGCHAIN_API_KEY=ls-xxxxx
set LANGCHAIN_PROJECT=hackathon-swarm-2026
# Daytona cloud sandboxes
set DAYTONA_API_KEY=daytona-xxxxxWithout these keys, the corresponding features run in simulation mode but all scanning is still real.
python main.py serveStarts the dashboard on port 8000 by default. If 8000 is busy, the CLI automatically selects the next open port (for example 8001) and prints the exact URL.
Use the web UI to:
- Enter a target hostname/IP
- Click LAUNCH SWARM for a one-shot scan, or
- Click LAUNCH SWARM with Loop mode to start the pentest-fix cycle
Optional explicit port:
python main.py serve --port 8010python main.py scan example.comRuns all 9 agents and prints findings to terminal.
# With AUTO repair agent (default): Codex → Antigravity → Claude → VS Code
python main.py loop example.com --repo https://github.com/user/vulnerable-app --timeout 300
# With Codex CLI (fully autonomous)
python main.py loop example.com --repo https://github.com/user/vulnerable-app --agent codex
# With Claude Code CLI (fully autonomous)
python main.py loop example.com --repo ./local-repo --agent claude
# With explicit workspace directory
python main.py loop example.com --repo https://github.com/user/repo --workspace C:\repairs --agent codexCLI options:
--repo— Git repo URL or local path (cloned to workspace if URL)--workspace— Local directory for prompt files (default: unique run path in~/pentest-repairs/instances)--agent— Repair agent:auto(default),vscode,claude,codex,antigravity--timeout— Seconds to wait for repair per cycle (default: 600)--max-iterations— Limit cycles (default: 0 = unlimited)
The dashboard at http://localhost:8000 provides:
- Target: hostname or IP to scan (e.g.,
purpleindustries.us) - Scope: comma-separated additional domains
- Git Repo / Target Codebase Path: local path or git URL of the target's source code. IMPORTANT: Setting this enables the full repair-and-retest cycle. Without it, the loop dispatches findings and completes.
- VS Code Workspace Path: where repair files are written (default: per-run unique instance path)
Color-coded badges: CRITICAL (red), HIGH (orange), MEDIUM (yellow), LOW (cyan), INFO (gray)
9 agent cards showing real-time progress:
- Recon Agent, Vuln Scanner, AI Security, Exploit Agent, Network Agent
- Wireless Agent, Social Engineer, Forensic Agent, Report Agent
Live feed of discoveries as agents complete. Each finding shows:
- Severity badge
- Agent name and tool used
- Finding title
- Remediation guidance
- Open VS Code & Auto-Fix Issues: Dispatches findings to VS Code
- Copy to Clipboard: Copies the repair prompt for manual paste into Copilot Chat
This is the automated cycle that scans, fixes, and re-scans:
┌─────────────┐
│ CLICK LAUNCH│
│ SWARM │
└──────┬──────┘
▼
┌───────────────────────┐
│ POST /api/loop/start │
└───────────┬───────────┘
▼
┌────────────────────────────────────────────────────────┐
│ ITERATION N │
│ │
│ 1. State: PENTESTING │
│ SwarmOrchestrator.execute() runs all 9 agents │
│ Real tools + Python fallbacks scan the target │
│ Dashboard shows live progress via GET /api/status │
│ │
│ 2. State: DISPATCHING │
│ Findings written to: │
│ <workspace>/.copilot-fix-request.md │
│ <workspace>/.pentest-findings.json │
│ <workspace>/.github/copilot-instructions.md │
│ <workspace>/.repair-dispatch.json │
│ VS Code opened with workspace + prompt file │
│ │
│ 3. State: DISPATCHING │
│ Findings dispatched to selected repair agent: │
│ - Auto mode: Codex → Claude → VS Code │
│ - VS Code + Copilot │
│ - Claude Code CLI (autonomous, --full-auto) │
│ - Codex CLI (autonomous, --full-auto) │
│ If VS Code mode times out, loop auto-falls back │
│ to autonomous agents (Codex/Antigravity/Claude). │
│ │
│ 4. State: WAITING_FOR_REPAIR │
│ Loop polls for <workspace>/.repair-complete │
│ User/Copilot fixes code, then signals completion: │
│ - Click "REPAIR COMPLETE" in dashboard, OR │
│ - POST /api/loop/repair-done, OR │
│ - Create the .repair-complete marker file │
│ After repair, loop logs verification of changed │
│ files/git status so repairs are auditable. │
│ │
│ 5. State: VERIFYING │
│ Re-runs the pentest to check if fixes worked │
│ → Back to step 1 with iteration N+1 │
│ │
└────────────────────────────────────────────────────────┘
- ⏱️ Max iterations reached (only if set > 0; default is unlimited)
- 🛑 User clicks STOP LOOP or POST /api/loop/stop
-
The loop writes
.copilot-fix-request.md— a structured markdown prompt containing:- All findings organized by severity (CRITICAL → HIGH → MEDIUM → LOW)
- Evidence from real tool output
- Specific remediation instructions per finding
- CVE/CWE and MITRE ATT&CK references
- Previous fix iteration history
-
The loop writes
.pentest-findings.json— raw machine-readable findings -
The loop writes
.github/copilot-instructions.md— auto-context for Copilot -
The loop writes
.repair-dispatch.json— auditable handoff receipt for this iteration -
The selected repair agent opens or consumes the workspace prompt file
vscodeopens the workspace for GitHub Copilot or a human operator.codexlaunches Codex CLI for autonomous repair when available.claudelaunches Claude Code CLI for autonomous repair when available.antigravitylaunches Antigravity CLI for autonomous repair when available.autoprefers autonomous CLIs first and falls back to VS Code when needed.
- Read
.copilot-fix-request.mdin the opened workspace - For each CRITICAL and HIGH finding: identify affected files and apply the recommended fix
- For MEDIUM findings: apply configuration hardening
- Save all files when done
- Signal completion via one of:
- Click "REPAIR COMPLETE — RE-SCAN" button in the dashboard
POST http://localhost:8000/api/loop/repair-done- Create the file
<workspace>/.repair-complete
<workspace>/
├── .copilot-fix-request.md # ← READ THIS: full repair instructions
├── .pentest-findings.json # Machine-readable findings (JSON)
├── .repair-dispatch.json # Dispatch receipt + marker path
├── .github/
│ └── copilot-instructions.md # Auto-context for Copilot
├── .repair-complete # CREATE THIS to signal done
└── [cloned repo files if git_repo was set]
ReconAgent — Maps the target's attack surface
- Port scanning (nmap → Python socket fallback)
- Subdomain enumeration (subfinder → dnspython fallback)
- Optional external recon integration check (pentagi CLI)
- Web fingerprinting (whatweb → httpx fallback)
- WAF detection (wafw00f, installed via pip)
- OSINT search (Tavily API)
- URL crawling (katana)
VulnScannerAgent — Finds known vulnerabilities
- CVE scanning (nuclei)
- Web server audit (nikto → Python header audit fallback)
- TLS/SSL analysis (sslyze, installed via pip → Python ssl fallback)
- Web app scanning (wapiti)
NetworkAgent — Tests network-level security
- Packet capture (tshark → HTTP/HTTPS probe fallback)
- Packet crafting (hping3; on Windows,
npingis accepted)
AISecurityAgent — AI/LLM endpoint and prompt-injection checks
- Loads Mr-Infect AI pentest resource index
- Discovers likely AI/LLM API endpoints
- Runs bounded OWASP-aligned prompt probes
- Emits leak/override findings for repair loop triage
WirelessAgent — WiFi security audit
- Aircrack-ng suite (requires wireless adapter)
- Kismet network detection
SocialEngineerAgent — OSINT about people
- Email harvesting (theHarvester → DNS MX/TXT fallback)
- Deep web search (Tavily API)
ExploitAgent — Confirms vulnerabilities are real
- SQL injection (sqlmap → Python SQLi error probe fallback)
- Credential brute-force (hydra)
- Cloud sandbox isolation (Daytona)
ForensicAgent — Memory and artifact analysis
- Volatility framework (requires memory dump)
ReportAgent — Generates reports from findings
Every agent uses a two-tier strategy:
| Tier | Method | Source |
|---|---|---|
| Tier 1 | CLI binary on PATH | shutil.which() → asyncio.subprocess |
| Tier 2 | Python-native scan | socket, ssl, dns.resolver, httpx |
| Missing CLI | Python Fallback | Real Data? |
|---|---|---|
nmap |
_python_port_scan() — TCP connect scan, 25 ports |
✅ Yes |
subfinder |
_python_dns_enum() — DNS brute-force, 37 subdomains |
✅ Yes |
pentagi |
Optional external CLI integration (no Python fallback) | ✅ Yes (when installed) |
whatweb |
_python_http_fingerprint() — HTTP headers |
✅ Yes |
nikto |
_python_header_audit() — HSTS/CSP/etc checks |
✅ Yes |
sslyze |
_python_ssl_check() — TLS cert + protocol |
✅ Yes |
sqlmap |
_python_sqli_probe() — SQL error detection |
✅ Yes |
tshark |
HTTP/HTTPS cleartext probe | ✅ Yes |
theHarvester |
DNS MX/TXT record lookup | ✅ Yes |
No simulated data anywhere. Every finding comes from a real network probe.
This project uses a strict notation/documentation standard:
- Each module starts with a high-level purpose block.
- Public classes and functions include docstrings with behavior and expected inputs.
- Non-obvious logic paths include concise inline comments.
- New integrations (for example Pentagi support) must include rationale comments and operator-facing docs.
When contributing, preserve this style so diagnostics and repair automation remain understandable.
This inventory covers the first-party swarm engine in the repository root. Bundled or report-local projects under reports/ are documented at the module level only and are not expanded here function-by-function.
| Symbol | Purpose |
|---|---|
_parse_scope |
Converts a comma-separated scope string into a non-empty scope list. |
_app_root |
Resolves the application root for source and bundled executable runs. |
_prepend_runtime_paths |
Prepends app-local runtime tool directories onto PATH. |
_default_loop_workspace |
Builds a unique per-run repair workspace path from the target and current UTC time. |
_find_available_port |
Finds the first bindable TCP port from a preferred starting point. |
_resolve_binary |
Resolves a binary using a preferred alias order. |
cmd_scan |
Runs a one-shot swarm scan and prints a findings summary. |
cmd_loop |
Starts the continuous pentest-fix-retest loop with the selected repair agent. |
cmd_serve |
Starts the FastAPI dashboard server and falls back to a nearby open port. |
cmd_doctor |
Reports installed tools, Python fallbacks, missing capabilities, and AI security resource references. |
main |
Parses CLI arguments and dispatches to scan, loop, serve, or doctor. |
| Symbol | Purpose |
|---|---|
Phase |
Defines the campaign lifecycle phases from initialization through completion or emergency stop. |
Severity |
Defines the finding severity levels used across the platform. |
Finding |
Stores one security finding with evidence, remediation, and metadata. |
ToolActivity |
Tracks lifecycle state and captured output for one tool invocation. |
Campaign |
Holds findings, logs, agent status, tool activity, and JSON-safe serialization for one run. |
LangSmithTracer |
Emits optional start/end traces to LangSmith when configured. |
tavily_search |
Executes Tavily OSINT lookups and returns real results or an empty list. |
daytona_create_sandbox |
Requests a Daytona sandbox for isolated exploit testing. |
_python_port_scan |
Performs a real TCP connect scan as the Python fallback for port discovery. |
_python_dns_enum |
Enumerates common subdomains through dnspython. |
_python_http_fingerprint |
Probes HTTP or HTTPS and extracts headers, cookies, and technology hints. |
_python_ssl_check |
Runs lightweight TLS certificate and protocol checks with Python ssl. |
_python_header_audit |
Audits HTTP security headers and returns finding-ready records. |
_tool_binary_candidates |
Expands a logical tool label into executable name candidates. |
_resolve_tool_binary |
Resolves the installed path and alias for a tool label. |
_tool_has_python_fallback |
Reports whether a missing CLI tool has a Python-native fallback. |
_normalize_target_bases |
Normalizes a target into probe-ready HTTP base URLs. |
_extract_llm_text |
Pulls readable model output from common API response shapes. |
_detect_secret_leakage |
Detects high-signal secret formats in model output. |
_detect_prompt_injection_signals |
Detects likely prompt-injection or instruction-bypass signals in model responses. |
BaseAgent |
Shared runtime for specialist agents that executes tools, records activity, and adds findings. |
ReconAgent |
Runs recon tools and fallbacks to discover ports, subdomains, WAFs, fingerprints, and OSINT. |
AISecurityAgent |
Probes likely AI endpoints and runs bounded prompt-injection and leakage checks. |
VulnScannerAgent |
Runs CVE and misconfiguration scanners plus HTTP and TLS fallbacks. |
ExploitAgent |
Attempts bounded exploitation confirmation, especially SQLi and credential brute force. |
NetworkAgent |
Checks network-level exposure such as cleartext HTTP and packet-probe visibility. |
WirelessAgent |
Runs wireless auditing tools when compatible hardware and CLIs are present. |
SocialEngineerAgent |
Collects social-engineering-relevant OSINT and mail infrastructure signals. |
ForensicAgent |
Runs Volatility-driven memory forensics when forensic tooling is available. |
ReportAgent |
Converts campaign findings into a markdown penetration-test report. |
SwarmOrchestrator |
Coordinates all phases, instantiates agents, logs tool availability, and returns the completed campaign. |
| Symbol | Purpose |
|---|---|
LoopState |
Defines the loop state machine values exposed to the dashboard. |
PentestFixLoop |
Repeats pentest, repair dispatch, wait, verification, and re-scan cycles until stopped or capped. |
PentestFixLoop.start |
Runs the end-to-end loop and returns a summary of iterations and findings reduction. |
PentestFixLoop.stop |
Requests a graceful stop and unblocks repair waits. |
PentestFixLoop.get_status |
Returns current loop state, iteration, and summary counters for the API. |
PentestFixLoop.signal_repair_complete |
Signals that the current repair phase is complete so the next scan can begin. |
| Symbol | Purpose |
|---|---|
find_vscode_cli |
Locates the VS Code command-line binary on the host system. |
_is_remote_git_source |
Detects whether a repository source string is a remote Git URL. |
_is_local_git_repo |
Detects whether a path is a local Git checkout. |
_repo_folder_name |
Derives a filesystem-safe folder name from a repo URL or path. |
_clone_repo |
Clones a repository or optionally pulls an existing checkout. |
_resolve_workspace |
Resolves the repair workspace and clones the target repo when needed. |
build_vscode_repair_prompt |
Builds the markdown repair prompt from findings, logs, and iteration history. |
dispatch_to_vscode |
Writes repair artifacts, creates Copilot context files, and opens VS Code on the workspace. |
generate_clipboard_payload |
Returns the repair prompt as plain text for manual paste. |
_write_prompt_files |
Writes the markdown prompt and JSON findings files into the workspace. |
_start_process_monitor |
Watches spawned repair processes and signals completion when they exit. |
dispatch_to_claude |
Launches Claude Code CLI for autonomous repair. |
dispatch_to_codex |
Launches Codex CLI, with npx fallback, for autonomous repair. |
dispatch_to_antigravity |
Launches Antigravity CLI for autonomous repair. |
| Symbol | Purpose |
|---|---|
StartCampaignRequest |
Request schema for launching one-shot campaigns. |
StartLoopRequest |
Request schema for launching the pentest-fix loop. |
DispatchRequest |
Request schema for immediate VS Code dispatch. |
start_campaign |
Starts a one-shot pentest campaign in the background. |
stop_campaign |
Requests a graceful stop for the active one-shot campaign. |
campaign_status |
Returns the best available live or completed campaign state. |
start_loop |
Starts the automated pentest-fix-retest loop and attaches status logging. |
stop_loop |
Requests a graceful stop for the active loop. |
loop_status |
Returns current loop state, iteration, and recent loop logs. |
signal_repair_done |
Marks the current repair phase as complete so the loop can continue. |
vscode_dispatch |
Pushes the current findings set to the VS Code repair bridge immediately. |
vscode_payload |
Returns the generated repair prompt for manual clipboard use. |
get_tools |
Returns static dashboard metadata for supported tools. |
get_agents |
Returns static dashboard metadata for supported agents. |
get_config |
Returns integration, loop, and VS Code availability state. |
root |
Serves the dashboard HTML. |
startup |
Logs server startup and integration status on boot. |
For an AI-operator view of the same inventory plus repo-handling rules, see AGENTS.md.
The first-party swarm engine explicitly references or adapts the following external sources:
https://github.com/Mr-Infect/AI-penetration-testing— source repository for the AI/LLM pentest resource index used byAISecurityAgentandcmd_doctor; seeREADME.Mr-Infect-AI-penetration-testing.mdfor the dedicated integration note.https://github.com/vxcontrol/pentagi— canonical external repository for the optional PentAGI recon integration.- The AI resource index currently cites:
https://llm-attacks.org,https://github.com/jthack/PIPE,https://atlas.mitre.org/,https://github.com/cckuailong/awesome-gpt-security,https://github.com/NetsecExplained/chatgpt-your-red-team-ally,https://gandalf.lakera.ai,https://prompting.ai.immersivelabs.com/,https://github.com/dhammon/ai-goat,https://github.com/elder-plinius/L1B3RT45, andhttps://prompttrace.airedlab.com/.
Operational scope note:
- The function inventory above documents the repository-root swarm engine (
main.py,core/,web/). - Bundled report fixtures and third-party snapshots under
reports/should be treated as auxiliary artifacts unless you are intentionally working inside those subprojects.
| Method | Path | Description |
|---|---|---|
POST |
/api/campaign/start |
Start one-shot pentest. Body: {"target":"example.com","scope":["example.com"]} |
POST |
/api/campaign/stop |
Emergency stop running campaign |
GET |
/api/status |
Live campaign status + findings + agent states |
| Method | Path | Description |
|---|---|---|
POST |
/api/loop/start |
Start pentest-fix loop. Body: {"target":"example.com","git_repo":"/path/to/repo","auto_dispatch":true,"repair_agent":"auto"} |
POST |
/api/loop/stop |
Stop loop after current phase |
GET |
/api/loop/status |
Loop state, iteration, logs |
POST |
/api/loop/repair-done |
Signal that VS Code repair is complete |
| Method | Path | Description |
|---|---|---|
POST |
/api/vscode/dispatch |
Send findings to VS Code now |
GET |
/api/vscode/payload |
Get clipboard payload for manual paste |
| Method | Path | Description |
|---|---|---|
GET |
/api/tools |
Full tool registry (67+ tools) |
GET |
/api/agents |
Agent metadata (9 agents) |
GET |
/api/config |
Integration status (API keys, VS Code) |
- Run
python main.py doctor— check if tools have ✅ or 🐍 status doctornow resolves tool aliases (for examplevol/volatility3,theHarvester/theharvester) and prints install hints for tools without fallbacks- If all tools show ❌:
pip install sslyze wafw00f python-nmap dnspython - Ensure the target is reachable:
ping target.com
- Install Pentagi from
https://github.com/vxcontrol/pentagi - Ensure
pentagiis executable from your shell (pentagi --version) - Re-run
python main.py doctorand verify it appears as installed
The loop is waiting for repair completion and supports explicit failover:
- Apply fixes to the code in VS Code
- Click "REPAIR COMPLETE — RE-SCAN" in the dashboard, OR
POST http://localhost:8000/api/loop/repair-done- In
--agent vscodemode, if no completion arrives in the grace window, the loop can auto-fallback to autonomous repair CLIs
The VS Code dispatch opens the workspace and prompt directly and writes .repair-dispatch.json for audit.
For fully autonomous repair, prefer --agent auto (or explicitly use codex / claude / antigravity).
If Copilot does not proceed automatically, alternatives:
- Use
--agent auto,--agent codex,--agent claude, or--agent antigravity - Open
.copilot-fix-request.mdin the editor and paste into Copilot Chat manually - Or use the "Copy to Clipboard" button in the dashboard
- Ensure server is running:
python main.py serve - Confirm the URL from CLI output (it may be
http://localhost:8001or another open port if 8000 was occupied) - Dashboard polls
/api/statusevery 2 seconds - Check browser console for errors
- Refresh PATH if nmap was just installed: restart the terminal
pip install -r requirements.txtThis section is written for AI agents (OpenAI Operator, browser agents, etc.) that need to operate this system end-to-end.
-
Start the server (if not running):
- Open a terminal
- Navigate to the project directory
- Run:
python main.py serve - Verify:
http://localhost:8000loads the dashboard
-
Configure the target:
- In the dashboard, find "TARGET CONFIGURATION"
- Enter the target domain in the "Target" field (e.g.,
purpleindustries.us) - Optionally enter additional scope domains
- Optionally set "Git Repo / Target Codebase Path" to a local repo path or git URL
-
Launch the scan:
- Click the "🚀 LAUNCH SWARM" button
- The dashboard will show agents progressing through 5 phases
- Watch the "LATEST FINDINGS" section for real-time results
- Watch severity counters update: CRITICAL (red), HIGH (orange), etc.
-
Wait for completion:
- All 8 agent cards will show "Done" with finding counts
- Phase will show "completed"
- If loop mode: state shows "completed" or "waiting_for_repair"
-
Review findings:
- Scroll to "LATEST FINDINGS" section
- Each finding shows: severity, agent, tool, title, evidence
- Critical and High findings need immediate attention
-
Apply fixes (if git repo was set):
- VS Code will auto-open with
~/pentest-repairs/.copilot-fix-request.md - Read the file — it contains all findings and fix instructions
- Apply fixes to the codebase
- Click "REPAIR COMPLETE — RE-SCAN" in the dashboard
- The swarm will re-scan to verify fixes
- VS Code will auto-open with
-
Export results:
- Click "Copy to Clipboard" to get a formatted report
- Raw data is at
/api/status(JSON) - Findings JSON:
~/pentest-repairs/.pentest-findings.json
When the loop dispatches findings to VS Code:
- Open VS Code — it should already be open at
~/pentest-repairs/ - Open file
.copilot-fix-request.mdif not already visible - Read the MISSION section — it lists all vulnerabilities
- For each finding:
- Find the "Recommended Fix" field
- Navigate to the affected file in the codebase
- Apply the fix
- Save the file
- Signal completion:
- Go back to the dashboard at
http://localhost:8000 - Click the green "REPAIR COMPLETE — RE-SCAN" button
- OR run in terminal:
curl -X POST http://localhost:8000/api/loop/repair-done
- Go back to the dashboard at
- Observe re-scan: The swarm will run again to verify fixes
| Finding | Severity | Fix |
|---|---|---|
| Open ports detected | MEDIUM | Close unused ports in firewall config |
| Database port exposed | HIGH | Block port in firewall, use SSH tunnel |
| Missing HSTS header | MEDIUM | Add Strict-Transport-Security header to web server config |
| Missing CSP header | MEDIUM | Add Content-Security-Policy header |
| Missing X-Frame-Options | MEDIUM | Add X-Frame-Options: DENY header |
| Server version disclosed | LOW | Remove Server header or set to generic value |
| TLS 1.0/1.1 enabled | HIGH | Disable in web server SSL config, require TLS 1.2+ |
| HTTP serves content (no redirect) | MEDIUM | Configure HTTP→HTTPS redirect |
| SQL injection detected | CRITICAL | Use parameterized queries in code |
| No WAF detected | MEDIUM | Deploy WAF (Cloudflare, AWS WAF) |
- Tavily — Deep OSINT web search integration for reconnaissance
- Daytona — Cloud development environment for safe exploit testing
- NVIDIA — Nemotron model for vulnerability classification
For authorized security testing only. Only scan targets you own or have explicit written permission to test. Unauthorized scanning is illegal under the Computer Fraud and Abuse Act (CFAA) and similar laws worldwide.
© 2026 Purple Industries · Hackathon Swarm 2026 · Agenthon 001 · Apache 2.0