Skip to content

About

Autonomous Offensive Security Agent for Red Team Operations

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

747 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BreachPilot

Open-source autonomous security-testing operator for authorized environments. Plans, executes, verifies, and reports full assessment lifecycles with evidence — target-locked, sandboxed, and audited.

CI Go Rust License

Quick start · Documentation · Architecture · Safety model · Reliability metrics · Live demo

Warning

Authorized testing only. Only test systems you own or have explicit written permission to assess. Run the operator from an isolated, throwaway machine or VM.

What is BreachPilot?

BreachPilot is an agentic penetration-testing operator. Given an authorized target, it runs the full loop — reconnaissance, exploitation, privilege escalation, lateral movement, verification, and reporting — through a WebUI mission-control interface or a scriptable CLI.

It is built for lab and sanctioned-assessment use on a 100% native Go control plane + Rust execution plane with a React/TypeScript WebUI (zero Python dependencies): every action executes inside defined authorization boundaries, every finding requires stored-probe evidence, and every step lands in a tamper-evident audit trail.

Linux is the primary platform (full tool arsenal + Docker netns containment). Windows is natively supported via bp.exe and bp-sidecar.exe.

Why BreachPilot?

Auditable, evidence-driven autonomous security testing — scope → containment → verification → provenance → operator graph. See positioning and reliability metrics (baseline in progress — methodology here).

  • Full lifecycle, not just scanning. Recon → exploit → post-exploitation → verified findings → MITRE-mapped reports, in one run.
  • Evidence decides, not agent claims. Findings are independently re-proven with stored probes (VERIFIED / HOLDING / INCONCLUSIVE). Execution success and evidential success are tracked separately.
  • Contained by default. Target allowlist plus mission scope gate plus disposable Docker worker with default-DROP network containment. Fail-closed: sandbox failures block execution, never fall back silently.
  • Multi-agent when it helps. A six-specialist swarm for single high-value targets, and a persistent campaign orchestrator for multi-target, multi-phase operations.
  • Extensible without forking. Auto-discovered MCP tools, advisory skills, attack modules, and a plugin system with a reference example. Inventory counts live in the generated appendix (docs/generated/capability-counts.json), never the headline.

Quick-start

Requires Go 1.24+, Rust (cargo), Node.js 22+ (for WebUI build), Docker Engine, and nmap. bp --doctor verifies everything, including the active AI provider and Rust sidecar.

Linux (primary)

From a checkout (recommended — always works):

git clone https://github.com/braydos-h/BreachPilot.git
cd BreachPilot
./install.sh
bp --doctor
bp   # opens the WebUI at http://127.0.0.1:8765

Pinned to the published tag (reproducible, no history needed):

curl -fsSL https://github.com/braydos-h/BreachPilot/archive/refs/tags/v0.49.2.tar.gz -o breachpilot-v0.49.2.tar.gz
tar -xzf breachpilot-v0.49.2.tar.gz
cd BreachPilot-0.49.2
./install.sh
bp --doctor
bp   # opens the WebUI at http://127.0.0.1:8765

No versioned installer assets are published yet — the only GitHub release is the asset-less beta / v0.49.2 prerelease, so there is nothing for scripts/verify-installer.sh to check today and releases/download/… URLs 404. The release workflow freezes a pinned installer per tag on publish; from the first asset-bearing release on, the quick-start returns to install-<version>.sh + .sha256, verified before executing. The release-truth CI job curls every URL in this section so a 404 can never ship again.

After an update (git pull), refresh the built interface with bp --rebuild (combine with bp --web to rebuild before serving).

Dev path (mutable main, dev-only with warning):

curl -fsSL https://raw.githubusercontent.com/braydos-h/BreachPilot/main/install.sh | bash  # dev-only

From an existing checkout: ./install.sh, or make install && make doctor && make run. Full options: docs/deployment.md.

Windows (secondary)

Windows builds and runs native bp.exe and bp-sidecar.exe via .\install.ps1 / install.bat. Docker Desktop with WSL2 is recommended so the default-on sandbox works.

