From 3aa4023c8f7bdee5554136f9ce4020776adc6508 Mon Sep 17 00:00:00 2001
From: Nicolas Pastorello <nicolaspastorello1@gmail.com>
Date: Mon, 6 Jul 2026 17:44:20 -0300
Subject: [PATCH] feat: add Docker deployment support

- Add Dockerfile with Node.js 18 alpine build
- Add docker-compose.yml with environment configuration
- Add docs/DOCKER.md deployment guide
- Update README.md with Docker quick start section
- Server binds to 0.0.0.0:3333 for external access
- UI available at http://localhost:3333/ui/
- Volumes mounted for reports and evidence persistence
---
 Dockerfile         |  36 +++++++++
 README.md          |  25 ++++++
 docker-compose.yml |  22 +++++
 docs/DOCKER.md     | 195 +++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 278 insertions(+)
 create mode 100644 Dockerfile
 create mode 100644 docker-compose.yml
 create mode 100644 docs/DOCKER.md

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..41eafc5
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,36 @@
+# syntax=docker/dockerfile:1
+
+FROM node:18-alpine
+
+# Install dependencies
+RUN apk add --no-cache \
+    bash \
+    curl \
+    git \
+    openssl \
+    ca-certificates
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY tsconfig.json ./
+
+# Install dependencies
+RUN npm ci && \
+    npm cache clean --force
+
+# Copy source code
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+# Ensure docs directory exists for /ui static files
+RUN mkdir -p docs
+
+# Expose port
+EXPOSE 3333
+
+# Default command: run the server (not interactive CLI)
+CMD ["npm", "run", "server"]
diff --git a/README.md b/README.md
index 33450bf..e4c0aca 100755
--- a/README.md
+++ b/README.md
@@ -96,6 +96,31 @@ npm run verify-claims             # re-derives every headline from committed JSO
 
 Library/SDK usage, the full HTTP API, and MCP setup live in [docs/](docs/).
 
