# Theseus Technology Stack

> Attack path graph for penetration testing — AI-powered external memory for security assessments.

**Version**: 0.2.1 | **Rust Edition**: 2021 | **License**: MIT

---

## Backend

### Runtime & Async

| Crate | Version | Locked | Features | Role |
|-------|---------|--------|----------|------|
| `tokio` | `1` | 1.52.3 | `full` | Async runtime — drives HTTP server, WebSocket broadcast, file I/O |
| `tracing` | `0.1` | 0.1.44 | — | Structured logging facade |
| `tracing-subscriber` | `0.3` | 0.3.23 | `env-filter` | Log output with `RUST_LOG`-based filtering |

### Web Framework

| Crate | Version | Locked | Features | Role |
|-------|---------|--------|----------|------|
| `axum` | `0.7` | 0.7.9 | `ws`, `multipart` | HTTP + WebSocket server; multipart for evidence file uploads |
| `tower-http` | `0.5` | 0.5.2 | `cors`, `trace`, `fs` | CORS (permissive), request tracing, static file serving (`ServeDir`) |

**Why axum 0.7?** Tower-native composable middleware, first-class WebSocket support via `ws` feature, and `extract::Multipart` for evidence uploads — all without pulling in a heavy framework. The `:param` route syntax (not `{param}`) is a project convention; `{param}` silently 404s.

### Database

| Crate | Version | Locked | Features | Role |
|-------|---------|--------|----------|------|
| `rusqlite` | `0.31` | 0.31.0 | `bundled` | Embedded SQLite — zero external DB dependency, single file persistence |

**Why `bundled`?** Compiles SQLite from source, eliminating system library dependencies. Critical for a pentest tool that may run on arbitrary machines (VMs, jump boxes, WSL) where `libsqlite3-dev` isn't installed. WAL mode + foreign keys enabled at startup.

### Serialization & Data

| Crate | Version | Locked | Features | Role |
|-------|---------|--------|----------|------|
| `serde` | `1` | 1.0.228 | `derive` | Serialize/deserialize all DTOs, enums, API payloads |
| `serde_json` | `1` | 1.0.150 | — | JSON encoding for API responses, node properties, import/export |
| `uuid` | `1` | 1.23.1 | `v4`, `serde` | All entity IDs are UUIDv4; `serde` feature enables direct JSON serialization |
| `chrono` | `0.4` | 0.4.44 | `serde` | Timestamps (RFC3339 in SQLite TEXT), CST timezone for daily reports |
| `toml` | `0.8` | 0.8.23 | — | Parse `theseus.toml` config file (AI API keys, etc.) |

### HTTP Client

| Crate | Version | Locked | Features | Role |
|-------|---------|--------|----------|------|
| `reqwest` | `0.12` | 0.12.28 | `json`, `multipart` | CLI HTTP client for API calls + multipart uploads from CLI |

### CLI

| Crate | Version | Locked | Features | Role |
|-------|---------|--------|----------|------|
| `clap` | `4` | 4.6.1 | `derive` | Command-line argument parsing — subcommand derive macros for `serve`, `project`, `node`, `edge`, `credential`, `search`, `import`, `tell`, `ask` |

---

## Frontend

### Libraries (no build step — vanilla JS)

| Library | Version | Source | Role |
|---------|---------|--------|------|
| **Cytoscape.js** | — | `static/cytoscape.min.js` (local) | Core graph rendering — nodes, edges, layouts, interactions |
| **cytoscape-dagre** | — | `static/cytoscape-dagre.js` (local) | Dagre layout plugin for hierarchical DAG rendering |
| **dagre** | — | `static/dagre.min.js` (local) | Graph layout engine (Sugiyama-style) |
| **cytoscape-elk** | — | `static/cytoscape-elk.js` (local) | ELK layout plugin for alternative layout strategies |
| **ELK.js** | — | `static/elk.bundled.js` (local) | Eclipse Layout Kernel — advanced graph layout |
| **marked.js** | latest | CDN (`cdn.jsdelivr.net`) | Markdown → HTML rendering in node content panels |
| **highlight.js** | `11.9.0` | CDN (`cdnjs.cloudflare.com`) | Code syntax highlighting (atom-one-dark theme) |