git clone https://github.com/braydos-h/BreachPilot.git
cd BreachPilot
powershell -ExecutionPolicy Bypass -File .\install.ps1

Save-and-inspect applies here too: download install.ps1, review it, then execute. Never irm ... | iex. See docs/deployment.md.

First authorized run

Start with the safe built-in smoke test — localhost only, no target to invent:

bp --self-test   # safe localhost check against 127.0.0.1

Then run against your own lab target (example uses a placeholder address — substitute a host you own or are contracted to test):

bp --target 10.0.0.50 --mode recon                 # read-only recon first
bp --target 10.0.0.50 --mode attack                # full assessment
bp --target 10.0.0.50 --mode attack --swarm        # swarm decomposition

For reproducible evaluation, the repo ships oracle-graded targets (eval_targets/: DVWA, Juice Shop, Metasploitable 2, and others) with bp --eval and sandboxed bp --benchmark suites. See docs/evaluation.md and docs/benchmarks.md.

Artifacts land in reports/<run_id>/ and exploit_workspace/<target>/.

How it works

flowchart TD
    OP[Operator: WebUI / CLI] --> RUN[Run Service]
    RUN --> AGENT[Exploit Agent: plan + execute + verify]
    AGENT --> MCP[MCP Tool Layer: allowlist + audit gates]
    AGENT --> SWARM[Swarm: 6 specialists]
    AGENT --> CAMP[Campaign: multi-phase queue]
    MCP --> SB[Disposable Docker worker]
    AGENT --> REP[Reports + findings + attack graph]
Loading

The WebUI/CLI submits runs to the run service, which drives the exploit agent. The agent calls gated MCP tools (recon, attack modules, Metasploit, web scanners, credentials, browser), optionally fanning out to the swarm or campaign orchestrators. Attack commands execute inside a per-run disposable container; results return as evidence-linked findings and reports.

Details: docs/architecture.md, docs/runtime-flows.md.

Core capabilities

Reconnaissance

Parallel TCP discovery, service fingerprinting, OS detection, and vulnerability enrichment (NVD + EPSS + CISA KEV + OSV + GHSA). Domain-aware: subdomain enumeration, DNS recon (AXFR/DNSSEC), vhost discovery, takeover flags. Nmap privilege fallback keeps firewalled hosts from wasting time.

Exploitation and chaining

Fifteen attack-module families (web/SQLi/XSS/upload, auth, JWT/crypto, deserialization, SMB, SSH, services, privesc, AD, persistence, supply chain, ICS/IoT, and more) with capability-aware planning — each module declares prerequisites so the planner composes chains dynamically. Payload crafting and mutation, Metasploit bridge (Linux full arsenal; Windows Python-only), and web scanners (nikto, nuclei, sqlmap, gobuster, feroxbuster, whatweb, wpscan).

Verification

Findings carry stored verification probes. verify_finding re-executes the probe N times; retest_finding re-checks confirmed findings later (STILL_OPEN / FIXED / INCONCLUSIVE). Optional kill-chain state machine advances stages only on passed probes. See docs/outcome-evidence.md.

Multi-agent orchestration

Six specialists (recon, vuln, exploit, post-exploit, critic, reflection) share a blackboard with parallel dispatch for single high-value targets (--swarm). The campaign orchestrator drives persistent multi-phase queues with resume and checkpoints across targets. Same authorization boundaries either way. See docs/swarm.md, docs/campaign.md.

Post-exploitation

Encrypted credential vault, Impacket-based lateral execution, Kerberoast, hash cracking (hashcat/john), AD attack paths (BloodHound CE, AS-REP roast, pass-the-hash, ADCS), and persistent beacons. ICS/IoT modules are read-only by default; writes are dual-gated. Web and browser testing runs through a sandboxed Playwright agent (mutating actions stay behind a config gate).

Reporting and integrations

Markdown + HTML reports with timelines, CVSS, exploit chains, loot tables, and attack-graph evidence; MITRE ATT&CK Navigator export; Jira/GitHub issue creation. Plugin system (plugins/, e.g. Shodan, ZAP, Sliver, SpiderFoot) adds tools and enrichment — off by default (opt in via plugins.enabled), most require their own API keys. See docs/plugin-development.md.

