Quick Reference Guide

📚 New to Apparatus? Start with the Documentation Navigator to find what you need. 💡 Visual Learner? Check the inline diagrams in Architecture Guide and Dashboard Tutorial.

Getting Started

Choose the method that fits your needs — npm and Docker are the fastest paths; source installs give you the full development environment.

Requires Node.js 23+.

npm install -g @atlascrew/apparatus
apparatus

Open http://localhost:8090/dashboard. The server, dashboard, and all protocol endpoints start in a single process.

Option B: Run with Docker

docker run -p 8090:8090 -p 8443:8443 -p 50051:50051 nickcrew/apparatus

Open http://localhost:8090/dashboard. Same platform as the npm package.

Pass environment variables with -e:

docker run -p 8090:8090 -p 8443:8443 \
  -e DEMO_MODE=true \
  -e ANTHROPIC_API_KEY=sk-... \
  nickcrew/apparatus

Also available from GitHub Container Registry: ghcr.io/nickcrew/apparatus.

Option C: Run from Source

Use this option when you want to develop Apparatus itself or need fine-grained control over individual components.

Prerequisites: Node.js 23+, pnpm

git clone https://github.com/NickCrew/apparatus.git
cd apparatus
pnpm install

# Generate TLS certificates (self-signed)
mkdir -p certs
openssl req -x509 -newkey rsa:2048 -keyout certs/server.key \
  -out certs/server.crt -days 365 -nodes -subj "/CN=localhost"

pnpm build
pnpm start

Option D: Full Lab with Chimera

Run Apparatus alongside Chimera (vulnerable web app + API) for a complete testing environment:

git clone https://github.com/NickCrew/apparatus.git
git clone https://github.com/NickCrew/Chimera.git
cd apparatus
docker compose --profile chimera up

Wait for all services to be healthy (30-60 seconds).

Environment Variables

Variable Default Description
HOST 0.0.0.0 Bind address
PORT_HTTP1 8090 HTTP/1.1 port
PORT_HTTP2 8443 HTTP/2 TLS port
DEMO_MODE false Enable all dangerous endpoints without localhost check
TLS_KEY certs/server.key TLS private key path
TLS_CRT certs/server.crt TLS certificate path
ANTHROPIC_API_KEY — Claude API key (for AI honeypot and autopilot)
ENABLE_COMPRESSION true Enable gzip compression
BODY_LIMIT 50mb Request body size limit
CLUSTER_SHARED_SECRET — Cluster authentication token

Accessing Services

Service URL Purpose
Apparatus Dashboard http://localhost:8090/dashboard Real-time testing control & monitoring
Apparatus API http://localhost:8090 Testing platform endpoints
VulnWeb http://localhost:3000 Vulnerable web application (12 UIs)
VulnAPI http://localhost:5000 Vulnerable REST API (450+ endpoints)
Apparatus Metrics http://localhost:8090/metrics Prometheus metrics (Grafana-compatible)
Apparatus Docs http://localhost:8090/docs Swagger API documentation

Learning Path At A Glance

Four-level feature adoption timeline from onboarding basics to advanced automation.

Common Testing Scenarios

1. Launch AI Red Team Against VulnWeb

# Start autopilot
curl -X POST http://localhost:8090/api/redteam/autopilot/start \
  -H "Content-Type: application/json" \
  -d '{
    "target": "http://vuln-web:3000",
    "config": {
      "interval": 2000,
      "maxIterations": 50,
      "allowedTools": ["chaos.cpu", "cluster.attack", "mtd.rotate"]
    }
  }'

# Check status
curl http://localhost:8090/api/redteam/autopilot/status

# Get results
curl http://localhost:8090/api/redteam/autopilot/reports | jq .

# Stop autopilot
curl -X POST http://localhost:8090/api/redteam/autopilot/stop

2. Validate Payload Detection

# Test XSS/SQLi/command injection against VulnAPI
curl "http://localhost:8090/redteam/validate?target=http://vuln-api:5000&path=/search&method=GET"

# Test against VulnWeb
curl "http://localhost:8090/redteam/validate?target=http://vuln-web:3000&path=/api/users&method=POST"

3. Monitor Real-Time Traffic

Open browser to: http://localhost:8090/dashboard

Features:

  • Live request feed with SSE streaming
  • Traffic heatmap and latency analysis
  • Deception honeypot events
  • Tarpit defense activity
  • System health metrics

4. Run Chaos While Testing

# Trigger CPU spike
curl -X POST http://localhost:8090/chaos/cpu \
  -d '{"duration": 5000}'

# Allocate memory
curl -X POST http://localhost:8090/chaos/memory \
  -d '{"action": "allocate", "amount": 512}'

# Trigger distributed cluster attack
curl -X POST http://localhost:8090/cluster/attack \
  -d '{"target": "http://vuln-web:3000/", "rate": 50}'

5. Run Pre-Built Scenarios

# Create a scenario
curl -X POST http://localhost:8090/scenarios \
  -H "Content-Type: application/json" \
  -d '{
    "name": "coordinated-chaos-test",
    "steps": [
      { "id": "1", "action": "chaos.cpu", "params": { "duration": 3000 } },
      { "id": "2", "action": "delay", "params": { "duration": 2000 } },
      { "id": "3", "action": "cluster.attack", "params": { "target": "http://vuln-web:3000/", "rate": 100 } }
    ]
  }'

# Extract scenario ID from response
SCENARIO_ID="sc-1708..."

# Run scenario
curl -X POST http://localhost:8090/scenarios/$SCENARIO_ID/run

# Get execution ID from response
EXECUTION_ID="run-..."

# Monitor execution
curl "http://localhost:8090/scenarios/$SCENARIO_ID/status?executionId=$EXECUTION_ID"

6. Activate Defense Mechanisms

