# π©οΈ T3MP3ST π©οΈ
```
βββββββββββββββ ββββ βββββ ββββββ ββββββ ββββββ βββββββββ
β βββ ββββ β βββββββ βββββββ βββββ β βββ β β βββ ββ
β ββββ ββββββ βββ ββββββββ ββββββββ β ββββ β ββββ ββ
β ββββ β βββ β βββ βββ βββββββ ββββ β β ββββ ββββ β
ββββ β βββββββββββ ββββββββ β βββββββββββββββββ ββββ β
β ββ ββ ββ ββ ββ β βββββ β βββ ββ ββ βββ β β β ββ
β β β ββ β βββ β β β ββ ββ β β β
β β β β ββ β β β β β
β β β β β β
T3MP3ST - Multi-Agent Red Team / Penetration Testing Framework
```
### β°β’-β’β§ 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.**
   
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.
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.
**And not just web β every domain here is real, no vaporware:**
- πΈοΈ **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
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`.
## π The proof β re-derivable benchmarks (receipts, not vibes)
> **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:
### 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 |
|---|---|---|
| **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)) | β |
> *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.*
**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:
```bash
npm install
npm run doctor
npm run server
```
Open `http://127.0.0.1:3333/ui/`, then in the War Room ops card click **Preflight** and **Sync Arsenal**.
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:
```bash
npm run field:drill
npm run exploit:smoke
npm run arsenal:smoke
npm run prompt:audit
```
The UI intentionally separates catalog tools, wired backend adapters, and locally installed command adapters. Missing binaries are activation work, not hidden success.
## ποΈ 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 β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
## π Agent Archetypes (Operators)
| Operator | Phase | MITRE Tactics | Primary 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 |
## βοΈ Kill Chain Integration
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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) β
β ββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
## π Quick Start
```typescript
import { createTempest, KillChainPhase } from 't3mp3st';
// 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,
},
});
// 2. Define target environment
tempest.targetEnv.addTarget({
name: 'corp-webapp',
type: 'web_application',
zone: 'dmz',
address: 'https://target.example.com',
});
// 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');
// 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',
],
});
// 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
---
**Don't trust the numbers. Run them.** Β· `npm run verify-claims`
*Fortes fortuna iuvat* β fortune favors the bold, and the reproducible.
β°β’-β’β§ LOVE PLINY β§β’-β’β± π©οΈ