Tool and knowledge layer

The agent draws on a generated MCP tool catalog (gated, auto-discovered tools across recon, exploitation, credentials, browser, verification, and orchestration families) and a generated skill catalog (advisory SKILL.md playbooks with deterministic + semantic selection, mid-run re-selection, and cross-mission memory). Counts change as tools and skills are added — the linked catalogs are authoritative, not this paragraph.

Autonomy model

Execution is autonomous within configured authorization boundaries, while findings and other explicitly gated operations can use human approval. Concretely:

Concern Behavior
Execution authorization Recon mode is read_only (gathers and proposes, never attacks). Attack mode is full_access: in-scope actions are auto-approved — every offensive step does not ask for confirmation.
Target/scope enforcement Always on. The target-IP allowlist (IP, domain, *.wildcard, CIDR) blocks off-allowlist destinations at the MCP tool layer; the mission scope gate denies forbidden actions/assets with a SCOPE_DENIED audit row.
Operator decisions Optional finding approval: agents can propose_finding (PROPOSED); a human approves or rejects in the WebUI Evidence tab before it becomes a finding. Goal risk tiers (SAFE/GATED/HIGH) and opt-in gates (kill-chain, snapshots, browser mutations) add further decision points.
Evidence verification Independent of agent claims. Stored probes are re-executed; only passing probes confirm findings.

Safety and containment

Commands are scope-checked at the application layer, while the sandbox network boundary independently enforces the effective destination allowlist.

  • Authorized targets only. The allowlist is the scope authority: anything not explicitly allowed is BLOCKED at the tool layer, regardless of what a command or prompt says. Static command-string inspection is best-effort (dynamically constructed, DNS-resolved, or sub-interpreter destinations may not be visible) — the sandbox egress firewall below is the containment authority.
  • Mission scope gate. forbidden_actions / disallowed_assets deny with an auditable SCOPE_DENIED row. Recon stays scope-gated even in attack mode.
  • Disposable worker. Attack commands run in a per-run Docker container (non-root, capability-dropped, read-only rootfs, resource limits), destroyed afterward. Build it once: docker build -t breachpilot-sandbox:latest docker/sandbox.
  • Network containment, fail closed. An ephemeral firewall in the worker's network namespace authorizes only the effective allowlist. Sandbox failures deny execution with structured SANDBOX_* errors — native host execution requires explicit, separate opt-in and is developer-only.
  • Tamper-evident audit. Every action lands in a SHA-256-chained JSONL audit trail with loot, credentials, and graph evidence.

Full model, threat model, and residual risks: docs/safety-model.md, docs/sandbox.md.

WebUI

Mission control at http://127.0.0.1:8765 (loopback-only, token-authenticated, real-time event stream). Operator workflows: configure and launch runs, monitor live execution, inspect evidence and recon, explore attack graphs, review loot and credentials, triage proposed findings, browse skills and modules, run benchmarks, and manage system configuration — no YAML editing required. Dev hot-reload: cd webui && npm install && npm run dev. Reference: docs/webui.md, docs/api.md.

Native backend (Go + Rust)

The control plane is Go (cmd/bp, internal/) and the execution engine is Rust (rust/crates/, proto/exec.proto IPC). The React WebUI is unchanged and served against the same /api/v1 + WebSocket contract. Build:

go mod tidy && go build -o bp ./cmd/bp   # control plane
cargo build --release --bin bp-sidecar    # execution sidecar (in rust/)

Details: docs/migration-map.md; honest test status: docs/verification-report.md; Python removal tracker: docs/python-elimination-audit.md.

Configuration and AI providers

Everything lives in config.yaml (validated against a schema), editable from the WebUI System pages. Providers are pluggable (ollama, opencode_go, chatgpt) — bp --doctor probes only the active one, and embeddings are a separate optional layer. Model routing, browser agent, sandbox, API concurrency, and benchmark suites are all config-driven. Key reference: docs/config-reference.md; providers: docs/providers.md.

