diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..ee03553 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,42 @@ +# Environment files (may contain real secrets) +.env +.env.* +!.env.example + +# Git +.git +.gitignore + +# Node modules (host might be glibc, container is musl) +node_modules + +# Reports and evidence (mounted as volumes) +reports +evidence + +# Build artifacts +dist +*.log +npm-debug.log* + +# IDE +.vscode +.idea +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Docker +docker-compose.override.yml +Dockerfile* +.dockerignore + +# CI/CD +.github + +# Documentation (built at runtime if needed) +docs/.vitepress/cache +docs/.vitepress/dist diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..05bcb29 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,43 @@ +# syntax=docker/dockerfile:1 + +FROM node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2 + +# 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 + +# Docker environment marker (tells server.ts to bind to 0.0.0.0) +ENV DOCKER=true + +# Expose port +EXPOSE 3333 + +# Health check +HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \ + CMD wget --no-verbose --tries=1 --spider http://localhost:3333/api/health || exit 1 + +# Default command: run the server (not interactive CLI) +CMD ["npm", "run", "server"] diff --git a/README.md b/README.md index 8ee64fe..12056f6 100755 --- a/README.md +++ b/README.md @@ -101,6 +101,33 @@ 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 (localhost only, not exposed externally): + +```bash +cp .env.example .env # configure API keys +docker compose up -d # API → http://localhost:3333 +docker compose logs -f # view logs +``` + +**Security Note:** Container binds to `127.0.0.1:3333` - accessible only from localhost, not exposed to network. + +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). + ## Updating from upstream If you installed from a release tarball or copied the tree instead of tracking `git pull`, use the built-in updater to sync with [github.com/elder-plinius/T3MP3ST](https://github.com/elder-plinius/T3MP3ST) without losing local secrets or bench output. It shows a numbered plan, asks **y/N** before changing anything, then runs `npm install`. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..60bd12c --- /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_PORT=3333 + volumes: + - ./reports:/app/reports + - ./evidence:/app/evidence + ports: + - "127.0.0.1:3333:3333" + healthcheck: + test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3333/api/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s diff --git a/docs/DOCKER.md b/docs/DOCKER.md new file mode 100644 index 0000000..6fdca4e --- /dev/null +++ b/docs/DOCKER.md @@ -0,0 +1,210 @@ +# 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:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2 AS builder +WORKDIR /app +COPY package*.json tsconfig.json ./ +RUN npm ci +COPY . . +RUN npm run build + +FROM node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2 +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 3333 already in use + +Change the host port in `docker-compose.yml` (keep the `127.0.0.1:` prefix for security): +```yaml +ports: + - "127.0.0.1:8080:3333" # 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 + +**⚠️ CRITICAL: External Exposure Risk** + +The Docker setup binds the server to `0.0.0.0` inside the container to allow port forwarding. This disables the Host-header/DNS-rebinding guard in `server.ts`. + +**SAFE:** The default `docker-compose.yml` publishes the port as `127.0.0.1:3333:3333`, which restricts access to localhost only. + +**UNSAFE:** Running `docker run -p 3333:3333` (without the `127.0.0.1:` prefix) or `network_mode: host` exposes the **unauthenticated command-executing API** on all network interfaces (0.0.0.0), allowing anyone on your network (or the internet if port-forwarded) to execute arbitrary system commands. + +**Deployment Rules:** +- ✅ Always bind to `127.0.0.1` on the host: `-p 127.0.0.1:3333:3333` +- ✅ Use a reverse proxy (nginx, Caddy, Coolify) with authentication for external access +- ❌ Never use `network_mode: host` in untrusted networks +- ❌ Never publish to `0.0.0.0` without authentication middleware + +**Additional Security:** +- Container runs as root by default. For production, add a non-root user in the Dockerfile. +- The `.env` file is excluded from the image via `.dockerignore` to prevent secret leakage. +- Network mode is `bridge` by default (isolated from host network). + +## Integration with Tools + +External security tools (nuclei, ffuf, sqlmap) can run in separate containers or be installed in a custom Dockerfile: + +```dockerfile +FROM node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2 +RUN apk add --no-cache nmap nuclei ffuf +# ... rest of Dockerfile +``` + +Refer to `docs/INSTALL_MATRIX.md` for the full tool list. diff --git a/src/server.ts b/src/server.ts index 25952f4..02e73d1 100755 --- a/src/server.ts +++ b/src/server.ts @@ -141,7 +141,8 @@ const PORT = process.env.T3MP3ST_PORT || 3333; // this local command-executing API (CSRF / DNS-rebinding), NOT remote attackers. // The CORS lock + origin guard below defend that vector; if this is ever exposed // beyond localhost, add real Bearer-token auth as the upgrade path. -const HOST = process.env.T3MP3ST_HOST || '127.0.0.1'; +// DOCKER: Inside containers, bind to 0.0.0.0 (env var can still override). +const HOST = process.env.T3MP3ST_HOST || (process.env.DOCKER === 'true' ? '0.0.0.0' : '127.0.0.1'); // B-02: only enforce the Host-header allow-list when bound to loopback (the // default). If the operator EXPLICITLY exposes the server (T3MP3ST_HOST set to a // non-loopback address) they've opted into network access behind their own front,