# elder-plinius/t3mp3st architecture

> Architecture diagram of the GitHub repository elder-plinius/t3mp3st, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elder-plinius/t3mp3st
- Repository: https://github.com/elder-plinius/t3mp3st

## Overview

#### Purpose and entry points
T3MP3ST is a TypeScript/Node.js, self-hosted offensive-security framework for authorized engagements. It orchestrates agent-driven reconnaissance, exploitation workflows, evidence handling, reporting, and reproducible benchmark evaluation. Primary entry points are the package CLI (`index.ts`, `src/cli.ts`), local HTTP/War Room server (`src/server.ts`), and MCP server (`src/mcp-server.ts`). Docker deployment is defined by `Dockerfile` and `docker-compose.yml`.

#### Mission control and orchestration
Mission execution centers on an orchestrator that turns target intent into agent tasks, shared context, and results. The control boundary is between mission planning/coordination and individual tool or model calls:
- `src/mission/index.ts`
- `src/orchestration/orchestrator.ts`
- `src/orchestration/context-pack.ts`
- `src/orchestration/types.ts`

The orchestration layer builds context packs, selects prompts/operators, dispatches work, and collects outputs. Mission adjudication is separated in `src/mission/adjudicate.ts`, allowing findings or task outcomes to be evaluated independently of generation.

#### LLM and local-agent boundary
The framework supports cloud providers and connected local coding agents; provider selection and model metadata are centralized rather than embedded in mission logic:
- `src/llm/index.ts`
- `src/agent/local-agents.ts`
- `src/config/provider-models.ts`

This is the principal external-service boundary: OpenRouter, Venice, Anthropic, OpenAI-compatible/local endpoints, and local agent CLIs. Credentials/environment configuration enter through `src/config/index.ts` and `.env.example`. Local-agent dispatch is a keyless alternative to API-backed models.

#### Targeting, reconnaissance, and source analysis
Target modelling and recon are distinct from orchestration, enabling black-box and white-box workflows:
- `src/target/index.ts`
- `src/recon/attack-graph.ts`
- `src/recon/code-ingest.ts`
- `src/recon/whitebox.ts`

For source targets, ingestion parses and extracts code structure, with TypeScript grammars/parsing isolated in `src/recon/ts-grammars.ts` and `src/recon/ts-parse.ts`. Recon can produce an attack graph and parameter splits before downstream tool-backed actions. Network proxy behavior is isolated at `src/net/proxy.ts`.

#### Arsenal, containment, and validation
The Arsenal is the controlled adapter layer for security tooling. Its catalog, adapters, parsers, and approval controls form a deliberate boundary between agent intent and command/tool execution:
- `src/arsenal/catalog.ts`
- `src/arsenal/adapter-tools.ts`
- `src/arsenal/parsers.ts`
- `src/arsenal/approval.ts`

Approval and scope enforcement constrain potentially dangerous operations; evidence validation is separately represented by `src/evidence/gate.ts` and `src/validation/index.ts`. This separation supports tool-proven findings rather than model-only assertions.

#### Evidence, reporting, and integrations
Evidence collection and report workspace management preserve artifacts across mission stages:
- `src/evidence/index.ts`
- `src/arsenal/report-workspace.ts`
- `src/integrations/bounty.ts`

The HTTP server exposes local API endpoints, while `src/mcp-server.ts` exposes the `security_recon` capability to MCP clients. The application is designed for localhost-oriented deployment; Docker Compose supplies the runtime boundary, and optional external security binaries are containerized via `tools/Dockerfile`.

#### Benchmark and reproducibility pipeline
Committed corpora, oracle data, and run receipts make benchmark claims independently recomputable rather than runtime application state:
- `bench/cve-zero/samples/`
- `bench/cybench/results/`
- `bench/xbow/results/`
- `scripts/verify-claims.mjs`

Benchmark runners under `scripts/` execute domain-specific evaluations; artifacts are stored as JSON under `bench/`. This is operationally separate from live missions, but architecturally important because it verifies tool counts, benchmark outcomes, and published claims from repository-contained evidence.

