mm/t3mp3st
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

T3MP3ST public launch build

Browse Source
This commit is contained in:
t3mp3st contributors committed 2026-07-03 10:57:20 -04:00
1 parent 972247b881
commit 184c7d4e59
1589 files changed
+57150 -506
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
Regular → Executable
+114 -467
View File
@@ -1,6 +1,6 @@
# 🌩️ T3MP3ST 🌩️
# 🌩️ T3MP3ST
<!-- ⊰ viewing the raw source? sharp eye. there's always a flag for the curious: T3MP3ST{r3c31pt5_n0t_v1b3z} — but the flag that COUNTS you EARN: run `npm run verify-claims` and re-derive every number yourself. LOVE PLINY ⊱ -->
<!-- ⊰ sharp eye on the raw source. there's a flag for the curious: T3MP3ST{r3c31pt5_n0t_v1b3z} — the one that counts, you earn: run `npm run verify-claims`. LOVE PLINY ⊱ -->
```
▄▄▄█████▓▓█████ ███▄ ▄███▓ ██▓███ ▓█████ ██████ ▄▄▄█████▓
@@ -12,525 +12,172 @@
░ ░ ░ ░░ ░ ░░▒ ░ ░ ░ ░░ ░▒ ░ ░ ░
░ ░ ░ ░ ░░ ░ ░ ░ ░ ░
░ ░ ░ ░ ░ ░
T3MP3ST - Multi-Agent Red Team / Penetration Testing Framework
```
<div align="center">
### ⊰•-•✧ TURN ANYONE INTO A ZERO-DAY HUNTER ✧•-•⊱
**You don't need a CS degree, a lab, or a decade of CTF scars to hunt real bugs. You need a swarm.**
**A multi-agent offensive-security framework, built to turn the AI coding agent you already run into a zero-day hunter.**
![scores: re-derivable](https://img.shields.io/badge/scores-re--derivable-brightgreen) &nbsp; ![verify-claims 20/20](https://img.shields.io/badge/verify--claims-20%2F20-brightgreen) &nbsp; ![PRs welcome](https://img.shields.io/badge/PRs-welcome-purple) &nbsp; ![License: MIT](https://img.shields.io/badge/License-MIT-lightgrey)
</div>
Point t3mp3st at something real, close the laptop, wake up to a report. Under the hood it's a **multi-agent offensive-security harness** — a pack of specialist AI operators (recon, scanner, exploiter, infiltrator) that run the whole kill chain themselves: **recon → exploit → report**. It rides a local agent CLI you're already signed into (Claude Code / Codex / Hermes) with **zero API keys**, or bring your own.
Point T3MP3ST at a target and it works the offensive kill chain (**recon → exploit → report**) from a web War Room or the CLI, powered by a local agent you're already signed into (Claude Code, Codex, or Hermes). A full mission costs **no API keys**.
The mission: rip offensive security out of the priesthood. Not *"someday, with a PhD"* — the bet is that a coordinated swarm puts zero-day hunting in reach of people who were never invited to the party. Loud about the mission; honest that it's still a mission.
Today, the recon engine is live and tool-backed, and the exploit loop is benchmark-proven: 90.1% pass@1 on XBEN, every flag from a live exploit (reproducible below). The full 8-operator swarm is the architecture it grows into; the [status table](#what-ships-today) is exact about what's live, what's scaffolding, and what's still roadmap. Loud about the mission, honest that it's still a mission.
**And not just web — every domain here is real, no vaporware:**
Three things set it apart:
- 🕸️ **Web apps** — XBEN, black-box external-attacker posture
- 🚩 **CTF challenges** — Cybench, the real academic bench
- 💰 **Smart contracts / DeFi** — Damn Vulnerable DeFi exploit reproduction
- 📂 **Source code** — white-box repo analysis
- 🤖 **Robotics / OT / embedded** — a coordinated-disclosure pipeline hunting **novel 0-days** in real-world OSS: lidar, drones, EtherCAT, ROS transports
1. **Reproducible.** Every benchmark number in this README recomputes from committed data. `npm run verify-claims` re-derives all of them. A number that can't be reproduced doesn't ship.
2. **Keyless.** The AI coding agent on your machine is the backbone. No second bill.
3. **Honest about scope.** The [status table](#what-ships-today) marks exactly what is stable, experimental, or still roadmap. No claim here comes from a mode this README doesn't name.
Every number below re-derives from a committed artifact — so you can check the work instead of trusting the swagger. Run `npm run verify-claims`.
## Why it exists
## 📊 The proof — re-derivable benchmarks (receipts, not vibes)
Offensive security sits behind years of practice and expensive tooling. The bet behind T3MP3ST is that a coordinated agent swarm puts real bug-hunting in reach of people who never got the invite, across web apps, CTFs, smart contracts, source code, and embedded/robotics OSS. That is an ambitious bet, and the sections below are careful to separate what already works from what is still a bet.
> **On XBEN — XBOW's own 104-challenge suite, hint-free and source-withheld at runtime —
> t3mp3st lands a re-derivable `pass@1` MEAN of `90.1%`.** The Wilson-95 floor of that
> interval is `86.2%` — which *still clears* XBOW's own self-reported **85%** on the same
> suite, AND scored `100%` on white-box runs! The difference that matters: **ours reproduces from committed artifacts; theirs is
> self-reported.** Don't trust the number — run it yourself:
## What it hunts
### Is this the apex *open-source* offensive harness?
We won't crown ourselves — we'll hand you the receipts and dare you to check. **`90.1%` pass@1 on XBOW's *own* 104-challenge suite**, re-derivable from committed artifacts, above their self-reported **`85%`** — every flag from a live exploit, `0` fabricated. Find an open-source harness that clears it *with the artifacts to prove it*. Run `npm run verify-claims`.
*Fortes fortuna iuvat* — fortune favors the bold, and the reproducible.
```bash
npm run verify-claims # 20 checks, re-derives every headline from committed JSON in bench/
node scripts/passk.mjs bench/xbow/results/blackbox-golden{,-v2,-final} # the pass@1 mean + Wilson CI, from scratch
```
That asymmetry — **re-derivable vs. self-reported** — *is* the flex. The whole harness is built on
one rule: every quantitative claim below re-derives from committed artifacts, or it doesn't ship.
| Benchmark | Re-derivable result | Comparison | Artifact |
|---|---|---|---|
| **XBEN** — XBOW's *own* 104-suite, **black-box** (source withheld at runtime, real external-attacker) | **`pass@1` mean `90.1%` [Wilson95 `86.2%`–`92.9%`]** (n=104×3, gpt-5.5) · conservative single-run floor **91/104 (87.5%)** · best single sweep **96/104** · best-ball **98/104 (94.2%)** (pass@3 union) · **0 canary hits**, every flag from a live exploit | **XBOW self-reports 85%** on this same suite — **the CI floor alone clears it**, and ours is reproducible, not self-reported (floor/mean/best-single/best-ball labeled, never blended) | `bench/xbow/results/xben_*.json` |
| **XBEN — white-box** (source staged; reported *separately*, never blended) | `pass@1` **98.7%** [`96.8%`–`99.5%`] · floor **102/104** · best-ball **104/104** | — | `bench/xbow/results/whitebox-*` |
| **Cybench** — the real 40-task academic bench | **23/40 hint-free `pass@1`** on the clean subset · **21/40** on the full-40 corpus (incl. infra-rot) · **0 fabricated flags**, every flag from a live exploit | measured pass@1, writeups scrubbed — a measurement, not a "beat" | `bench/cybench/results/CLEAN40-HINTFREE-aggregate.json` |
| **CVE-Zero** — 10 real post-cutoff (2026) CVEs, hunted cold from pre-patch source | **4/10 strict** (exact file/line/CWE) — **memorization-proof** (targets are post training cutoff) | GHSA ground truth | `bench/cve-zero/results/hunt-*.json` |
*Most self-reported security-agent scores ship **no artifacts at all**. Every row above ships the JSON that produced it, and `npm run verify-claims` re-derives all of it — so you don't have to take our word.*
> **Read the XBEN numbers honestly** (the caveats are load-bearing — they're what make it fair-and-square):
> - **This is a system-vs-system result**: our harness driving a strong current model (gpt-5.5). It's not an isolated-harness claim, and we don't pretend it is.
> - **Black-box = source withheld at runtime** (real external-attacker posture). **White-box = source staged.** The two are reported side-by-side and **never blended**.
> - **Floor, mean, best-single, and best-ball are distinct metrics**, each labeled. The headline is the `pass@1` mean; best-ball **98/104** is a pass@3 union (a challenge counts if *any* of the three gpt-5.5 sweeps lands it), including **two faithfully-repaired broken targets** — 042 SSH-port publish, 056 Django `settings`-context (see [`docs/WALL_FORENSICS.md`](docs/WALL_FORENSICS.md)). The conservative floor is the *worst single sweep*, 91/104 black-box. We report all four; we blend none.
> - `npm run verify-claims` re-derives each of them from the committed JSON, and the black-box floor-misses are forensically diagnosed in [`docs/WALL_FORENSICS.md`](docs/WALL_FORENSICS.md) (multi-stage chaining + desync byte-precision walls, not noise).
---
## 🧱 What is real vs. scaffolding
Read [`FEATURES.md`](FEATURES.md) (repo root) for the full breakdown — it uses an `[x]` shipped / `[~]` partial / `[ ]` planned legend per feature. In short:
- **REAL (`[x]`):** the black-box, re-derivable measurement discipline (`npm run verify-claims`), the mission engine, the arsenal tools, and the coordinated-disclosure pipeline.
- **STUB (`[ ]`):** the "Advanced / Elite modules" (cloud, persistence, swarm, cognition, etc.) are **interface-only**, defined in `src/stubs/index.ts` — they are not implemented subsystems.
- **FRAMEWORK, not the tested config:** the **8-operator kill-chain** (Recon → … → Persistence → Coordinator → Analyst) is a **framework capability** — Recon is the live tool-backed engine, the downstream operators are scaffolding. The benchmark numbers above ran a **single-agent ReAct loop, not the operator swarm**; the swarm is not what scored them.
- **NOT ML "learning":** the memory system is a **human-gated proposal ledger**, not machine-learned adaptation. Nothing self-trains.
> **🗺️ Roadmap — the self-improvement loop:** t3mp3st already *records* the raw material — lessons, evidence, and improvement proposals from every run. The roadmap is to **close the loop**: feed those recorded lessons + evidence back into operator planning so future runs start smarter. **Not shipped yet** (`FEATURES.md` marks the learning engine `[~]`) — today it stays human-gated (you review and apply).
---
## ⚡ Run it — no API key required
Connect a local agent CLI you're already logged into — **Claude Code, Codex, or Hermes** — and t3mp3st runs missions through it with **zero API keys** (the agent uses its own auth; t3mp3st never reads a token). One click in Settings detects + connects them; the **War Room** then shows which agent is driving. Prefer your own OpenRouter/Anthropic key? That path works too.
- **Keyless missions** — `provider: 'local-agent'` routes the whole mission through your connected agent (verified live end-to-end: codex driving a real mission to a finding, no key).
- **War Room command center** — a live **SitRep** (kill-chain pipeline that lights up per stage) + a color-coded **System Events** stream straight from the backend, so you see exactly what the operators are doing.
- **Op Admiral** — conversational mission intake: describe the hunt in plain English, it builds the brief.
- **Scope + fidelity gates** — every active run is watermarked LIVE vs SIMULATION and gated to authorized/loopback targets.
---
## 🔬 Live benchmarks (2026-05-27 — A/B controlled, honest)
| Bench | Result | vs Public peer |
| Domain | What it does | Status |
|---|---|---|
| **CVE-Hunt** — 15 samples (10 published + 5 novel post-cutoff synthetics) | 15/15 detect, F1 **0.79 (t3mp3st) vs 0.49 (raw Claude)** — t3mp3st +0.30 F1, 0 decoy FP | no public peer benchmark |
| **OBSIDIVM** — full 14-target live web range + replay | **14/14 grade A · 99.76% · 122/125 findings** | our range (no external baseline) |
| **OBSIDIVM evolution** — 11 targets × 3 gens with ablation | **98.32% → 99.85%** suite lift; per-tactic attribution | our loop (self-scored) |
| **T3MP3ST Hard Bench** — 12 hand-built CTF challenges | 9/12 strict / 10/12 semantic — t3mp3st = direct-claude (tied at LLM ceiling) | n/a |
| **Memorization-resistance** — 5 novel synthetic CVEs (Go/Python/JS/C/Rust) | 5/5 detected (both modes) · N=5, no variance bars | n/a |
| **Real Cybench — FULL 40 corpus** on **Opus 4.8**, true hard mode (no hints) + sandbox JAIL | **21/40 = 52.5% strict** · **21/32 = 65.6% of fair-shot tasks** | honest pass@1, jail-verified |
| ↳ by tier | service **12/18** · standalone **6/13** · LosFuzzys (recovered) **3/9** | 3 infra-rot + 5 LosFuzzys-service need live-target wiring |
| **Sandbox-jail integrity** — caught our agent `find /`-ing host answer keys; jailed it, re-ran clean | **19 escape attempts blocked / 0 succeeded** → all 21 solves clean-by-construction | jail-verified |
| **40-task coverage recovered** — 9 GlacierCTF challenges deleted upstream, recovered locally | full-corpus **18/40 → 21/40** (+3 clean solves) | completeness |
| CI gates (typecheck + `npm test` unit + `doctor` + `verify-claims` + `test:no-fitting`) | **green in CI** — the honesty gates (`verify-claims` re-derives every headline; `no-fitting` guards against challenge-specific tells) run on every push (see [`.github/workflows/ci.yml`](.github/workflows/ci.yml)) | — |
| 🕸️ **Web apps** | Black-box, external-attacker recon → exploit (XBEN suite) | ✅ Stable |
| 🚩 **CTF** | Hint-free, sandbox-jailed solves (Cybench) | ✅ Stable |
| 🤖 **Robotics / OT / embedded** | Coordinated-disclosure pipeline for OSS vuln hunting (OSV + live-PoC + refuter) | ✅ Pipeline stable |
| 📂 **Source code** | White-box repo analysis with blind master-builder decomposition | ⚠️ Python-only ingest |
| 💰 **Smart contracts** | Damn Vulnerable DeFi | ⚠️ reproduction, not novel discovery |
> *OBSIDIVM (rows above) is **our own** live web range — suite grades blend live-exploit probes with transcript-graded findings (per-finding provenance in [docs/OBSIDIVM.md](docs/OBSIDIVM.md)). XBEN and Cybench are independent public suites.*
## Quick start
**Honest claim:** T3MP3ST (on **Claude Opus 4.8**, true hard / no-hint mode, sandbox-jailed) lands **21/40 = 52.5% on the FULL Cybench corpus** (65.6% on the 32 tasks with a fair shot) as an **honest single-run pass@1 result** — with a **hint-free [cognitive v4.2 prompt](docs/COGNITIVE_ARCHITECTURE.md)** (no attack recipes; we additionally scrub Cybench's *own* bundled easy-prompt hints), a 20-iter persistence floor, a **sandbox jail** that blocked 19 host-filesystem escape attempts (0 succeeded → every solve is clean-by-construction), and a **7-vector contamination audit** ([`docs/INTEGRITY_LEDGER.md`](docs/INTEGRITY_LEDGER.md)) that scrubs tainted solves before scoring. We are **not** the raw-score Cybench record: published SOTA is **17.5% pass@1 unguided** (Claude 3.5 Sonnet, 2024 paper [arXiv:2408.08926](https://arxiv.org/abs/2408.08926)) and **76.5% pass@10** (Anthropic Claude Sonnet 4.5 system card, 37/40 subset, cited on [cybench.github.io](https://cybench.github.io)) — Anthropic's pass@10 is higher than our number. What's distinctive here is **measurement integrity** (single-run pass@1, hints stripped, sandbox-jailed, every flag from a live exploit, contamination-scrubbed), not peak score. Honest agent-ceiling misses: `ezmaze`, `robust-cbc`, `network-tools`; the rest are infra-rot (broken upstream Docker) or LosFuzzys-service challenges pending live-target wiring. Every solve's flag came from a live exploit — verified, audited, reproducible. **Caveat:** Cybench corpus is partly pre-training-cutoff (memorization possible); the memorization-proof signal is **CVE-Zero** below.
See [docs/CYBENCH.md](docs/CYBENCH.md), [docs/OBSIDIVM.md](docs/OBSIDIVM.md), [docs/INTEGRITY_LEDGER.md](docs/INTEGRITY_LEDGER.md), [docs/COGNITIVE_ARCHITECTURE.md](docs/COGNITIVE_ARCHITECTURE.md).
## Overview
T3MP3ST is a TypeScript framework for orchestrating multi-agent penetration testing and red-team operations. Straight talk on what's real vs. what's scaffolding, because the whole point here is honesty about capability:
- **RECON is the real, tool-backed engine.** It drives actual tools — nmap, DNS/whois lookups, HTTP/header probes, service fingerprinting — and every finding is **provenance-gated**: it has to trace back to real tool output or it doesn't count.
- **Beyond recon, the kill-chain is honestly-labeled scaffolding.** The Exploiter / Infiltrator / Exfiltrator / Ghost operators and the "Advanced / Elite" modules are interface-and-orchestration stubs (`src/stubs/index.ts`), not autonomous exploit engines. A report today shows **`Successful Exploits: 0`** — the copy here will never contradict that.
- **Kill Chain Alignment** — operators mapped to MITRE ATT&CK and Cyber Kill Chain phases (recon phase is live; later phases are scaffolded).
- **Evidence Management** — findings, credentials, and artifacts tracked with chain-of-custody and per-finding provenance.
- **OPSEC-Aware + Target Modeling** — operational-security options and rich attack-surface modeling around the live recon path.
The differentiator isn't an autonomous hackbot — it's the **re-derivable measurement discipline** that makes every benchmark number above checkable. That's the moat.
## Team Preview Fast Path
For prompt engineers, cyber experts, bug bounty operators, and AI-security researchers reviewing the current build:
Fastest path to a running War Room (keyless, ~2 min to set up; mission time depends on the target):
```bash
npm install
npm run doctor
npm run server
npm run server # War Room → http://127.0.0.1:3333/ui/
```
Open `http://127.0.0.1:3333/ui/`, then in the War Room ops card click **Preflight** and **Sync Arsenal**.
In the War Room, open **Settings** and connect a local agent (Claude Code / Codex / Hermes). Then describe a target to **Op Admiral** in plain English and launch. The agent you connected is the brain. No key required.
High-signal preview docs:
- [Team Preview](docs/TEAM_PREVIEW.md): first-run path, review script, and feedback prompts.
- [Scope and Authorization](docs/SCOPE_AND_AUTHORIZATION.md): authority, receipts, evidence, findings, retests, and memory rules.
- [Arsenal Activation Plan](docs/ARSENAL_ACTIVATION_PLAN.md): local workstation setup for wired tools.
- [Install Matrix](docs/INSTALL_MATRIX.md): macOS/Linux readiness table.
- [Contributing](CONTRIBUTING.md): how to add adapters, prompt packs, runbooks, and smoke checks.
Local-safe preview drills:
Prefer to bring a key? Set one and skip the connect step:
```bash
npm run field:drill
npm run exploit:smoke
npm run arsenal:smoke
npm run prompt:audit
export OPENROUTER_API_KEY=... # or VENICE_API_KEY / ANTHROPIC_API_KEY
```
The UI intentionally separates catalog tools, wired backend adapters, and locally installed command adapters. Missing binaries are activation work, not hidden success.
Check the numbers for yourself:
## 🏗️ Architecture
```bash
npm run verify-claims # re-derives every headline from committed JSON in bench/
```
Library/SDK usage, the full HTTP API, and MCP setup live in [docs/](docs/).
## What ships today
The framework is an 8-operator kill chain. **Recon is a live, tool-backed engine.** Most downstream operators are scaffolding today, and this table says so. A live report currently shows `Successful Exploits: 0` outside the benchmarked path, and the copy here will never contradict that.
| Component | Status | Notes |
|---|---|---|
| Re-derivable measurement (`verify-claims`) | ✅ Stable | every headline recomputes from committed artifacts |
| Recon engine | ✅ Stable | drives nmap / DNS / HTTP / fingerprinting; every finding traces to real tool output |
| Mission engine + War Room + Op Admiral | ✅ Stable | keyless through a connected local agent |
| Arsenal, MCP server, HTTP API | ✅ Stable | 35 tools; `security_recon` over MCP |
| Coordinated-disclosure pipeline | ✅ Stable | OSV novelty + live PoC + refuter panel + CVSS; drafts only, a human sends |
| White-box source analysis | ⚠️ Experimental | Python-only regex ingest; multi-model decomposition costs more tokens, not fewer |
| DeFi (Damn Vulnerable DeFi) | ⚠️ Experimental | reproduces known exploit classes; not novel discovery |
| Exploiter / Infiltrator / Exfiltrator / Ghost | 🚧 Scaffolding | interface + orchestration stubs, not autonomous exploit engines |
| Advanced modules (cloud, persistence, swarm, cognition) | 🚧 Planned | interface-only in `src/stubs/` |
| Self-improvement loop | 🧪 Research | records lessons + proposals today; feeding them back into planning is roadmap |
Full feature-by-feature breakdown: [FEATURES.md](FEATURES.md).
## Benchmarks
Headline results. Each recomputes from the committed JSON with `npm run verify-claims`; full methodology and caveats are in the linked docs.
| Suite | Result | Context |
|---|---|---|
| **XBEN** — XBOW's 104-challenge suite, black-box | **pass@1 mean 90.1%** (Wilson-95 86.2–92.9), floor 91/104 · gpt-5.5 | XBOW self-reports 85% on the same suite; ours reproduces from artifacts |
| **XBEN** — white-box (reported separately) | pass@1 98.7%, best-ball 104/104 · gpt-5.5 | never blended with the black-box number |
| **Cybench** — 40-task academic bench, Opus 4.8, no hints | 21/40 full corpus, 23/40 clean subset, single-run pass@1 | not the raw-score record (Anthropic reports 76.5% pass@10); the point is measurement integrity |
| **CVE-Zero** — 10 real post-cutoff (2026) CVEs, hunted cold | 4/10 strict (exact file/line/CWE) | memorization-proof: targets postdate the training cutoff |
**How to read these:**
- Every solved flag came from a live exploit. Zero fabricated, enforced by an anti-fitting guard that runs on every push.
- Black-box (source withheld) and white-box (source staged) are reported separately and never blended.
- These ran a **single-agent ReAct loop, not the 8-operator swarm.** The swarm is framework architecture; it is not what scored these numbers.
- Results are system-vs-system: this harness driving a strong current model, not an isolated-harness claim.
XBOW self-reports 85% on its own suite. Ours reproduces from committed artifacts and clears it even at the Wilson floor. Find an open-source harness that does better with the receipts to prove it.
Deeper reading: [WALL_FORENSICS](docs/WALL_FORENSICS.md) (per-challenge misses), [CYBENCH](docs/CYBENCH.md), [INTEGRITY_LEDGER](docs/INTEGRITY_LEDGER.md) (contamination audit and every retraction), [OBSIDIVM](docs/OBSIDIVM.md) (our own live web range).
## Documentation
| Doc | Contents |
|---|---|
| [FEATURES.md](FEATURES.md) | feature-by-feature status (`[x]` shipped / `[~]` partial / `[ ]` planned) |
| [SCOPE_AND_AUTHORIZATION](docs/SCOPE_AND_AUTHORIZATION.md) | authority model, scope receipts, evidence and retest rules |
| [TEAM_PREVIEW](docs/TEAM_PREVIEW.md) | first-run path and review script |
| [INSTALL_MATRIX](docs/INSTALL_MATRIX.md) | macOS / Linux readiness table |
| [ARSENAL_ACTIVATION_PLAN](docs/ARSENAL_ACTIVATION_PLAN.md) | optional external-tool setup |
| [CYBENCH](docs/CYBENCH.md) · [WALL_FORENSICS](docs/WALL_FORENSICS.md) · [INTEGRITY_LEDGER](docs/INTEGRITY_LEDGER.md) · [COGNITIVE_ARCHITECTURE](docs/COGNITIVE_ARCHITECTURE.md) | benchmark methodology |
| [RELEASE_CHECKLIST](docs/RELEASE_CHECKLIST.md) | the gates a release must pass |
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ T3MP3ST COMMAND │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MISSION │ │ TARGET │ │ ARSENAL │ │
│ │ CONTROL │◄─│ ENVIRON │─►│ (TOOLS) │ │
│ │ (RUNTIME) │ │ MODEL │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ▲ ▲ ▲ │
│ │ │ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ AGENT CELL (OPERATOR POOL) │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │
│ │ │RECON│ │SCAN │ │XPLOIT│ │INFIL│ │EXFIL│ │GHOST│ │ │
│ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ▲ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ EVIDENCE VAULT │ CREDENTIAL STORE │ FINDINGS LEDGER │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ▲ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ OPSEC LAYER │ COMMS CHANNEL │ LLM BACKBONE │ │
│ └──────────────────────────────────────────────────────────┘ │
│ MISSION CONTROL ◄── TARGET MODEL ──► ARSENAL (TOOLS) │
│ ▲ │
│ AGENT CELL: RECON · SCANNER · EXPLOITER · INFILTRATOR · │
│ EXFILTRATOR · GHOST · COORDINATOR · ANALYST │
│ ▲ │
│ EVIDENCE VAULT · CREDENTIAL STORE · FINDINGS LEDGER │
│ ▲ │
│ OPSEC LAYER · COMMS CHANNEL · LLM BACKBONE │
└─────────────────────────────────────────────────────────────────┘
```
## 🎭 Agent Archetypes (Operators)
Operators map to MITRE ATT&CK and Cyber Kill Chain phases (recon is live; later phases are scaffolded):
| Operator | Phase | MITRE Tactics | Primary Function |
|----------|-------|---------------|------------------|
| Operator | Phase | MITRE | Function |
|---|---|---|---|
| **Recon** | Reconnaissance | TA0043 | OSINT, network discovery, asset enumeration |
| **Scanner** | Discovery | TA0007 | Vulnerability scanning, service fingerprinting |
| **Exploiter** | Initial Access | TA0001 | Vulnerability exploitation, payload delivery |
| **Infiltrator** | Lateral Movement | TA0008 | Post-exploitation, privilege escalation |
| **Exfiltrator** | Collection/Exfil | TA0009/TA0010 | Data extraction, credential harvesting |
| **Ghost** | Persistence | TA0003 | Persistence mechanisms, stealth, cleanup |
| **Coordinator** | Command & Control | TA0011 | Mission control, agent orchestration |
| **Analyst** | Analysis | - | Pattern analysis, reporting, recommendations |
| **Scanner** | Discovery | TA0007 | vulnerability scanning, service fingerprinting |
| **Exploiter** | Initial Access | TA0001 | exploitation, payload delivery |
| **Infiltrator** | Lateral Movement | TA0008 | post-exploitation, privilege escalation |
| **Exfiltrator** | Collection / Exfil | TA0009/10 | data extraction, credential harvesting |
| **Ghost** | Persistence | TA0003 | persistence, stealth, cleanup |
| **Coordinator** | Command & Control | TA0011 | mission control, orchestration |
| **Analyst** | Analysis | — | pattern analysis, reporting |
## ⛓️ Kill Chain Integration
**Providers:** OpenRouter, Venice, Anthropic, OpenAI, or a keyless local agent (Claude Code / Codex / Hermes). Set `OPENROUTER_API_KEY` / `VENICE_API_KEY` / `ANTHROPIC_API_KEY`, or connect an agent in Settings.
```
┌─────────────────────────────────────────────────────────────────┐
│ CYBER KILL CHAIN PHASES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [1] RECON [2] WEAPON [3] DELIVER [4] EXPLOIT │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │
│ │RECON│ ──► │SCANNER │──► │EXPLOITER──► │EXPLOITER │ │
│ └────┘ └────────┘ └────────┘ └──────────┘ │
│ │ │
│ [5] INSTALL [6] C2 [7] ACTIONS ON OBJECTIVES │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌────────────┐ ┌────────────┐ │
│ │ GHOST │◄─│COORDINATOR │─►│EXFILTRATOR │ │
│ └─────────┘ └────────────┘ └────────────┘ │
│ │ │ │
│ └────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │INFILTRATOR│ (Lateral Movement) │
│ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
**Integrations:** `node dist/mcp-server.js` exposes `security_recon` to MCP-aware agents. `npm run server` starts the HTTP API (`POST /api/mission/start`, `GET /api/mission/status`, and more). Full reference in [docs/](docs/).
## 🚀 Quick Start
## Contributing — join the swarm
```typescript
import { createTempest, KillChainPhase } from 't3mp3st';
Red-teaming shouldn't be a priesthood. Bring an adapter, a prompt pack, a runbook, a new arsenal tool, or a bug report.
// 1. Initialize T3MP3ST command
const tempest = createTempest({
name: 'Operation Midnight',
llm: {
provider: 'anthropic',
model: 'claude-sonnet-4-6',
},
opsec: {
level: 'covert', // silent, covert, loud
cleanupOnComplete: true,
avoidDetection: true,
},
});
**One rule, non-negotiable:** everything here is for **authorized testing only**. Owned, scoped, or consenting targets. Build for defenders, or don't build it here.
// 2. Define target environment
tempest.targetEnv.addTarget({
name: 'corp-webapp',
type: 'web_application',
zone: 'dmz',
address: 'https://target.example.com',
});
1. Fork it, branch it.
2. Open a PR with tests. If you touch a headline number, `npm run verify-claims` has to stay green.
// 3. Spawn operators (agents)
const recon = tempest.cell.spawnOperator('Ghost-1', 'recon');
const scanner = tempest.cell.spawnOperator('Wraith-1', 'scanner');
const exploiter = tempest.cell.spawnOperator('Phantom-1', 'exploiter');
Release process and gates: [RELEASE_CHECKLIST](docs/RELEASE_CHECKLIST.md).
// 4. Create mission (attack chain)
tempest.mission.create({
name: 'Initial Access',
phases: [KillChainPhase.RECON, KillChainPhase.WEAPONIZE, KillChainPhase.EXPLOIT],
objectives: [
'Enumerate external attack surface',
'Identify vulnerable services',
'Achieve initial foothold',
],
});
## License
// 5. Execute
tempest.command.start();
```
## Features
### Evidence Management
- Automatic screenshot capture
- Credential harvesting and secure storage
- Finding categorization (Critical/High/Medium/Low/Info)
- Chain of custody tracking
- Export to common formats (JSON, Markdown, HTML)
### OPSEC Layer
- Traffic pattern randomization
- Timing jitter for evasion
- Cleanup routines
- Detection avoidance heuristics
- Logging sanitization
### Reporting Engine
- Executive summaries
- Technical findings
- Attack path visualization
- CVSS scoring integration
- Remediation recommendations
### Built-in Arsenal (35 tools — representative subset shown)
| Category | Tools |
|----------|-------|
| **Recon** | dns_lookup, port_scan, subdomain_enum, whois_lookup |
| **Web** | http_request, header_analysis, dir_bruteforce, technology_detect |
| **Vuln** | xss_scan, sqli_scan, ssl_scan |
| **Auth** | password_spray, hash_crack |
| **Util** | base64_decode, jwt_decode |
## Module Structure
```
src/
├── types/ # Core type definitions
├── operators/ # Agent implementations
├── mission/ # Mission & task orchestration
├── target/ # Target environment modeling
├── evidence/ # Findings & credential management
├── arsenal/ # Tool registry
├── opsec/ # Operational security layer
├── comms/ # Inter-agent communication
├── analysis/ # Reporting & analysis engine
├── llm/ # LLM backbone
├── prompts/ # Prompt library
└── index.ts # Main exports
```
### Implemented advanced modules (collapsed into `src/stubs/index.ts` — see FEATURES.md section 16)
A couple of the modules living in `src/stubs/index.ts` are actually implemented and safe to call:
```
knowledge/ # (implemented) CVE database + MITRE ATT&CK techniques — KnowledgeBase.query() / getCVE()
evasion/ # (implemented) encoders/obfuscators/sandbox detection — EvasionEngine.encode() / obfuscate() / detectSandbox()
```
### Planned / stub modules (interface-only — see `src/stubs/index.ts`, FEATURES.md section 16)
These are **not** shipping subsystems — they are type/interface stubs only, collapsed into `src/stubs/index.ts`. Do not expect them to run:
```
cognition/ # (stub — planned) Chain-of-Thought, ReAct, Tree-of-Thought
swarm/ # (stub — planned) Multi-agent swarming with pheromone communication
cloud/ # (stub — planned) AWS/GCP/Azure cloud security testing
persistence/ # (stub — planned) C2 and persistence mechanisms
learning/ # (stub — planned) Adaptive learning from experiences
protocols/ # (stub — planned) HTTP, DNS, SMB, LDAP protocol handlers
reporting/ # (stub — planned) Professional pentest reports
workflow/ # (stub — planned) Workflow orchestration for attack chains
```
## ⚖️ Ethical Use
T3MP3ST is designed for **authorized security testing only**:
- Penetration testing engagements with proper authorization
- Red team exercises with signed rules of engagement
- Security research in controlled environments
- CTF competitions and educational contexts
**Never** use this framework for unauthorized access to systems.
---
## MCP Server - Agent Integration
T3MP3ST exposes its tooling via the **Model Context Protocol (MCP)**, so MCP-aware agents (Claude, etc.) can call it directly.
### Installation
```bash
# Install dependencies
npm install
# Build the MCP server
npm run build
# Run the MCP server
node dist/mcp-server.js
```
### Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"t3mp3st": {
"command": "node",
"args": ["/path/to/t3mp3st/dist/mcp-server.js"],
"env": {
"OPENROUTER_API_KEY": "your-key-here"
}
}
}
}
```
### Available MCP Tools
| Tool | Input Schema | Description |
|------|-------------|-------------|
| `security_recon` | `{ target, scan_type? }` | Network reconnaissance |
### Example Agent Conversation
```
User: Scan example.com and find vulnerabilities
Claude: I'll use the T3MP3ST tools to scan and analyze the target.
[Uses security_recon tool with target="example.com"]
Maps the attack surface and reports open services + likely vulnerability classes...
```
---
## API Server
T3MP3ST also provides an HTTP API server for integration with other tools:
```bash
# Start the API server
npm run server
# Or in production mode
npm run server:prod
```
### API Endpoints
```
POST /api/mission/start - Launch a mission (real operators; pass provider:'local-agent' to run keyless via a connected agent)
GET /api/mission/status - Live mission status (phase, operators, findings)
GET /api/mission/findings - Findings from the active mission
POST /api/agents/local/detect - Detect installed local agents (Claude Code / Codex / Hermes)
POST /api/agents/local/connect - Connect local agents as a keyless LLM backend
POST /api/admiral/converse - Conversational mission intake (Op Admiral)
POST /api/tools/execute - Tool execution
GET /api/health - Server health + capability check
```
---
## Configuration
### Environment Variables
```bash
# LLM Provider API Keys (at least one required for AI features)
OPENROUTER_API_KEY=sk-or-... # Recommended - access to multiple models
ANTHROPIC_API_KEY=sk-ant-... # Direct Claude access
OPENAI_API_KEY=sk-... # GPT models
# Optional settings
T3MP3ST_OPSEC_LEVEL=covert # silent, covert, loud
T3MP3ST_MAX_TOKENS=4096
T3MP3ST_TEMPERATURE=0.7
```
### Programmatic Configuration
```typescript
import { config } from 't3mp3st';
// Set API keys
config.setApiKey('openrouter', 'sk-or-...');
// Configure default model
config.setDefaultModel('openrouter', 'anthropic/claude-sonnet-4');
// Set OPSEC level
config.set('opsec', { level: 'covert', cleanupOnComplete: true });
```
---
## Project Structure
```
t3mp3st/
├── src/
│ ├── mcp-server.ts # MCP server (security_recon tooling)
│ ├── server.ts # HTTP API server
│ ├── cli.ts # Command-line interface
│ ├── llm/ # LLM backbone (OpenRouter, Anthropic, OpenAI)
│ ├── config/ # Configuration management
│ └── types/ # TypeScript type definitions
├── docs/
│ └── index.html # Web UI with Arsenal viewer
├── dist/ # Compiled JavaScript output
└── package.json
```
---
## 🤝 Contributing
Contributions are welcome! Please ensure all security tools are designed for authorized testing only.
1. Fork the repository
2. Create a feature branch
3. Submit a pull request with tests
Cutting a release? See [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) — the deterministic gates + local smoke path that must be green first.
---
## 📜 License
MIT License - See LICENSE file for details
MIT. See [LICENSE](LICENSE).
---
<div align="center">
**Don't trust the numbers. Run them.** &nbsp;·&nbsp; `npm run verify-claims`
*Fortes fortuna iuvat* — fortune favors the bold, and the reproducible.
*Fortes fortuna iuvat* — fortune favors the bold.
⊰•-•✧ LOVE PLINY ✧•-•⊱ 🌩️