Integration Guide: Apparatus + Chimera

This guide explains how Apparatus and Chimera work together as a complete security testing ecosystem.

Overview

Apparatus and Chimera are two separate monorepos designed to work together:

Component	Purpose	Location
Apparatus	Security testing platform (59+ features)	/Users/nferguson/Developer/apparatus
Chimera	Vulnerable web app + API targets	/Users/nferguson/Developer/Chimera

Together they form a complete attack/defense simulation lab.

---

Quick Start

# Navigate to Apparatus root
cd ~/Developer/apparatus

# Start everything with docker-compose
docker-compose up

Services will be available at:

• Apparatus Dashboard: http://localhost:8090/dashboard
• VulnWeb: http://localhost:3000
• VulnAPI: http://localhost:5000

---

Architecture

Docker Compose Network

All containers run on isolated network security-lab:

• Apparatus can reach VulnWeb at http://vuln-web:3000
• Apparatus can reach VulnAPI at http://vuln-api:5000
• VulnWeb can reach VulnAPI at http://vuln-api:5000

---

Typical Workflows

1. Red Team Testing Against VulnWeb

# Start full lab
docker-compose up

# In another terminal, launch autopilot against VulnWeb
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
    }
  }'

# Monitor in dashboard
open http://localhost:8090/dashboard

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

2. Payload Validation Against VulnAPI

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

3. Chaos Engineering While Testing

# Start baseline load against VulnWeb
for i in {1..10}; do
  curl http://localhost:3000/api/endpoint &
done

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

# Monitor impact on VulnWeb response times
curl http://localhost:8090/dashboard

4. Scenario-Based Testing

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

# Run scenario
SCENARIO_ID="sc-..."  # from response
curl -X POST http://localhost:8090/scenarios/$SCENARIO_ID/run

# Monitor
curl "http://localhost:8090/scenarios/$SCENARIO_ID/status?executionId=run-..."

5. Defense Validation

# Activate MTD on Apparatus
curl -X POST http://localhost:8090/mtd \
  -d '{"prefix": "secure-xyz"}'

# Test if VulnWeb can still reach Apparatus (it will fail without prefix)
docker-compose exec vuln-web curl http://apparatus:8090/echo     # 404
docker-compose exec vuln-web curl http://apparatus:8090/secure-xyz/echo  # 200

# Add WAF rule to block certain paths
curl -X POST http://localhost:8090/sentinel/rules \
  -d '{"pattern": "/admin", "action": "block"}'

# Test blocking works
curl http://localhost:8090/secure-xyz/admin  # 403 Forbidden

---

Development Workflow

Making Changes to Apparatus

# Stop docker-compose
docker-compose down

# Make changes to src/
vi apps/apparatus/src/myfeature.ts

# Rebuild
pnpm build

# Start again
docker-compose up --build

Making Changes to Chimera

# Stop docker-compose
docker-compose down

# Navigate to Chimera and make changes
cd ../Chimera
vi apps/vuln-web/src/index.ts

# Build from Chimera directory
pnpm build

# Back to Apparatus, restart
cd ../apparatus
docker-compose up --build

Debugging

# View Apparatus logs
docker-compose logs -f apparatus

# View VulnWeb logs
docker-compose logs -f vuln-web

# View VulnAPI logs
docker-compose logs -f vuln-api

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

---

Key Endpoints for Integration

Apparatus → Chimera Testing

From Apparatus, attack or test Chimera targets:

# Red team VulnWeb
curl -X POST http://localhost:8090/api/redteam/autopilot/start \
  -d '{"target": "http://vuln-web:3000"}'

# Test payloads against VulnAPI
curl "http://localhost:8090/redteam/validate?target=http://vuln-api:5000&path=/api/users"

# Proxy requests through Apparatus to VulnWeb
curl "http://localhost:8090/proxy?url=http://vuln-web:3000/admin"

# Generate load against VulnWeb
curl -X POST http://localhost:8090/scenarios \
  -d '{
    "name": "load-test",
    "steps": [
      {
        "id": "1",
        "action": "cluster.attack",
        "params": {"target": "http://vuln-web:3000/", "rate": 50}
      }
    ]
  }'

Chimera → Apparatus Communication

If Chimera needs to report findings or trigger events in Apparatus:

