docs: add usage and developer documentation
Add user and developer documentation plus Pagenary docsite publishing support. Includes Getting Started, Developer Guide, API and MCP references, Pagenary tenant metadata, npm scripts for sync/build/check/serve, and validation coverage for the generated docsite. Closes #102
This commit is contained in:
1 parent
7b1d12a07c
commit
0c35a833b9
39 files changed
+4920
-2
No files matched your search
@@ -0,0 +1,228 @@
|
||||
# T3MP3ST API Reference
|
||||
|
||||
The API server is implemented in `src/server.ts`.
|
||||
|
||||
Default base URL:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:3333
|
||||
```
|
||||
|
||||
Start it with:
|
||||
|
||||
```bash
|
||||
npm run server
|
||||
```
|
||||
|
||||
The War Room UI is served from `/ui/`; `/` redirects there.
|
||||
|
||||
## Security Model
|
||||
|
||||
The API is a local operator surface, not a multi-user internet service.
|
||||
|
||||
- Default host: `127.0.0.1`
|
||||
- Default port: `3333`
|
||||
- Override port with `T3MP3ST_PORT`
|
||||
- Override bind host with `T3MP3ST_HOST`
|
||||
- State-changing requests are guarded against foreign browser origins
|
||||
- Loopback binds reject non-loopback Host headers to reduce DNS-rebinding risk
|
||||
- Active or networked tool use should have a scope/authorization receipt
|
||||
|
||||
Do not expose the server on a public interface without adding your own authentication and network controls.
|
||||
|
||||
## Health And Runtime
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/health` | Basic server health |
|
||||
| `GET` | `/api/health` | API health alias |
|
||||
| `GET` | `/api/preflight` | Local preflight and readiness summary |
|
||||
| `GET` | `/api/events` | Server-sent event stream |
|
||||
| `GET` | `/api/mission-context/latest` | Latest mission context snapshot |
|
||||
| `GET` | `/api/net/proxy` | Current outbound SOCKS5 proxy configuration, with credentials redacted |
|
||||
| `POST` | `/api/net/proxy` | Set or clear outbound SOCKS5 proxy URL |
|
||||
| `GET` | `/api/net/ip` | Check observed outbound IP path |
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:3333/api/health
|
||||
```
|
||||
|
||||
## Arsenal And Approvals
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/arsenal/catalog` | Tool catalog and adapter metadata |
|
||||
| `GET` | `/api/arsenal/status` | Installed/readiness status for arsenal tools |
|
||||
| `POST` | `/api/arsenal/plan` | Plan tool activation for a mission family |
|
||||
| `GET` | `/api/arsenal/activation` | Activation guidance |
|
||||
| `GET` | `/api/arsenal/approvals` | Arsenal approval state |
|
||||
| `GET` | `/api/approvals` | Approval requests |
|
||||
| `POST` | `/api/approvals/request` | Create an approval request |
|
||||
| `POST` | `/api/approvals/:id/approve` | Approve a request |
|
||||
| `POST` | `/api/approvals/:id/reject` | Reject a request |
|
||||
| `POST` | `/api/approvals/authorize-target` | Record target authorization |
|
||||
| `GET` | `/api/tools` | Built-in tool metadata |
|
||||
| `POST` | `/api/tools/execute` | Execute a named tool |
|
||||
| `POST` | `/api/tools/recon` | Run recon helper flow |
|
||||
|
||||
Tool requests should be scoped to authorized targets. External binary availability comes from the local workstation, not from package installation alone.
|
||||
|
||||
## Mission Planning And Execution
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `POST` | `/api/mission/start` | Start a mission |
|
||||
| `POST` | `/api/mission/stop` | Stop the current mission |
|
||||
| `POST` | `/api/mission/pause` | Pause the current mission |
|
||||
| `POST` | `/api/mission/resume` | Resume the current mission |
|
||||
| `GET` | `/api/mission/status` | Current mission status |
|
||||
| `GET` | `/api/mission/report` | Current mission report |
|
||||
| `GET` | `/api/mission/:id/report` | Report for a mission ID |
|
||||
| `GET` | `/api/mission/findings` | Findings for the active mission |
|
||||
| `POST` | `/api/mission-drafts` | Create a mission draft |
|
||||
| `GET` | `/api/mission-drafts` | List mission drafts |
|
||||
| `GET` | `/api/mission-drafts/:id` | Read a mission draft |
|
||||
| `PATCH` | `/api/mission-drafts/:id` | Update a mission draft |
|
||||
| `DELETE` | `/api/mission-drafts/:id` | Delete a mission draft |
|
||||
| `POST` | `/api/mission-bundles` | Create a mission bundle |
|
||||
| `GET` | `/api/mission-bundles/:missionId` | Read mission bundle |
|
||||
| `POST` | `/api/mission-gate` | Evaluate mission readiness gate |
|
||||
|
||||
## General Planner And Admiral
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `POST` | `/api/general/plan` | Generate an Op General plan |
|
||||
| `GET` | `/api/general/plan` | Read current plan |
|
||||
| `POST` | `/api/general/execute` | Execute plan steps |
|
||||
| `POST` | `/api/general/auto` | Plan and execute automatically |
|
||||
| `GET` | `/api/general/sitreps` | Read sitrep history |
|
||||
| `POST` | `/api/general/sitrep` | Create a sitrep |
|
||||
| `POST` | `/api/general/assess` | Run strategic assessment |
|
||||
| `POST` | `/api/admiral/converse` | Converse with Op Admiral |
|
||||
| `POST` | `/api/admiral/suggest` | Request mission suggestions |
|
||||
| `POST` | `/api/admiral/launch` | Launch from Admiral flow |
|
||||
|
||||
## Evidence, Findings, And Retests
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/evidence` | List evidence |
|
||||
| `POST` | `/api/evidence` | Add evidence |
|
||||
| `GET` | `/api/evidence-graph` | Evidence graph |
|
||||
| `GET` | `/api/findings` | List findings |
|
||||
| `POST` | `/api/findings` | Create finding |
|
||||
| `PATCH` | `/api/findings/:id` | Update finding |
|
||||
| `POST` | `/api/findings/:id/retest` | Queue or run retest |
|
||||
| `GET` | `/api/retests` | List retests |
|
||||
| `PATCH` | `/api/retests/:id` | Update retest |
|
||||
| `GET` | `/api/repro-packs` | List reproduction packs |
|
||||
| `POST` | `/api/repro-packs` | Create reproduction pack |
|
||||
|
||||
Evidence and finding payloads must avoid raw secrets. Use redaction helpers in `src/redact.ts` and `src/evidence/` when adding new paths.
|
||||
|
||||
## Hypotheses And Work Orders
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/hypotheses` | List hypotheses |
|
||||
| `POST` | `/api/hypotheses` | Create hypothesis |
|
||||
| `PATCH` | `/api/hypotheses/:id` | Update hypothesis |
|
||||
| `POST` | `/api/hypotheses/:id/promote` | Promote hypothesis |
|
||||
| `POST` | `/api/hypotheses/:id/decompose` | Decompose into work orders |
|
||||
| `POST` | `/api/hypotheses/:id/work-orders` | Work-order decomposition alias |
|
||||
| `GET` | `/api/work-orders` | List work orders |
|
||||
| `POST` | `/api/work-orders` | Create work order |
|
||||
| `PATCH` | `/api/work-orders/:id` | Update work order |
|
||||
| `POST` | `/api/work-orders/:id/complete` | Complete work order |
|
||||
|
||||
## Resources And Operator Context
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/workflow-presets` | Workflow presets |
|
||||
| `GET` | `/api/resource-packs` | Resource packs |
|
||||
| `GET` | `/api/resource-packs/:id` | Resource pack details |
|
||||
| `POST` | `/api/resource-packs/search` | Search resource packs |
|
||||
| `GET` | `/api/agent-prompt-packs` | Agent prompt packs |
|
||||
| `GET` | `/api/agent-prompt-packs/:id` | Prompt pack details |
|
||||
| `GET` | `/api/operator-runbooks` | Operator runbooks |
|
||||
| `GET` | `/api/operator-runbooks/:family` | Runbook for a family |
|
||||
| `GET` | `/api/forefront-radar` | Forefront pressure lanes |
|
||||
| `GET` | `/api/forefront-radar/:id` | Forefront lane details |
|
||||
| `GET` | `/api/agent-context/:family` | Combined agent context |
|
||||
| `GET` | `/api/operator-doctrine` | Operator doctrine |
|
||||
| `GET` | `/api/ai-redteam/playbook` | AI red-team playbook |
|
||||
|
||||
## LLMs, Local Agents, And Operators
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/llm/status` | LLM status |
|
||||
| `POST` | `/api/llm/chat` | Send a chat request |
|
||||
| `POST` | `/api/llm/local` | Test or use a local OpenAI-compatible model endpoint |
|
||||
| `POST` | `/api/models` | Resolve model list |
|
||||
| `GET` | `/api/codex/status` | Codex local status |
|
||||
| `POST` | `/api/codex/probe` | Probe Codex integration |
|
||||
| `GET` | `/api/agents/local/detect` | Detect local coding agents |
|
||||
| `POST` | `/api/agents/local/connect` | Connect local agent |
|
||||
| `POST` | `/api/agents/local/ping` | Ping local agent |
|
||||
| `POST` | `/api/agents/local/dispatch` | Dispatch to local agent |
|
||||
| `POST` | `/api/agents/local/disconnect` | Disconnect local agent |
|
||||
| `GET` | `/api/agents/local/status` | Local agent status |
|
||||
| `GET` | `/api/operators/prompts` | Operator prompt overrides |
|
||||
| `POST` | `/api/operators/prompt` | Set operator prompt override |
|
||||
| `POST` | `/api/operators/prompt/reset` | Reset operator prompt override |
|
||||
| `POST` | `/api/operators/spawn` | Spawn operator |
|
||||
| `POST` | `/api/operators/terminate` | Terminate operator |
|
||||
| `GET` | `/api/operators/list` | List operators |
|
||||
| `POST` | `/api/operators/:id/task` | Assign operator task |
|
||||
|
||||
## White-Box And Attack Graph
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `POST` | `/api/whitebox/analyze` | Analyze a local repository path |
|
||||
| `POST` | `/api/attack-graph` | Build or update attack graph |
|
||||
| `POST` | `/api/attack-graph/ingest` | Ingest graph material |
|
||||
|
||||
Repository paths are contained by resolver logic before analysis. Keep that containment intact when extending white-box features.
|
||||
|
||||
## Learning And Improvement
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/watch-loop/status` | Watch Loop status |
|
||||
| `POST` | `/api/watch-loop/run` | Run Watch Loop pulse |
|
||||
| `POST` | `/api/self-heal/run` | Run self-heal flow |
|
||||
| `GET` | `/api/pressure-paths` | Pressure path list |
|
||||
| `POST` | `/api/pressure-paths` | Create pressure path |
|
||||
| `POST` | `/api/pressure-paths/canary` | Canary pressure path |
|
||||
| `POST` | `/api/pressure-paths/duel` | Duel pressure path |
|
||||
| `POST` | `/api/pressure-paths/mutate` | Mutate pressure path |
|
||||
| `POST` | `/api/pressure-paths/chains` | Chain pressure paths |
|
||||
| `POST` | `/api/route-preview` | Preview route |
|
||||
| `GET` | `/api/routes/:routeId/scorecards` | Route scorecards |
|
||||
| `POST` | `/api/improvement/proposals` | Create improvement proposal |
|
||||
| `GET` | `/api/improvement/proposals` | List improvement proposals |
|
||||
| `POST` | `/api/promotion/evaluate` | Evaluate promotion |
|
||||
| `GET` | `/api/learning/status` | Learning status |
|
||||
| `POST` | `/api/learning/run-review` | Run learning review |
|
||||
| `GET` | `/api/memory/capsule` | Memory capsule |
|
||||
| `GET` | `/api/memory/proposals` | List memory proposals |
|
||||
| `POST` | `/api/memory/proposals` | Create memory proposal |
|
||||
| `POST` | `/api/memory/proposals/:id/accept` | Accept memory proposal |
|
||||
| `POST` | `/api/memory/proposals/:id/reject` | Reject memory proposal |
|
||||
| `GET` | `/api/selfimprove/ledger` | Self-improvement ledger |
|
||||
|
||||
## Bounty Helpers
|
||||
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/bounty/platforms` | Supported bounty platforms |
|
||||
| `GET` | `/api/bounty/programs/:platform` | Programs for a platform |
|
||||
| `GET` | `/api/bounty/credentials` | Credential readiness |
|
||||
| `POST` | `/api/bounty/format` | Format a report |
|
||||
| `POST` | `/api/bounty/submit` | Submit through configured platform integration |
|
||||
@@ -0,0 +1,166 @@
|
||||
# T3MP3ST Developer Guide
|
||||
|
||||
This guide maps the codebase to the public surfaces documented for operators and integrators.
|
||||
|
||||
## Local Development
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
npm test
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Useful focused checks:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run doctor
|
||||
npm run test:no-phantom-tools
|
||||
npm run arsenal:smoke
|
||||
npm run smoke
|
||||
```
|
||||
|
||||
Run the HTTP API and UI during development:
|
||||
|
||||
```bash
|
||||
npm run server
|
||||
```
|
||||
|
||||
Run the CLI from TypeScript:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Run the built CLI:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
## Pagenary Docsite
|
||||
|
||||
The publishable documentation site is generated with Pagenary from the Markdown docs in this repository.
|
||||
|
||||
```bash
|
||||
npm run docs:sync # regenerate docsite/t3mp3st-docs from docs/*.md
|
||||
npm run docs:build # build dist/t3mp3st-docs
|
||||
npm run docs:check # build and verify Pagenary publishing artifacts
|
||||
npm run docs:serve # build and serve http://127.0.0.1:5173/t3mp3st-docs/
|
||||
```
|
||||
|
||||
Set `PAGENARY_SITE_URL` before `docs:sync` or `docs:build` when publishing somewhere other than the default GitHub Pages-style URL.
|
||||
|
||||
## Source Map
|
||||
|
||||
| Path | Responsibility |
|
||||
|---|---|
|
||||
| `src/cli.ts` | Commander-based CLI: interactive mode, setup, status, test, and model listing |
|
||||
| `src/server.ts` | Express API server and static War Room UI host |
|
||||
| `src/index.ts` | Public SDK exports, `TempestCommand`, factory helpers, and composed `Tempest` instance |
|
||||
| `src/types/index.ts` | Shared TypeScript contracts for LLMs, operators, targets, findings, tools, missions, and reports |
|
||||
| `src/config/index.ts` | Persistent configuration, provider defaults, API key helpers, and model registry |
|
||||
| `src/llm/index.ts` | LLM provider adapters and tool-call normalization |
|
||||
| `src/net/proxy.ts` | Optional outbound SOCKS5 proxy configuration for test/attack traffic |
|
||||
| `src/arsenal/` | Built-in tools, external adapter catalog, approval gates, parser helpers, and post-exploitation gatekeeping |
|
||||
| `src/mission/` | Mission, rules-of-engagement, task queue, and adjudication logic |
|
||||
| `src/evidence/` | Evidence vault, findings, redaction, integrity checks, and retest support |
|
||||
| `src/general/` | Autonomous Op General planning and execution orchestration |
|
||||
| `src/resources/` | Prompt packs, runbooks, resource packs, workflow presets, and playbooks |
|
||||
| `src/mcp-server.ts` | MCP stdio server exposing `security_recon` |
|
||||
| `scripts/` | Verification, benchmark, smoke, update, disclosure, and release helper scripts |
|
||||
| `docs/` | Operator, developer, benchmark, release, and provenance documentation |
|
||||
|
||||
## Public SDK
|
||||
|
||||
The package exports the main factory functions and core classes from `src/index.ts`.
|
||||
|
||||
```ts
|
||||
import { createTempest, createTestTempest } from 't3mp3st';
|
||||
|
||||
const tempest = createTempest({
|
||||
name: 'Authorized Lab Run',
|
||||
llm: {
|
||||
provider: 'mock',
|
||||
model: 'mock-model',
|
||||
maxTokens: 4096,
|
||||
temperature: 0.7,
|
||||
},
|
||||
opsec: {
|
||||
level: 'covert',
|
||||
maxDetectionEvents: 3,
|
||||
cleanupOnComplete: true,
|
||||
},
|
||||
});
|
||||
|
||||
tempest.command.start();
|
||||
```
|
||||
|
||||
For tests, prefer `createTestTempest()` unless the test specifically needs a provider adapter.
|
||||
|
||||
## HTTP Server
|
||||
|
||||
`src/server.ts` hosts the War Room at `/ui/` and exposes JSON endpoints under `/api/`. It binds to `127.0.0.1:3333` by default. The server includes a localhost CORS/origin guard and a loopback Host-header guard because many endpoints can dispatch local tools.
|
||||
|
||||
See [API Reference](API_REFERENCE.md) for route groups.
|
||||
|
||||
Provider state comes from `src/config/index.ts`. Current provider families include hosted OpenAI-compatible APIs, direct Anthropic/OpenAI-style APIs, DeepSeek, LiteLLM proxy, local OpenAI-compatible servers, and connected local coding-agent CLIs.
|
||||
|
||||
When adding an endpoint:
|
||||
|
||||
1. Keep state-changing methods behind the existing origin guard.
|
||||
2. Validate request bodies before using them in shell, file, or model calls.
|
||||
3. Redact secrets before writing evidence, ledgers, reports, logs, or responses.
|
||||
4. Attach outputs to evidence or status structures instead of returning opaque strings.
|
||||
5. Add a focused test if the endpoint changes security, persistence, routing, or evidence behavior.
|
||||
|
||||
## Arsenal Tools
|
||||
|
||||
Built-in tools live in `src/arsenal/index.ts`; external adapter metadata lives in `src/arsenal/catalog.ts`.
|
||||
|
||||
Tool additions should define:
|
||||
|
||||
- Name, description, parameters, and risk tier
|
||||
- Scope behavior for active or networked operations
|
||||
- Evidence kind and output shape
|
||||
- Availability or install hint for external binaries
|
||||
- Tests for refusal, parsing, redaction, or scope behavior when applicable
|
||||
|
||||
Dangerous tools must not be exposed through generic command execution. Add narrow adapters with explicit approvals and receipt gates.
|
||||
|
||||
## MCP Server
|
||||
|
||||
`npm run mcp` starts the stdio MCP server from `src/mcp-server.ts`. It currently exposes one tool, `security_recon`, for DNS and nmap reconnaissance against a hostname or IP. See [MCP Guide](MCP_GUIDE.md).
|
||||
|
||||
## Documentation Sync
|
||||
|
||||
Use code-to-docs review when public behavior changes:
|
||||
|
||||
```bash
|
||||
aiwg discover "doc-sync code2doc"
|
||||
aiwg show skill doc-sync
|
||||
```
|
||||
|
||||
For this repository, the highest-value docs sync scope is:
|
||||
|
||||
```text
|
||||
README.md, docs/, package.json, src/cli.ts, src/server.ts, src/index.ts, src/mcp-server.ts, src/arsenal/
|
||||
```
|
||||
|
||||
Keep claims tied to source, scripts, tests, or committed benchmark artifacts. If a headline metric changes, run `npm run verify-claims` and update the relevant benchmark documentation in the same change.
|
||||
|
||||
## Release Gate
|
||||
|
||||
Before a release or broad documentation claim change, run:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm test
|
||||
npm run doctor
|
||||
npm run verify-claims
|
||||
npm run arsenal:smoke
|
||||
```
|
||||
|
||||
If a check cannot run in your environment, document the reason in the PR using [Contribution Receipts](CONTRIBUTION_RECEIPTS.md).
|
||||
@@ -0,0 +1,153 @@
|
||||
# Getting Started With T3MP3ST
|
||||
|
||||
T3MP3ST is a local offensive-security command center for authorized testing. It gives an AI coding agent or LLM-backed operator a UI, API, evidence store, mission model, and tool arsenal. Use it only on systems you own or have explicit written permission to test.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Node.js 18 or newer
|
||||
- npm
|
||||
- git, if you want to update from upstream or contribute
|
||||
- Optional local model runtime: Ollama, LM Studio, vLLM, or another OpenAI-compatible local server
|
||||
- Optional security tools for deeper arsenal coverage; see [Arsenal Activation Plan](ARSENAL_ACTIVATION_PLAN.md)
|
||||
|
||||
## Install
|
||||
|
||||
From a clone:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/elder-plinius/T3MP3ST.git
|
||||
cd T3MP3ST
|
||||
npm install
|
||||
```
|
||||
|
||||
From an existing checkout:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
## Configure A Model
|
||||
|
||||
You can run with a hosted provider key or a local model.
|
||||
|
||||
Interactive setup:
|
||||
|
||||
```bash
|
||||
npm run setup
|
||||
```
|
||||
|
||||
Hosted provider environment variables are supported:
|
||||
|
||||
```bash
|
||||
export OPENROUTER_API_KEY=...
|
||||
export VENICE_API_KEY=...
|
||||
export ANTHROPIC_API_KEY=...
|
||||
export OPENAI_API_KEY=...
|
||||
export DEEPSEEK_API_KEY=...
|
||||
export LITELLM_BASE_URL=http://localhost:4000/v1
|
||||
export LITELLM_API_KEY=... # only if your LiteLLM proxy requires one
|
||||
```
|
||||
|
||||
Local/offline example with Ollama:
|
||||
|
||||
```bash
|
||||
ollama serve
|
||||
ollama pull llama3
|
||||
export TEMPEST_LOCAL_BASE_URL=http://localhost:11434/api
|
||||
export TEMPEST_LOCAL_MODEL=llama3
|
||||
export TEMPEST_LOCAL_API_KEY=... # only if your local server requires one
|
||||
```
|
||||
|
||||
Check current configuration:
|
||||
|
||||
```bash
|
||||
npx t3mp3st status
|
||||
npx t3mp3st models
|
||||
npx t3mp3st test
|
||||
```
|
||||
|
||||
## Start The War Room
|
||||
|
||||
```bash
|
||||
npm run server
|
||||
```
|
||||
|
||||
Open:
|
||||
|
||||
```text
|
||||
http://127.0.0.1:3333/ui/
|
||||
```
|
||||
|
||||
The server binds to `127.0.0.1` by default. Do not expose it to a network unless you understand the command-execution and browser-origin risk. If you intentionally bind elsewhere with `T3MP3ST_HOST`, put it behind your own access control.
|
||||
|
||||
If you need outbound test traffic to use a SOCKS5 proxy, configure it with `TEMPEST_PROXY_URL` or through the War Room settings. The expected form is:
|
||||
|
||||
```bash
|
||||
export TEMPEST_PROXY_URL=socks5://127.0.0.1:9050
|
||||
```
|
||||
|
||||
## First Safe Run
|
||||
|
||||
Use a target you control, a local lab, or a CTF service.
|
||||
|
||||
1. Open the War Room.
|
||||
2. Run the preflight view and confirm the API is healthy.
|
||||
3. Sync or inspect arsenal status so missing tools are visible.
|
||||
4. Define the target and rules of engagement before any active probing.
|
||||
5. Start with a passive or local-safe plan.
|
||||
6. Approve only the active or networked operations that are inside scope.
|
||||
7. Save evidence before promoting a finding.
|
||||
8. Retest before reporting.
|
||||
|
||||
If you are only evaluating the app, use the built-in safe checks:
|
||||
|
||||
```bash
|
||||
npm run doctor
|
||||
npm run field:drill
|
||||
npm run arsenal:smoke
|
||||
npm run prompt:audit
|
||||
```
|
||||
|
||||
## CLI Basics
|
||||
|
||||
```bash
|
||||
npx t3mp3st # interactive mode
|
||||
npx t3mp3st setup # setup wizard
|
||||
npx t3mp3st status # config status
|
||||
npx t3mp3st models # available models for the selected provider
|
||||
npx t3mp3st test # test the selected LLM connection
|
||||
```
|
||||
|
||||
The interactive CLI can start an operation, spawn operators, add targets, create missions, chat with the configured model, and generate a report from collected findings.
|
||||
|
||||
## Updating
|
||||
|
||||
Preview an update:
|
||||
|
||||
```bash
|
||||
npm run update:dry
|
||||
```
|
||||
|
||||
Interactive update from upstream:
|
||||
|
||||
```bash
|
||||
npm run update
|
||||
```
|
||||
|
||||
Hard reset to upstream is opt-in:
|
||||
|
||||
```bash
|
||||
npm run update:hard
|
||||
```
|
||||
|
||||
The updater protects local secrets and run artifacts listed in `scripts/update-protected.txt`.
|
||||
|
||||
## Common Problems
|
||||
|
||||
| Symptom | Check |
|
||||
|---|---|
|
||||
| UI does not load | Confirm `npm run server` is still running and open `http://127.0.0.1:3333/ui/` |
|
||||
| LLM calls fail | Run `npx t3mp3st status` and `npx t3mp3st test`; check provider key or local model URL |
|
||||
| Arsenal tools show missing | Install the relevant tools from [Arsenal Activation Plan](ARSENAL_ACTIVATION_PLAN.md) |
|
||||
| Active tool call is refused | Confirm the target is authorized and inside the active scope receipt |
|
||||
| Update wants to change local files | Run `npm run update:dry` first and inspect the plan |
|
||||
@@ -0,0 +1,65 @@
|
||||
# MCP Guide
|
||||
|
||||
T3MP3ST includes a Model Context Protocol stdio server in `src/mcp-server.ts`.
|
||||
|
||||
## Start The Server
|
||||
|
||||
From a development checkout:
|
||||
|
||||
```bash
|
||||
npm run mcp
|
||||
```
|
||||
|
||||
From a built package:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm run mcp:prod
|
||||
```
|
||||
|
||||
## Exposed Tool
|
||||
|
||||
| Tool | Purpose |
|
||||
|---|---|
|
||||
| `security_recon` | Runs quick DNS and nmap reconnaissance against a hostname or IP |
|
||||
|
||||
Input schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"target": "example.com",
|
||||
"scan_type": "quick"
|
||||
}
|
||||
```
|
||||
|
||||
`scan_type` may be `quick`, `standard`, `full`, or `stealth`.
|
||||
|
||||
## Safety And Validation
|
||||
|
||||
The MCP server validates the target before it reaches a subprocess:
|
||||
|
||||
- Target must be a hostname or IP-like value matching `[A-Za-z0-9._:-]`
|
||||
- Shell metacharacters, spaces, pipes, and command separators are rejected
|
||||
- Subprocesses use `execFile`, not a shell
|
||||
- Executable names are restricted to an allowlist
|
||||
|
||||
The current `security_recon` implementation calls:
|
||||
|
||||
- `dig +short <target> ANY`
|
||||
- `nmap` with scan arguments selected by `scan_type`
|
||||
|
||||
Only use this tool against systems inside your authorized scope.
|
||||
|
||||
## Example MCP Tool Call
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "security_recon",
|
||||
"arguments": {
|
||||
"target": "scanme.nmap.org",
|
||||
"scan_type": "quick"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response is JSON text containing DNS records, nmap output, command summaries, and suggested next steps.
|
||||
@@ -0,0 +1,50 @@
|
||||
# T3MP3ST Documentation
|
||||
|
||||
Start here when you want to install, run, integrate, or contribute to T3MP3ST.
|
||||
|
||||
## For Operators
|
||||
|
||||
| Doc | Use it for |
|
||||
|---|---|
|
||||
| [Getting Started](GETTING_STARTED.md) | Install, first launch, first safe mission, updates, and troubleshooting |
|
||||
| [Scope and Authorization](SCOPE_AND_AUTHORIZATION.md) | Rules of engagement, target receipts, and evidence requirements |
|
||||
| [Target Headers](TARGET_HEADERS.md) | Supplying auth headers for an explicitly authorized target origin |
|
||||
| [Arsenal Activation Plan](ARSENAL_ACTIVATION_PLAN.md) | Installing optional external tools and understanding adapter readiness |
|
||||
| [Team Preview](TEAM_PREVIEW.md) | Ten-minute UI walkthrough for preview builds |
|
||||
|
||||
## For Developers
|
||||
|
||||
| Doc | Use it for |
|
||||
|---|---|
|
||||
| [Developer Guide](DEVELOPER_GUIDE.md) | Architecture, local development, scripts, extension points, and release checks |
|
||||
| [API Reference](API_REFERENCE.md) | HTTP server endpoints grouped by workflow |
|
||||
| [MCP Guide](MCP_GUIDE.md) | Model Context Protocol setup and the `security_recon` tool |
|
||||
| [Contribution Receipts](CONTRIBUTION_RECEIPTS.md) | Evidence template for PRs and claim changes |
|
||||
| [Pull Request Delivery](PULL_REQUEST_DELIVERY.md) | Contributor and maintainer PR checklist |
|
||||
|
||||
Preview this documentation as a Pagenary site:
|
||||
|
||||
```bash
|
||||
npm run docs:serve
|
||||
```
|
||||
|
||||
## Benchmarks And Provenance
|
||||
|
||||
| Doc | Use it for |
|
||||
|---|---|
|
||||
| [Verified Provenance](VERIFIED_PROVENANCE.md) | How T3MP3ST ties findings to tool evidence |
|
||||
| [XBOW Baseline](XBOW_BASELINE.md) | XBEN benchmark notes |
|
||||
| [Cybench](CYBENCH.md) | Cybench benchmark notes |
|
||||
| [Wall Forensics](WALL_FORENSICS.md) | Per-challenge misses and benchmark analysis |
|
||||
| [Integrity Ledger](INTEGRITY_LEDGER.md) | Contamination audit and retractions |
|
||||
| [Obsidivm](OBSIDIVM.md) | Local web range and evaluation notes |
|
||||
| [Cognitive Architecture](COGNITIVE_ARCHITECTURE.md) | Prompt and reasoning architecture boundaries |
|
||||
| [AI Red-Team Techniques](AI_REDTEAM_TECHNIQUES.md) | Defensive taxonomy and technique map |
|
||||
|
||||
## Release And Maintenance
|
||||
|
||||
| Doc | Use it for |
|
||||
|---|---|
|
||||
| [Install Matrix](INSTALL_MATRIX.md) | OS readiness notes |
|
||||
| [Release Checklist](RELEASE_CHECKLIST.md) | Release gates |
|
||||
| [Changelog](CHANGELOG.md) | Project change history |
|
||||
Reference in new issue
Block a user