API keys (OPENCODE_GO_API_KEY, OLLAMA_API_KEY, optional NVD/GitHub/SerpAPI keys) live in the environment or gitignored secr.json. bp --setup-api-keys walks through setup.

Data residency: loopback Ollama keeps prompts on-box (local); Ollama Cloud, OpenCode Go, and ChatGPT send prompts + target data off-box (cloud) — the WebUI badges each provider and asks for explicit acknowledgement before a cloud route is used. Boundary table: docs/providers.md#data-residency--privacy-boundary.

Evaluation and quality

  • Tests: mocked pytest suite (no live Nmap) covering scope gates, recon, swarm, audit chains, credentials, and Metasploit. Run one file at a time per repo policy (see AGENTS.md).
  • CI: pytest matrix (Python 3.11–3.13), coverage, CodeQL, dependency review on every push/PR.
  • Lint/types: ruff check . and ruff format --check . must be clean; mypy over tools/; WebUI via tsc, vite build, and vitest.
  • Regression: bp --eval (oracle-graded targets) and bp --benchmark (sandboxed suites) with --save-baseline / --check-regression gates, surfaced in the WebUI Benchmarks page and nightly workflows. The gates fail on score drift and on stopping-judgement drift: false-compromise rise, any scope violation reaching the network layer (>0), and stuck-loop rise.

Reliability over capability counts

BreachPilot is graded on verified performance, not on how many tools or skills it ships. The headline numbers are the five release-grade rates in the live reliability table — verified compromise rate, false-compromise rate, scope violations reaching the network layer (must read 0), median actions to a verified finding, and findings reproduced twice — each with its reproduction command. No live numbers are claimed until hermetic trials produce them. The shipped XBEN targets currently have no reset mechanism and support one independent trial per scenario; repeated-trial reliability claims need reset-capable target infrastructure.

docker compose -f eval_targets/docker-compose.yml up -d
python main.py --benchmark xben --trials 1
# These eval baseline commands currently fail closed until live scope telemetry is wired.
python main.py --eval --save-baseline
python main.py --eval --check-regression
docker compose -f eval_targets/docker-compose.yml down

For benchmark runs, --timeout-seconds <SECONDS> overrides the per-trial mission timeout (minimum 30 seconds); otherwise BreachPilot uses benchmark.timeout_seconds from the effective configuration.

Inventory counts never appear in headlines: tool and skill totals live only in the generated catalogs — the MCP tool catalog and skill catalog, with live numbers in docs/generated/capability-counts.json (python scripts/generate_capability_counts.py --check fails CI on drift).

python3 -m pytest tests/test_scope_gate.py -v -p no:cacheprovider -n 0
ruff check . && ruff format --check .
mypy --follow-imports=skip tools

See docs/testing-guide.md, docs/evaluation.md, docs/benchmarks.md.

Documentation

Topic Links
Start here Getting Started · Tutorial · CLI Reference · Glossary
Design Architecture · Runtime Flows · Safety Model · Sandbox
Operating WebUI · API · Deployment · Config Reference
Capabilities Attack Modules · Swarm · Campaign · MCP Tools · Providers · Skills
Assurance Evaluation · Benchmarks · Testing Guide · Release Checklist

Full index (40+ guides): docs/README.md.

Contributing

  1. Read AGENTS.md (test-run rules and frozen-file constraints are mandatory).
  2. Run bp --doctor && bp --self-test after safety-area changes.
  3. Before a PR: one test file at a time, then ruff check ., ruff format --check ., mypy --follow-imports=skip tools, plus the WebUI build/tests. CI repeats all of this plus CodeQL. Release sign-off additionally requires every gate in docs/release-checklist.md.
  4. Never edit frozen Flow B files (scope_gate.py, safety_reviewer.py, legacy/). Root Flow B shims warn on import (removal in 0.71); canonical imports are legacy.* — see legacy/README.md. New MCP tools: add @audit_tool / @require_allowlist() in tools/mcp_tools/<family>.py — registration is automatic.

License

Apache 2.0. See LICENSE. Repository: github.com/braydos-h/BreachPilot.

About

Autonomous Offensive Security Agent for Red Team Operations

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages