Joseph Magly
0c35a833b9
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
154 lines
4.0 KiB
Markdown
154 lines
4.0 KiB
Markdown
# 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 |
|