# Add WAF rule (Active Shield)
curl -X POST http://localhost:8090/sentinel/rules \
  -H "Content-Type: application/json" \
  -d '{"pattern": "/admin", "action": "block"}'

# List rules
curl http://localhost:8090/sentinel/rules

# Enable Moving Target Defense (MTD)
curl -X POST http://localhost:8090/mtd \
  -d '{"prefix": "secure-xyz123"}'

# Verify MTD requires prefix
curl http://localhost:8090/echo      # Returns 404
curl http://localhost:8090/secure-xyz123/echo  # Returns 200

7. Capture and Inspect Traffic

# Capture PCAP for 30 seconds
curl "http://localhost:8090/capture.pcap?duration=30&iface=eth0" -o traffic.pcap

# Inspect via Wireshark
wireshark traffic.pcap

# View request history
curl http://localhost:8090/history | jq .

# Clear history
curl -X DELETE http://localhost:8090/history

8. Test DLP Detection

# Generate credit card numbers
curl "http://localhost:8090/dlp?type=cc"

# Generate SSNs
curl "http://localhost:8090/dlp?type=ssn"

# Generate fake SQL errors
curl "http://localhost:8090/dlp?type=sql"

# Test if your DLP system detects these

9. Webhook Testing

# Send webhook to Apparatus
curl -X POST http://localhost:8090/hooks/my-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"event": "deployment", "version": "1.0.0"}'

# Inspect webhooks received
curl http://localhost:8090/hooks/my-webhook-id/inspect

10. Terminal UI Monitoring

# In apparatus directory
pnpm tui

Features:

  • Real-time traffic graph
  • Request/response details
  • Event streams (deception, tarpit, webhooks)
  • System metrics (CPU, memory, event loop lag)
  • Scenario control
  • API status monitoring

Useful Endpoints

Reflection & Debugging

  • GET /echo - Echo back all request details
  • GET /sysinfo - System and process information
  • GET /metrics - Prometheus metrics
  • GET /healthz - Basic health check
  • GET /health/pro - Advanced health with lag metrics
  • GET /history - Recent request history

Network Tools

  • GET /dns?target=example.com&type=A - DNS queries
  • GET /ping?target=host:port - TCP connectivity test
  • GET /generate?size=100mb - Generate bandwidth
  • POST /sink - Discard uploaded data

Security Testing

  • GET /redteam/validate?target=...&path=... - Payload validation
  • GET /debug/jwt?token=... - JWT debugging
  • GET /dlp?type=cc|ssn|email|sql - Sensitive data generation
  • GET /ratelimit - Rate limit testing

Defense & Deception

  • GET /deception/history - Honeypot events
  • GET /tarpit - Trapped IPs
  • POST /tarpit/release - Release trapped IPs
  • GET /sentinel/rules - Active Shield (WAF) rules
  • POST /mtd - Rotate Moving Target Defense prefix

Cluster & Distributed

  • POST /cluster/attack - Broadcast attack to cluster
  • GET /cluster/members - List cluster nodes

Docker Compose Commands

# Start all services
docker-compose up

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f apparatus

# Stop all services
docker-compose down

# Rebuild images
docker-compose build

# Rebuild and restart
docker-compose up --build

# View service status
docker-compose ps

# Execute command in container
docker-compose exec apparatus pnpm test

Troubleshooting

Services won’t start

# Check logs
docker-compose logs apparatus
docker-compose logs vuln-web
docker-compose logs vuln-api

# Verify ports are free
lsof -i :8090
lsof -i :3000
lsof -i :5000

# Clean up and restart
docker-compose down -v
docker-compose up --build

Dashboard not loading

# Verify Apparatus is running
curl http://localhost:8090/healthz

# Check for build errors
docker-compose logs apparatus | grep -i error

# Clear browser cache (Ctrl+Shift+Del) and refresh

Tests failing

# Run tests in container
docker-compose exec apparatus pnpm test

# Run specific test
docker-compose exec apparatus pnpm test -- test/scenarios.test.ts

# Run with verbose output
docker-compose exec apparatus pnpm test -- --reporter=verbose

Red team autopilot not connecting to target

# Verify target is reachable from Apparatus container
docker-compose exec apparatus curl http://vuln-web:3000/health

# Check network
docker network inspect apparatus_security-lab

# Verify firewall rules

Performance Tips

Reduce Memory Usage

# Limit Docker container memory
docker-compose.yml: `mem_limit: 512m`

# Clear old deception events
curl -X DELETE http://localhost:8090/deception/history

# Clear request history
curl -X DELETE http://localhost:8090/history

Improve Dashboard Performance

  • Close browser DevTools (F12) while monitoring
  • Reduce SSE client count by refreshing fewer browser tabs
  • Use TUI (pnpm tui) for lighter-weight monitoring

Run Specific Services Only

# Just Apparatus
docker-compose up apparatus

# Just Chimera
docker-compose up vuln-web vuln-api

Useful Aliases

Add to .bash_profile or .zshrc:

# Start full lab
alias apparatus-lab='cd ~/Developer/apparatus && docker-compose up'

# Just Apparatus
alias apparatus-start='cd ~/Developer/apparatus && pnpm build && pnpm start'

# View dashboard
alias apparatus-dash='open http://localhost:8090/dashboard'

# Run tests
alias apparatus-test='cd ~/Developer/apparatus && pnpm test'

# Terminal UI
alias apparatus-tui='cd ~/Developer/apparatus && pnpm tui'

# Red team start
alias apparatus-redteam='curl -X POST http://localhost:8090/api/redteam/autopilot/start -H "Content-Type: application/json" -d'

# Check status
alias apparatus-status='curl http://localhost:8090/healthz && curl http://localhost:3000/health && curl http://localhost:5000/health'

Next Steps