Docs

These docs are the fastest path into this codebase for new contributors. The root README.md is the product and usage guide; this folder is the engineering guide.

Start Here

• Getting Started: setup, common commands, and local development loop.
• Architecture: system shape, entry points, persistence, and major flows.
• Runtime Flows: how recon, task execution, exploitation, swarm, and MCP flows move through the code.
• Module Guide: responsibilities of the top-level modules, tools/, and tests.
• Extension Guide: exact edit points for adding tools, integrations, config, persistent data, and tests.
• Safety Model: scope checks, risk checks, permission modes, audit records, and secure development rules.
• Testing Guide: test layout, focused test commands, and what to update with each kind of change.
• Plugin Development: how to write, package, enable, and distribute out-of-tree plugins.
• Runtime Skills: advisory skill pipeline, selection, re-selection, feedback, and semantic matching.
• Building & Improving Skills: how to author new SKILL.md files and tune selection/feedback for existing ones.
• WebUI API: v1 REST + WebSocket reference for the --demon/--daemon API (runs, decisions, events, tools, config, secrets).
• WebUI: the bundled React/Vite SPA — stack, pages, auth, real-time transport, and extension points.

Deep Dives

• Exploit Agent: the Flow A agent — loop lifecycle, prompts, model routing, permission model, outcome pipeline, reflection, research assistant.
• MCP Tools: every tool family across the three MCP servers, the @audit_tool/@require_allowlist wiring, and the target-IP allowlist lock.
• MCP Wiring: servers, transports, ports, how the agent/swarm connect, env-var propagation, and exception-group handling.
• Swarm: multi-agent missions — orchestrator, blackboard, the six agent roles, phase flow, MCP bridge, observability.
• Attack Modules: the module registry, all 15 module families (~90 modules), applicability scoring, and the add-a-module checklist.
• Run Service: run lifecycle, providers, event/decision brokers, persistence, auth, and WebSocket transport.
• Model Providers: Ollama wiring for chat/generate, embeddings, and research — and how to add a new provider.
• Config Reference: every config.yaml key — type, default, consumer file:line, env overrides.
• CLI Reference: every entry point and flag across main.py / app.py / cli.py, WebUI daemon default, --menu terminal menu, exit codes, example workflows.
• Database & Mission: SQLite schema (both DBs), mission lifecycle, task queue, memory, target graph, evidence-to-report pipeline.
• Outcomes & Evidence: outcome taxonomy, truth-vs-claim, evidence model, audit JSONL, finding verification, PoE, report generation.
• Research: research assistant, web research, recon enrichers, CVE lookup, and how findings flow into the agent.
• Evaluation: eval harness vs oracle-backed benchmark, metrics, scenarios, detection coverage, PoE canary scoring.
• Deployment: Windows/Linux install, Ollama cloud vs local, nmap privileges, WebUI build, daemon mode, hardening checklist.
• Troubleshooting: symptom → cause → check → fix for setup, startup, runtime, tests, WebUI, and platform issues.
• Tutorial: hands-on walkthrough — setup, --self-test, recon-first run, exploit session, swarm mission, WebUI, demo/eval.
• Glossary: alphabetized domain vocabulary with file:line pointers.
• Prompts: inventory of every AI prompt in the codebase and where to edit them.
• Sandbox: disposable Docker worker — architecture, network containment, fail-closed posture.
• Benchmarks: reproducible benchmark suite, oracles, regression gates (--benchmark flags).
• Provider Development: adding a 4th AI provider (adapter + registry + config + tests).
• Browser Agent: sandboxed Playwright agent (off by default, target-locked).
• Configuration: generated config/API reference · MCP: servers, registration, families · Components: subsystem deep-dives · Reference: generated CLI dump.

Mental Model

This project is a locally run, AI-assisted security research agent. It has several surfaces over the same core concepts:

• main.py: interactive launcher and direct recon/attack entry point.
• cli.py: database-backed workflow commands for missions, scope, tasks, findings, and reports.
• mcp_server.py: defensive, scope-enforced MCP scan server.
• mcp_exploit_server.py: permissive exploit MCP server whose tool use is expected to be gated by policy in tools.exploit_agent.

The shared domain model is:

Mission -> Scope/Risk gates -> Planner -> TaskQueue -> Executor/Tools -> Observer -> OutcomeJudge/Hypothesis state -> Memory/Graph/Evidence -> FindingVerifier -> ReportGenerator

Extension Paths

• In-tree edits: see extension-guide.md for exact edit points for adding tools, integrations, config, persistent data, and tests.
• Out-of-tree plugins: see plugin-development.md for writing, packaging, enabling, and distributing plugins.

Generated Directories

The repository contains runtime artifacts from previous local runs. Contributors should understand them, but normally should not edit them:

• reports/: generated reports, run logs, and copied exploit workspaces.
• exploit_workspace/: generated exploit scripts, command logs, plans, and loot workspace.
• research_workspace/: local research database/logs.
• test_workspace*: temporary workspaces used by tests and manual regression runs.
• __pycache__/, .pytest_cache/, .venv/: local Python artifacts.