// From Chimera backend
const response = await fetch('http://apparatus:8090/webhooks/vuln-lab-events', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    event: 'vulnerability_detected',
    type: 'xss',
    path: '/search',
    severity: 'high'
  })
});

Monitor webhook in Apparatus:

curl http://localhost:8090/hooks/vuln-lab-events/inspect

---

Monitoring & Metrics

Real-Time Dashboard

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

• All requests hitting both Apparatus and (reflected via echo) Chimera
• Real-time traffic heatmap
• Autopilot findings and progress
• Deception honeypot events
• System metrics

Prometheus Metrics

# Get Prometheus metrics
curl http://localhost:8090/metrics

# Example metrics:
# http_requests_total{method="POST",route="/api/redteam/autopilot/start",status_code="202"} 1
# http_request_duration_microseconds_bucket{le="1000", method="GET", route="/echo"} 42

Request History

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

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

---

Performance Tuning

Docker Compose Resource Limits

Edit docker-compose.yml to add limits:

services:
  apparatus:
    mem_limit: 512m
    cpus: 2

  vuln-web:
    mem_limit: 256m
    cpus: 1

  vuln-api:
    mem_limit: 256m
    cpus: 1

Reduce Event Storage

Apparatus stores events in memory. To prevent bloat:

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

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

# Clear webhooks
docker-compose exec apparatus rm -rf /tmp/webhooks

Run Services Separately

If you only need one component:

# Just Apparatus
docker-compose up apparatus

# Just Chimera (from Chimera repo)
cd ../Chimera
docker-compose up

# Just run source (no Docker)
cd apparatus
pnpm build && pnpm start

---

Troubleshooting

Containers won’t start

# Check logs
docker-compose logs

# Verify images built correctly
docker images | grep -E "apparatus|vuln"

# Clean and rebuild
docker-compose down -v
docker-compose build --no-cache
docker-compose up

Network connectivity issues

# Check network exists
docker network ls | grep security-lab

# Inspect network
docker network inspect apparatus_security-lab

# Test connectivity from Apparatus
docker-compose exec apparatus curl http://vuln-web:3000/health
docker-compose exec apparatus curl http://vuln-api:5000/health

Services unhealthy

# Check health status
docker-compose ps

# View startup logs
docker-compose logs --tail=100 apparatus

# Give containers more time to start
docker-compose up --wait  # Waits for healthchecks

Dashboard not loading

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

# Check browser console for errors (F12)
# Try hard refresh: Cmd+Shift+R or Ctrl+Shift+R

# Clear browser cache and try again

Autopilot not connecting to target

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

# Check network configuration
docker-compose ps  # Verify all containers are running

# View autopilot logs
docker-compose logs apparatus | grep -i autopilot

---

Advanced: Custom Integration

Add Your Own Target

Edit docker-compose.yml:

services:
  my-app:
    build:
      context: ../my-vulnerable-app
    ports:
      - "8000:8000"
    networks:
      - security-lab

Then test against it from Apparatus:

curl -X POST http://localhost:8090/api/redteam/autopilot/start \
  -d '{"target": "http://my-app:8000"}'

Custom Scenario for Chimera

curl -X POST http://localhost:8090/scenarios \
  -H "Content-Type: application/json" \
  -d '{
    "name": "comprehensive-vuln-lab-test",
    "steps": [
      { "id": "1", "action": "delay", "params": { "duration": 1000 } },
      { "id": "2", "action": "chaos.memory", "params": { "action": "allocate", "amount": 256 } },
      { "id": "3", "action": "cluster.attack", "params": { "target": "http://vuln-web:3000/", "rate": 75 } },
      { "id": "4", "action": "delay", "params": { "duration": 3000 } },
      { "id": "5", "action": "chaos.cpu", "params": { "duration": 5000 } }
    ]
  }'

Monitor Traffic in Terminal UI

# Run Terminal UI in Apparatus
docker-compose exec apparatus pnpm tui

# Watch real-time metrics while testing Chimera

---

Next Steps

• Quick Reference - Common commands and scenarios
• Features - All 58+ features explained
• Architecture - System design and data flow
• Chimera Documentation - Vulnerable app details

---

Support

• 📖 Apparatus docs: See /docs/ folder
• 🐛 Issues: Report in respective repository
• 💬 Questions: Check integration examples above

---

Last Updated: 2026-02-18