**Why local files for graph libs?** A pentest tool may run on air-gapped networks. Cytoscape.js + layout plugins are vendored locally. Markdown/highlight libs are CDN-loaded (acceptable tradeoff — content rendering isn't critical path).

### Custom Modules (14 vanilla JS files)

| Module | Role |
|--------|------|
| `state.js` | Global app state (current project, selected node, etc.) |
| `api.js` | Fetch wrapper for all REST API calls |
| `graph.js` | Cytoscape initialization, node colors (`nodeColor()`), corner icons, layout |
| `projects.js` | Project CRUD, sidebar rail management |
| `nodes.js` | Node creation/editing panel, inline edge creation |
| `edges.js` | Edge CRUD, context menu |
| `credentials.js` | Credential management panel |
| `timeline.js` | Chronological node view |
| `search.js` | Cross-project search dropdown |
| `evidence.js` | File upload/download for evidence attachments |
| `import.js` | Bulk JSON import with preview |
| `analysis.js` | Attack path analysis display + AI integration |
| `daily_report.js` | Date-filtered daily report generation |
| `ws.js` | WebSocket client — auto-reload on `graph:<pid>` broadcast |

**Zero framework** — no React, no Vue, no build tooling. Global scripts loaded in dependency order via `<script>` tags. This keeps the frontend trivially deployable and inspectable.

### Styling

| Aspect | Detail |
|--------|--------|
| File | `static/css/style.css` (2645 lines) |
| Theme | Dark — 5-level background system (`deepest` → `deep` → `surface` → `elevated` → `rail`) |
| CSS Variables | **34 custom properties** — colors, fonts, radii, shadows, transitions |
| Fonts | System stack: SF Pro Display / Inter / Segoe UI (sans), SF Mono / Fira Code / Cascadia Code / JetBrains Mono (mono) |
| Layout | Flexbox-based, 64px sidebar rail, slide-in node panel, modal overlays |

---

## Architecture Decisions & Why They Matter

### Single Binary
`[lib]` + `[[bin]]` in one Cargo.toml. The server (`src/lib.rs`) is a library the binary (`src/main.rs`) consumes. This enables both in-process serving (`serve` command) and standalone HTTP client usage — the CLI works against a remote server too.

### SQLite over PostgreSQL
Zero operational overhead. A pentest engagement doesn't need a database server — it needs a single file that survives restarts and can be copied/backed up trivially. `bundled` means no system dependencies.

### No JavaScript Build Pipeline
`include_str!("../static/index.html")` embeds HTML at compile time (requires rebuild). CSS/JS are served by `ServeDir` at runtime (hot-reloadable). No webpack, no npm, no `node_modules`. A pentest tool's frontend should be inspectable and modifiable by the operator.

### WebSocket for Real-time Updates
After every mutation (node/edge create/update/delete), the server broadcasts `graph:<pid>`. The client auto-reloads the graph. This matters when the CLI and web UI are used simultaneously during an engagement.

### API Key Auth (not JWT, not OAuth)
Simple header-based API key. Stored in `localStorage` on the client, configured via CLI `--api-key`, env var, or `theseus.toml`. Appropriate threat model: local tool, not a multi-tenant SaaS.

### CST Timezone Hardcoded
Daily reports and date filtering use UTC+8 (CST), not server local time. Pentest engagements in China-centric teams need consistent date boundaries regardless of where the tool runs.

---

## Build & Run

```bash
# Development
cargo check                    # Fast compile check
cargo run -- serve --port 3080 # Start server

# Release
./install.sh                   # Build release → ~/.local/bin/theseus

# Single crate, no workspace — all in one Cargo.toml
```

**Binary size**: ~11MB (debug). **Port**: 3080 (hardcoded). **DB**: `theseus.db` in working directory.
