vadymsemeniuk/saboteur

Saboteur — HTTP Fault Injection Proxy

A lightweight HTTP-layer fault injection proxy. Intercepts traffic and injects configurable faults based on rules — useful for testing service resilience in development and CI/CD.

Key differentiator from Toxiproxy: operates at HTTP layer — understands URLs, methods, headers, and response bodies. Not TCP-level.

---

Quickstart

bash
docker run -p 8080:8080 -p 8081:8081 \
  -e UPSTREAM_URL=http://my-service:3000 \
  yourname/saboteur

• Port 8080 — proxy (send your real traffic here)
• Port 8081 — control UI + API (manage rules, view traffic)

Open http://localhost:8081 in your browser to use the web UI.

---

With a config file

bash
docker run -p 8080:8080 -p 8081:8081 \
  -v $(pwd)/config/example.yaml:/etc/saboteur/config.yaml \
  yourname/saboteur --config /etc/saboteur/config.yaml

---

Docker Compose

bash
docker compose up

Uses docker-compose.yml in the repo root. Spins up saboteur + a mock upstream (hashicorp/http-echo).

---

Configuration Reference

All settings can be provided via YAML file or environment variables.

---

Fault Types

Latency

Add delay before forwarding or returning.

yaml
fault:
  type: latency
  mode: fixed       # fixed | uniform | normal
  fixed_ms: 500
  apply_to: request # request | response

Error Response

Return a specific status without hitting upstream.

yaml
fault:
  type: error
  status_code: 503
  body: '{"error":"down"}'
  headers:
    Retry-After: "30"

Connection Abort

Drop the connection after N bytes.

yaml
fault:
  type: abort
  after_bytes: 0    # 0 = drop immediately

Timeout

Accept connection, forward to upstream, never respond.

yaml
fault:
  type: timeout

Body Corruption

Replace the upstream response body.

yaml
fault:
  type: body_corrupt
  mode: json_invalid  # empty | random_bytes | json_invalid | truncate
  truncate_bytes: 100 # for truncate mode

Header Injection

Add or override headers on request or response.

yaml
fault:
  type: header_inject
  apply_to: response   # request | response
  headers:
    X-Injected: "true"

Bandwidth Throttle

Rate-limit response streaming.

yaml
fault:
  type: throttle
  bytes_per_second: 1024

---

Rule System

Rules are evaluated in priority order (lower number = higher priority). A request matches the first rule where all matcher conditions are satisfied.

yaml
rules:
  - id: "payment-errors"
    enabled: true
    priority: 10
    description: "503 on 20% of EU payment POSTs"
    match:
      path_prefix: "/api/payment"
      methods: [POST]
      headers:
        X-Region: "EU"
    percentage: 20        # 0-100; fraction of matching requests that get the fault
    fault:
      type: error
      status_code: 503
      body: '{"error":"unavailable"}'

Matcher fields (all optional; unset = match anything)

---

Control API Overview

Base URL: http://localhost:8081

Full spec: openapi.yaml

API Key auth

bash
curl -H "X-API-Key: mysecret" http://localhost:8081/api/rules

Quick examples

bash
# Add an error rule
curl -X POST http://localhost:8081/api/rules \
  -H "Content-Type: application/json" \
  -d '{"id":"test-error","enabled":true,"priority":1,"percentage":100,"match":{},"fault":{"type":"error","status_code":503}}'

# Toggle a rule off
curl -X PATCH http://localhost:8081/api/rules/test-error \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

# View recent traffic (faults only)
curl "http://localhost:8081/api/traffic?limit=10&fault_only=true"

# Delete a rule
curl -X DELETE http://localhost:8081/api/rules/test-error

# Reset all runtime rules
curl -X POST http://localhost:8081/api/rules/reset

---

Hot Reload (SIGHUP)

Send SIGHUP to reload the config file without restarting:

bash
kill -HUP $(pgrep saboteur)

Config-file rules are replaced atomically. Runtime rules (created via API) are preserved.

---

Prometheus Metrics

Available at http://localhost:8081/metrics.

---

Building from source

bash
go build -o saboteur ./cmd/saboteur
UPSTREAM_URL=http://localhost:3000 ./saboteur

Run tests

bash
go test ./...
go test -race ./...

Build Docker image

bash
docker build -f docker/Dockerfile -t saboteur .

Multi-arch:

bash
docker buildx build --platform linux/amd64,linux/arm64 \
  -f docker/Dockerfile -t yourname/saboteur:latest --push .

---

Out of scope

• TCP-level fault injection (use https://github.com/Shopify/toxiproxy)
• gRPC support
• Persistent rule storage (config file is the persistence layer)
• TLS termination on the proxy port