+### Docker
+
+Run T3MP3ST API server in a container:
+
+```bash
+cp .env.example .env       # configure API keys
+docker compose up -d       # API → http://localhost:3333
+docker compose logs -f     # view logs
+```
+
+Test the API:
+```bash
+curl http://localhost:3333/api/health
+curl http://localhost:3333/api/bounty/platforms
+```
+
+Execute commands inside the container:
+
+```bash
+docker compose exec app npm run verify-claims
+docker compose exec app npm run cve:bench
+```
+
+Full deployment guide: [docs/DOCKER.md](docs/DOCKER.md).
+
 ## What ships today
 
 The framework is an 8-operator kill chain, and this table won't blow smoke about it. **Recon is a live, tool-backed engine** — and the teeth are already real: 90.1% pass@1 on XBEN, 8/10 held-out post-cutoff CVEs pinned to exact file/line/CWE, and a coordinated-disclosure pipeline that's live enough to have drafts held for vendor coordination right now. What's *not* proven is the swarm. Each downstream operator — Exploiter, Infiltrator, Exfiltrator, Ghost — runs the **same real, tool-backed ReAct loop as recon** (real exploit tools, not stubs), but the headline numbers came from a single agent, not the coordinated 8-operator cell, and end-to-end swarm exploitation is unbenchmarked and still unreliable. The engine is real; the swarm is the part still earning its stripes. Loud where we've earned it, blunt about the rest.
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..381fae1
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,22 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: t3mp3st
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - T3MP3ST_HOST=0.0.0.0
+      - T3MP3ST_PORT=3333
+    volumes:
+      - ./reports:/app/reports
+      - ./evidence:/app/evidence
+    ports:
+      - "3333:3333"
+    healthcheck:
+      test: ["CMD", "node", "-e", "process.exit(0)"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
new file mode 100644
index 0000000..069461f
--- /dev/null
+++ b/docs/DOCKER.md
@@ -0,0 +1,195 @@
+# T3MP3ST Docker Deployment
+
+Run T3MP3ST in a containerized environment. The Docker setup provides a minimal Node.js runtime with persistent volumes for reports and evidence.
+
+## Quick Start
+
+```bash
+# Build and run
+docker compose up -d
+
+# View logs
+docker compose logs -f
+
+# Stop
+docker compose down
+```
+
+The API server is available at `http://localhost:3333`.
+
+Test endpoints:
+```bash
+curl http://localhost:3333/api/health
+curl http://localhost:3333/api/bounty/platforms
+```
+
+## Prerequisites
+
+- Docker Engine 20.10+
+- Docker Compose 2.0+
+
+Verify installation:
+```bash
+docker --version
+docker compose version
+```
+
+## Environment Configuration
+
+Copy the environment template and configure API keys:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your credentials:
+```env
+ANTHROPIC_API_KEY=sk-ant-xxx
+OPENAI_API_KEY=sk-xxx
+OPENROUTER_API_KEY=xxx
+```
+
+The compose file mounts `.env` into the container automatically.
+
+## Volume Mounts
+
+| Host Path | Container Path | Purpose |
+|---|---|---|
+| `./reports` | `/app/reports` | Engagement reports and findings |
+| `./evidence` | `/app/evidence` | Collected evidence and artifacts |
+
+Data persists across container restarts.
+
+## Running Commands
+
+Execute any npm script inside the container:
+
+```bash
+# CLI
+docker compose exec app npm run dev
+
+# Setup
+docker compose exec app npm run setup
+
+# Doctor check
+docker compose exec app npm run doctor
+
+# Verify claims
+docker compose exec app npm run verify-claims
+
+# Run benchmarks
+docker compose exec app npm run cve:bench
+docker compose exec app npm run cloud:bench
+docker compose exec app npm run mobile:bench
+```
+
+## Development Mode
+
+For live code changes, mount the source directory:
+
+```yaml
+# docker-compose.dev.yml
+services:
+  app:
+    build: .
+    volumes:
+      - ./src:/app/src
+      - ./scripts:/app/scripts
+      - ./reports:/app/reports
+      - ./evidence:/app/evidence
+    command: npm run dev
+```
+
+Run with:
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up
+```
+
+## Build Optimization
+
+The default `Dockerfile` is single-stage for simplicity. For production, consider a multi-stage build:
+
+```dockerfile
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY package*.json tsconfig.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:18-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY package*.json ./
+CMD ["npm", "start"]
+```
+
+This reduces final image size from ~800MB to ~300MB.
+
+## Troubleshooting
+
+### Container exits immediately
+
+Check logs for startup errors:
+```bash
+docker compose logs app
+```
+
+Verify `.env` file exists and contains valid API keys.
+
+### Permission errors on volumes
+
+Ensure the host directories are writable:
+```bash
+mkdir -p reports evidence
+chmod 755 reports evidence
+```
+
+On Linux, match container UID/GID if needed:
+```bash
+sudo chown -R $(id -u):$(id -g) reports evidence
+```
+
+### Port 3000 already in use
+
+Change the host port in `docker-compose.yml`:
+```yaml
+ports:
+  - "8080:3000"  # host:container
+```
+
+## Cleanup
+
+Remove containers and volumes:
+```bash
+docker compose down -v
+```
+
+Remove the image:
+```bash
+docker rmi t3mp3st-app
+```
+
+Full cleanup (use with caution):
+```bash
+docker system prune -a --volumes
+```
+
+## Security Notes
+
+- Container runs as root by default. For production, add a non-root user in the Dockerfile.
+- `.env` is mounted read-only in the compose file to prevent accidental modification.
+- Network mode is `bridge` by default. Change to `host` if scanning from the container's network context.
+
+## Integration with Tools
+
+External security tools (nuclei, ffuf, sqlmap) can run in separate containers or be installed in a custom Dockerfile:
+
+```dockerfile
+FROM node:18-alpine
+RUN apk add --no-cache nmap nuclei ffuf
+# ... rest of Dockerfile
+```
+
+Refer to `docs/INSTALL_MATRIX.md` for the full tool list.