Main entry points: [`src/mission/index.ts`](https://github.com/elder-plinius/t3mp3st/blob/main/src/mission/index.ts) (Mission service), [`src/orchestration/orchestrator.ts`](https://github.com/elder-plinius/t3mp3st/blob/main/src/orchestration/orchestrator.ts) (Orchestrator), [`src/arsenal/adapter-tools.ts`](https://github.com/elder-plinius/t3mp3st/blob/main/src/arsenal/adapter-tools.ts) (Arsenal adapters), [`src/evidence/index.ts`](https://github.com/elder-plinius/t3mp3st/blob/main/src/evidence/index.ts) (Evidence store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_cli["CLI<br/>Node entry point<br/>[cli.ts]"]
  node_warroom["War Room HTTP server<br/>Local API<br/>[server.ts]"]
  node_mcp["MCP server<br/>MCP interface<br/>[mcp-server.ts]"]
end

subgraph group_mission["Mission Control"]
  node_mission["Mission service<br/>Mission lifecycle<br/>[index.ts]"]
  node_orchestrator["Orchestrator<br/>Task coordinator<br/>[orchestrator.ts]"]
  node_context["Context packs<br/>Shared task context<br/>[context-pack.ts]"]
  node_adjudication["Mission adjudication<br/>Outcome evaluator<br/>[adjudicate.ts]"]
  node_model_boundary{{"LLM &amp; local-agent gateway<br/>Provider dispatch<br/>[index.ts]"}}
  node_providers(("Models &amp; local agents<br/>External services"))
end

subgraph group_security["Targeting &amp; Execution"]
  node_target["Target model<br/>Target definition<br/>[index.ts]"]
  node_recon["Recon &amp; source analysis<br/>Attack-surface analysis<br/>[attack-graph.ts]"]
  node_arsenal{{"Arsenal adapters<br/>Controlled tool execution<br/>[adapter-tools.ts]"}}
  node_approval["Approval &amp; scope control<br/>Execution guardrail<br/>[approval.ts]"]
  node_tools(("Security tools<br/>External binaries"))
end

subgraph group_assurance["Evidence &amp; Assurance"]
  node_evidence[("Evidence store<br/>Mission artifacts<br/>[index.ts]")]
  node_validation["Evidence validation<br/>Finding verifier<br/>[index.ts]"]
  node_integrations["Bounty integration<br/>External reporting<br/>[bounty.ts]"]
end

subgraph group_benchmark["Reproducibility"]
  node_benchmark_data[("Benchmark corpora &amp; results<br/>Committed evaluation artifacts")]
  node_claim_verifier["Claims verifier<br/>Reproducibility script<br/>[verify-claims.mjs]"]
end

node_cli -->|"starts missions"| node_mission
node_warroom -->|"local API"| node_mission
node_mcp -->|"security_recon requests"| node_mission
node_mission -->|"plans and coordinates"| node_orchestrator
node_orchestrator -->|"builds"| node_context
node_orchestrator -->|"dispatches agents"| node_model_boundary
node_model_boundary -->|"selects provider or CLI"| node_providers
node_mission -->|"defines target intent"| node_target
node_target -->|"drives analysis"| node_recon
node_recon -->|"attack surface"| node_context
node_orchestrator -->|"requests actions"| node_arsenal
node_approval -->|"authorizes scoped execution"| node_arsenal
node_arsenal -->|"executes via adapters"| node_tools
node_arsenal -->|"tool artifacts"| node_evidence
node_evidence -->|"findings and artifacts"| node_validation
node_validation -->|"validated results"| node_adjudication
node_adjudication -->|"mission outcomes"| node_mission
node_evidence -->|"reportable artifacts"| node_integrations
node_benchmark_data -->|"inputs and receipts"| node_claim_verifier

click node_cli "https://github.com/elder-plinius/t3mp3st/blob/main/src/cli.ts"
click node_warroom "https://github.com/elder-plinius/t3mp3st/blob/main/src/server.ts"
click node_mcp "https://github.com/elder-plinius/t3mp3st/blob/main/src/mcp-server.ts"
click node_mission "https://github.com/elder-plinius/t3mp3st/blob/main/src/mission/index.ts"
click node_orchestrator "https://github.com/elder-plinius/t3mp3st/blob/main/src/orchestration/orchestrator.ts"
click node_context "https://github.com/elder-plinius/t3mp3st/blob/main/src/orchestration/context-pack.ts"
click node_adjudication "https://github.com/elder-plinius/t3mp3st/blob/main/src/mission/adjudicate.ts"
click node_model_boundary "https://github.com/elder-plinius/t3mp3st/blob/main/src/llm/index.ts"
click node_target "https://github.com/elder-plinius/t3mp3st/blob/main/src/target/index.ts"
click node_recon "https://github.com/elder-plinius/t3mp3st/blob/main/src/recon/attack-graph.ts"
click node_arsenal "https://github.com/elder-plinius/t3mp3st/blob/main/src/arsenal/adapter-tools.ts"
click node_approval "https://github.com/elder-plinius/t3mp3st/blob/main/src/arsenal/approval.ts"
click node_tools "https://github.com/elder-plinius/t3mp3st/blob/main/tools/Dockerfile"
click node_evidence "https://github.com/elder-plinius/t3mp3st/blob/main/src/evidence/index.ts"
click node_validation "https://github.com/elder-plinius/t3mp3st/blob/main/src/validation/index.ts"
click node_integrations "https://github.com/elder-plinius/t3mp3st/blob/main/src/integrations/bounty.ts"
click node_claim_verifier "https://github.com/elder-plinius/t3mp3st/blob/main/scripts/verify-claims.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_warroom,node_mcp toneBlue
class node_mission,node_orchestrator,node_context,node_adjudication,node_model_boundary,node_providers toneAmber
class node_target,node_recon,node_arsenal,node_approval,node_tools toneMint
class node_evidence,node_validation,node_integrations toneRose
class node_benchmark_data,node_claim_verifier toneIndigo
```

## Components

### Interfaces

- [CLI](https://github.com/elder-plinius/t3mp3st/blob/main/src/cli.ts): Node entry point · `src/cli.ts`
- [War Room HTTP server](https://github.com/elder-plinius/t3mp3st/blob/main/src/server.ts): Local API · `src/server.ts`
- [MCP server](https://github.com/elder-plinius/t3mp3st/blob/main/src/mcp-server.ts): MCP interface · Exposes security_recon to MCP clients. · `src/mcp-server.ts`

### Mission Control

- [Mission service](https://github.com/elder-plinius/t3mp3st/blob/main/src/mission/index.ts): Mission lifecycle · `src/mission/index.ts`
- [Orchestrator](https://github.com/elder-plinius/t3mp3st/blob/main/src/orchestration/orchestrator.ts): Task coordinator · Builds context, chooses operators, dispatches work, and collects outputs. · `src/orchestration/orchestrator.ts`
- [Context packs](https://github.com/elder-plinius/t3mp3st/blob/main/src/orchestration/context-pack.ts): Shared task context · `src/orchestration/context-pack.ts`
- [Mission adjudication](https://github.com/elder-plinius/t3mp3st/blob/main/src/mission/adjudicate.ts): Outcome evaluator · Independently evaluates findings and task outcomes. · `src/mission/adjudicate.ts`
- [LLM & local-agent gateway](https://github.com/elder-plinius/t3mp3st/blob/main/src/llm/index.ts): Provider dispatch · Centralizes cloud models, compatible endpoints, and local coding agents. · `src/llm/index.ts`
- **Models & local agents**: External services · Cloud providers, local endpoints, and agent CLIs.

### Targeting & Execution

- [Target model](https://github.com/elder-plinius/t3mp3st/blob/main/src/target/index.ts): Target definition · `src/target/index.ts`
- [Recon & source analysis](https://github.com/elder-plinius/t3mp3st/blob/main/src/recon/attack-graph.ts): Attack-surface analysis · Builds attack graphs and analyzes white-box source targets. · `src/recon/attack-graph.ts`
- [Arsenal adapters](https://github.com/elder-plinius/t3mp3st/blob/main/src/arsenal/adapter-tools.ts): Controlled tool execution · Catalogs tools, parses output, and mediates agent-requested actions. · `src/arsenal/adapter-tools.ts`
- [Approval & scope control](https://github.com/elder-plinius/t3mp3st/blob/main/src/arsenal/approval.ts): Execution guardrail · Constrains dangerous operations before tool execution. · `src/arsenal/approval.ts`
- [Security tools](https://github.com/elder-plinius/t3mp3st/blob/main/tools/Dockerfile): External binaries · Optional tooling can run in a dedicated container. · `tools/Dockerfile`

### Evidence & Assurance

- [Evidence store](https://github.com/elder-plinius/t3mp3st/blob/main/src/evidence/index.ts): Mission artifacts · Preserves collected artifacts and report workspace material. · `src/evidence/index.ts`
- [Evidence validation](https://github.com/elder-plinius/t3mp3st/blob/main/src/validation/index.ts): Finding verifier · Separates tool-proven findings from model-only assertions. · `src/validation/index.ts`
- [Bounty integration](https://github.com/elder-plinius/t3mp3st/blob/main/src/integrations/bounty.ts): External reporting · `src/integrations/bounty.ts`

### Reproducibility

- **Benchmark corpora & results**: Committed evaluation artifacts · Samples, oracle data, and JSON run receipts.
- [Claims verifier](https://github.com/elder-plinius/t3mp3st/blob/main/scripts/verify-claims.mjs): Reproducibility script · Recomputes benchmark claims from repository evidence. · `scripts/verify-claims.mjs`

## Connections

- CLI → Mission service: starts missions
- War Room HTTP server → Mission service: local API
- MCP server → Mission service: security_recon requests
- Mission service → Orchestrator: plans and coordinates
- Orchestrator → Context packs: builds
- Orchestrator → LLM & local-agent gateway: dispatches agents
- LLM & local-agent gateway → Models & local agents: selects provider or CLI
- Mission service → Target model: defines target intent
- Target model → Recon & source analysis: drives analysis
- Recon & source analysis → Context packs: attack surface
- Orchestrator → Arsenal adapters: requests actions
- Approval & scope control → Arsenal adapters: authorizes scoped execution
- Arsenal adapters → Security tools: executes via adapters
- Arsenal adapters → Evidence store: tool artifacts
- Evidence store → Evidence validation: findings and artifacts
- Evidence validation → Mission adjudication: validated results
- Mission adjudication → Mission service: mission outcomes
- Evidence store → Bounty integration: reportable artifacts
- Benchmark corpora & results → Claims verifier: inputs and receipts