tmestery/SPECTRE

Self-coordinating Penetration and Exploit Crew for Threat Research and Exposure
Multi-agent GitHub repository security audits with a live dashboard — scope-controlled and observable end to end.
---
> [!IMPORTANT]
> SPECTRE audits only repositories you own or have explicit permission to test.
> Every engagement requires a scope allowlist (scopes/*.yaml). Do not scan
> arbitrary public repos without authorization.
What it does
- **Four-agent crew** — Recon, VulnHunter, Exploiter, and Reporter coordinate through a shared Findings Bus
- **Live dashboard** — Watch findings, handoffs, and report sections stream in real time
- **Sandboxed tools** — GitHub API, gitleaks, osv-scanner, and workflow checks with timeouts and redaction
- **Safety by default** — Repo allowlists, audit logs, and an engagement kill switch
Run with Docker
**Requirements:** Docker with Compose, a GitHub token, and an LLM API key (Groq by default).
Open http://localhost:8080 and choose **Start audit**.
| Port | Service |
|------|---------|
| 8080 | Demo dashboard |
| 8765 | WebSocket control plane |
Optional CLI helpers (reports, halt, sessions):
Full details: Docker guide.
Configure
| Variable | Purpose |
|----------|---------|
| GITHUB_TOKEN | Access to authorized target repos |
| GROQ_API_KEY | LLM provider key (when LLM_PROVIDER=groq) |
| LLM_MODEL | Model id (see .env.example) |
Add a scope file under scopes/ listing allowed_repos before auditing a new target. Defaults ship for this repo (scopes/spectre.yaml) and a demo sample (scopes/vuln-sample.yaml).
Local development
Documentation
- Agent guide · Docs index
- Architecture · Safety & scope
- Docker · Demo UI
Security
Use SPECTRE only on authorized repositories. Keep tokens in .env; never commit secrets or unredacted findings. Report vulnerabilities in SPECTRE privately to the maintainers.