Constable Documentation

body_rules #

Applied to the request body. Skipped for GET requests unless inspect_get_body is true.

{
  "body_rules": [
    { "label": "SQL injection",
      "pattern": "(?i)(select\\s.+from\\s|insert\\s+into\\s|drop\\s+table\\s|union\\s+select)" },

    { "label": "XSS script tags",
      "pattern": "(?i)]*>" },

    { "label": "command injection",
      "pattern": "(?i)(;|\\||&&|`|\\$\\()\\s*(ls|cat|wget|curl|bash|sh|nc|whoami|id|uname)" },

    { "label": "template injection (SSTI)",
      "pattern": "(\\$\\{|\\{\\{|<%|%>|#\\{).*?(exec|import|system|eval|Runtime|getClass)" },

    { "label": "log4shell JNDI",
      "pattern": "(?i)\\$\\{jndi:(ldap|rmi|dns|iiop|corba|nds|http)://" },

    { "label": "XXE external entity",
      "pattern": "(?i)]*(SYSTEM|PUBLIC)" },

    { "label": "PHP deserialization",
      "pattern": "(?i)(O:\\d+:\"|a:\\d+:\\{|s:\\d+:\")" },

    { "label": "credit card numbers",
      "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13})\\b" },

    { "label": "SSN pattern",
      "pattern": "\\b[0-9]{3}-[0-9]{2}-[0-9]{4}\\b" }
  ]
}

response_body_rules #

Applied to the upstream response body. Gzip-compressed responses are transparently decompressed for inspection; the original compressed payload is forwarded unchanged.

{
  "response_body_rules": [
    { "label": "block SSN in response",
      "pattern": "\\b[0-9]{3}-[0-9]{2}-[0-9]{4}\\b" },

    { "label": "block credit card in response",
      "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13})\\b" },

    { "label": "log WordPress failed login",
      "pattern": "(?i)(The password you entered for the username|Unknown username|Invalid username)",
      "mode": "log" }
  ],
  "max_response_inspect_bytes": 1048576
}

Per-Path Rules #

Override or extend global rules for requests whose path matches a regex. Per-path rules are evaluated after global rules.

{
  "path_rules": [
    {
      "label": "API endpoint",
      "path_pattern": "^/api/",
      "allowed_methods": ["GET", "POST", "PUT", "DELETE"],
      "body_rules": [
        { "label": "UNION SELECT", "pattern": "(?i)\\bunion\\b.+\\bselect\\b" }
      ]
    },
    {
      "label": "upload endpoint",
      "path_pattern": "^/upload",
      "allowed_methods": ["POST"],
      "body_rules": [
        { "label": "PHP opening tag", "pattern": "(?i)<\\?(php|=)" },
        { "label": "webshell eval", "pattern": "(?i)eval\\s*\\(\\s*(base64_decode|gzinflate|str_rot13)" }
      ]
    },
    { "label": "static assets", "path_pattern": "^/static/", "cache": true },
    { "label": "auth endpoints (never cache)", "path_pattern": "^/(login|logout|auth)", "cache": false },
    { "label": "downloads (skip gzip)", "path_pattern": "^/downloads/", "gzip": false }
  ]
}

Conditional Rules #

Threshold-based control statements that track how many qualifying requests a single IP has made to a specific endpoint within a time window, then fire an action when that threshold is crossed. Use cases: brute-force login protection, credential-stuffing mitigation, failure-based rate limiting.

Brute-force protection on a login endpoint

{
  "conditional_rules": [
    {
      "label": "login brute-force",
      "path_pattern": "^/login$",
      "methods": ["POST"],
      "trigger_on": "failure",
      "threshold": 3,
      "window_sec": 1800,
      "action": "block",
      "block_duration_min": 60
    }
  ]
}

Trigger on rule detection (content-inspection)

{
  "response_body_rules": [
    { "label": "log WordPress failed login",
      "pattern": "(?i)(The password you entered for the username|Unknown username)",
      "mode": "log" }
  ],
  "conditional_rules": [
    {
      "label": "wordpress login brute-force",
      "trigger_on": "rule_detect",
      "trigger_by_labels": ["log WordPress failed login"],
      "threshold": 3,
      "window_sec": 1800,
      "action": "block",
      "block_duration_min": 60
    }
  ]
}

CVE Detection #

Inline, named, explainable detection of known-CVE exploitation. Where generic rules say "this looks like an attack," CVE detection says "this is the exploitation path for CVE-2021-44228 (Log4Shell), CVSS 10.0" — and, with stack awareness, "…you run Contact Form 7 5.8.1, which is < 5.9, so you are EXPOSED."

Rules merge from three sources at load time:

• A built-in baseline catalog (Log4Shell, Spring4Shell, Struts2 OGNL, Shellshock, Confluence OGNL, plus .env/.git harvesting and WordPress user-enumeration recon) — works offline.
• A feed of CVE rules. With feed_url empty (default), a bundled cve-feed.json (~400 signatures from CISA KEV ∩ nuclei-templates) loads with no outbound request. Set feed_url to poll a live feed.
• Operator custom_rules.

Matching is two-stage: a case-folding Aho-Corasick literal prefilter answers "could any rule plausibly match?" in one pass, and only survivors run their full RE2 regex.

{ "cve_detection": { "enabled": true, "mode": "block" } }

A block emits [CVE_BLOCK]; a log-only hit emits [CVE_DETECT] (which also feeds conditional-rule trigger_on: rule_detect). A local-only /cve-intel endpoint returns the loaded rules, provenance, feed status, and per-host fingerprinted stacks.

Stack Awareness #

Because the proxy knows what runs behind each upstream, it (1) scopes the CVE ruleset to only what's deployed and (2) attaches an exposure verdict to every CVE hit. It's hybrid — declaration anchors, fingerprinting fills in.

• Declared (upstream_stack, top-level or per domains.<host>): you state the platform and optionally components with versions. Declared versions override anything detected. Set auto_detect: false to rely on the declaration alone.
• Passively detected: as upstream responses pass through, the proxy reads Server / X-Powered-By / X-Generator headers, the <meta name="generator"> tag, and WordPress plugin asset versions — keyed per host.

Given a rule whose stack.affected is <5.9 and a host running contact-form-7 5.8.1, a probe is logged exposed="yes"; a patched 6.0.0 logs exposed="no"; an undetected version logs exposed="unknown" (never treated as not-exposed).

Botnet Detection #

Three-layer detection: IP reputation blocklists, behavioral auto-blocking, and user-agent fingerprinting.

GeoIP Blocking #

Block or allow requests by country code using a CIDR-to-country CSV database.

{
  "geoip": {
    "enabled": true,
    "database_path": "/etc/constable/geoip.csv",
    "blocked_countries": ["CN", "RU", "KP"]
  }
}

CSV format — one CIDR per line with its country code: 1.0.0.0/24,AU

Learn Mode #

A WAF bootstrapper for new deployments. Enable it and let real traffic teach the proxy what query parameters your application uses. After the observation window it generates mode:"log" WAF rules targeting those parameters with SQLi, XSS, and path-traversal patterns, written to a file for review. It never blocks.

{
  "listen_addr": ":8000",
  "target_url": "http://localhost:8080",
  "learn_mode": { "enabled": true, "source_ips": ["10.0.0.0/8", "192.168.0.0/16"] }
}

Adaptive Learning #

Where Learn Mode is a one-shot rule generator, adaptive_learning is a continuous anomaly-scoring engine that keeps adapting to live traffic. It combines three signals into a per-request risk score: past attack styles, a learned profile of the application, and 4xx error indicators.

Shadow-first, never blocks by default

Even in enforce, a block requires all of: score >= enforce_threshold, at least min_corroborating_signals independent signal classes agreeing, and a mature path profile.

"conditional_rules": [
  { "label": "adaptive-enforce", "trigger_on": "adaptive_score",
    "threshold": 3, "window_sec": 300, "action": "block", "block_duration_min": 30 }
],
"adaptive_learning": { "mode": "enforce", "warmup_sec": 86400 }

Inspect the model via local-only endpoints on the metrics port: GET /anomaly-model (full dump) and GET /anomaly-model/explain?path=/api/items (one path). The model persists stats-only with decay applied for elapsed time, and survives config reloads.

Upstreams & Load Balancing #

When upstreams is set it takes precedence over target_url. Unhealthy nodes are skipped automatically when health checks are enabled.

{
  "upstreams": [
    { "url": "http://10.0.0.1:8080", "weight": 2 },
    { "url": "http://10.0.0.2:8080", "weight": 1 }
  ],
  "load_balance": "least-conn"
}

Upstream transport tuning

For HTTPS upstreams, TLS sessions are automatically resumed across connections (TLS 1.2 tickets, TLS 1.3 PSK) — no configuration needed.

Health Checks #

Periodically probe upstreams and remove unhealthy nodes from rotation.

Response Caching #

In-memory response cache. Serves repeated GET/HEAD requests from cache without hitting the upstream. Responses are cached only when the request carries no credentials and the response is 2xx with no Cache-Control: no-store/private or Set-Cookie.

Cache log events: CACHE_HIT (served from cache) and CACHE_STORE (new response stored). Config reloads that change cache settings discard the old cache and start fresh.

Gzip Compression #

Compresses eligible upstream responses before sending them to clients that advertise Accept-Encoding: gzip. Works alongside the response cache (the cache stores uncompressed bytes and compresses on-the-fly).

Security Response Headers #

Key-value pairs injected into every proxied response.

{
  "security_headers": {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "X-XSS-Protection": "1; mode=block",
    "Referrer-Policy": "strict-origin-when-cross-origin",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
  }
}

Remove Response Headers #

Strip specific headers from the upstream response before forwarding to the client.

{
  "remove_response_headers": ["Server", "X-Powered-By", "X-Generator"]
}

Response Rewrites #

String replacements applied to the response body and Location headers. Useful when an upstream returns hardcoded internal URLs or IP addresses.

{
  "response_rewrites": [
    { "find": "http://10.0.0.5",  "replace": "https://example.com" },
    { "find": "https://10.0.0.5", "replace": "https://example.com" }
  ]
}

TLS Termination #

Manual TLS using your own certificate and key files.

Let's Encrypt (Automatic TLS) #

Automatically obtain and renew certificates. Certs are cached to disk and renewed within 30 days of expiry.

{
  "lets_encrypt": {
    "enabled": true,
    "domains": ["example.com", "*.example.com"],
    "email": "admin@example.com",
    "cache_dir": "/var/lib/constable/acme",
    "challenge": "dns-cloudflare",
    "cloudflare": { "api_token": "$ENV{CF_TOKEN}", "zone_id": "YOUR_ZONE_ID" }
  }
}

HTTP & WWW Redirects #

Issue 301 redirects from HTTP to HTTPS, and from the bare domain to www.

Authentication #

Three auth methods are available; only one needs to be enabled at a time. exempt_paths lists path prefixes that bypass authentication entirely.

Basic Auth #

Passwords are stored as sha256:<hex> hashes (unsalted) and compared in constant time.

# Generate a password hash
echo -n "mypassword" | sha256sum

{
  "auth": {
    "basic": {
      "enabled": true,
      "realm": "My Proxy",
      "users": { "alice": "sha256:89e0...f45e" },
      "exempt_paths": ["/healthz", "/public"]
    }
  }
}

API Key Auth #

{
  "auth": {
    "api_key": {
      "enabled": true,
      "header": "X-API-Key",
      "keys": ["key-one-abc123", "key-two-def456"],
      "exempt_paths": ["/healthz"]
    }
  }
}

JWT Auth #

Supports HMAC algorithms HS256, HS384, HS512. The secret supports $ENV{VAR} expansion.

{
  "auth": {
    "jwt": {
      "enabled": true,
      "secret": "$ENV{JWT_SECRET}",
      "algorithm": "HS256",
      "header": "Authorization",
      "exempt_paths": ["/healthz", "/login"]
    }
  }
}

Prometheus Metrics #

Exposes a Prometheus-compatible /metrics endpoint with request counts, latency histograms, and block/allow totals — including CVE and adaptive-learning series. The same listener serves the local-only /cve-intel and /anomaly-model endpoints.

{ "metrics_addr": "127.0.0.1:9090", "metrics_local_only": true }

Peer-to-Peer Block Sync #

When running multiple proxy instances, each node automatically propagates dynamic blocks (botnet behavioral bans and conditional-rule blocks) to its peers within seconds. Nodes also run a periodic full-reconciliation loop to catch missed events.

Security model

• All messages are HMAC-SHA256 signed with a shared secret.
• Timestamp replay protection rejects messages more than 30 seconds old.
• Nonce deduplication prevents the same message from being applied twice.
• TLS transport — the listener requires a certificate (falls back to the main proxy cert).
• Optional mutual TLS for peer identity verification.

Production Hardening #

Advanced, production-oriented controls. All are off by default, hot-reloadable, and pure stdlib.

Client-certificate (mTLS) auth

tls.client_auth: "require" rejects the handshake unless the client presents a cert chaining to client_ca_file; the verified subject is forwarded upstream as X-Client-Cert-Subject.

Connection-level DDoS controls

rate_limit.max_concurrent_per_ip caps simultaneous in-flight requests per IP. Listener timeouts are tunable for slow-POST/slowloris defense: read_header_timeout_ms (10000), read_timeout_ms (30000), write_timeout_ms (60000), idle_timeout_ms (120000).

Structured body inspection

inspect_structured_body: true decodes JSON / urlencoded-form / multipart bodies into individual field values and runs body_rules against each. max_json_depth (default 64) rejects pathologically nested JSON.

Forward-auth / external authorization

"forward_auth": { "enabled": true, "url": "http://authz:9000/auth",
  "copy_request_headers": ["Cookie","Authorization"], "copy_response_headers": ["X-Auth-User"] }

A subrequest carries the original method/URI/host; 2xx allows, 401/403 denies, any other status or transport error fails closed.

Runtime management API

"management": { "enabled": true, "token": "$ENV{ASP_ADMIN_TOKEN}" }

Bearer-token + local-only admin endpoints on the metrics listener: POST /admin/ban?ip=<ip>&minutes=<n>, POST /admin/unban?ip=<ip>, GET /admin/bans, POST /admin/purge-cache. Bans persist across config reloads.

Outlier ejection / circuit breaking

outlier_detection ejects an upstream after consecutive_5xx (default 5) 5xx responses for ejection_sec (default 30) — catching backends that pass active probes but fail real requests. max_ejection_percent (default 50) caps simultaneous ejections; the last upstream is never ejected.

Upstream retries

upstream_retry retries idempotent requests on transient transport errors (never on a returned status) up to max_retries with a backoff_ms delay.

Adaptive concurrency / load shedding

adaptive_concurrency sheds requests (503) when in-flight exceeds a latency-steered limit — AIMD, bounded by [min_limit, max_limit].

Distributed tracing

tracing.enabled propagates a W3C traceparent to the upstream and logs a TRACE event linking trace_id to request_id. No OpenTelemetry SDK — pure stdlib.

Real-time alerting webhooks

alerting POSTs to a webhook (generic JSON or Slack) when thresholds are crossed — blocks_per_interval, rate_limited_per_interval, adaptive_would_block_per_tick, or alert_on_upstream_down.

SIEM / syslog streaming

"syslog": { "enabled": true, "network": "tcp+tls", "address": "siem.example.com:6514" }

Mirrors every structured log event to a remote collector as RFC5424 frames over udp / tcp / tcp+tls.

Bot challenge (proof-of-work)

"bot_challenge": { "enabled": true, "secret": "$ENV{ASP_BOT_SECRET}", "difficulty": 4, "cookie_ttl_sec": 3600 }

Gates matching paths behind a JavaScript proof-of-work interstitial. Stateless (HMAC over client IP + time) — no server-side storage, no CAPTCHA service.

Response DLP / PII redaction

"dlp": { "enabled": true, "mode": "redact", "builtins": true,
  "patterns": [ { "label": "internal-token", "pattern": "INT-[A-Z0-9]{20}" } ] }

Scans response bodies for secrets/PII and either redacts matches in-flight (mode: "redact") or logs them. builtins: true enables a curated set (US SSN, credit cards, AWS keys, JWTs, PEM private keys).

Daily AI Report #

Once per day, the proxy ships the previous 24 hours of constable.log and the running config to the Claude API and emails the analysis — top threats, block/detect/error counts, per-rule performance, and concrete config-change recommendations. Disabled by default; the pipeline can never block proxy traffic.

Complete config.json Example #

A representative configuration touching the most common subsystems. Trim it to what you need — everything not listed inherits its default.

{
  "listen_addr": ":80",
  "target_url": "http://localhost:8080",
  "max_workers": 64,
  "preserve_host": true,

  "block_status_code": 403,
  "block_message": "Blocked by proxy policy",

  "rate_limit": { "requests_per_second": 100, "burst": 200, "cleanup_interval_sec": 300 },

  "max_body_bytes": 10485760,
  "regex_timeout_ms": 2000,
  "allowed_methods": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],

  "log_format": "json",
  "log_file": "constable.log",
  "log_max_size_mb": 100,
  "log_max_backups": 5,

  "metrics_addr": "127.0.0.1:9090",
  "metrics_local_only": true,

  "cache": {
    "enabled": true, "ttl_sec": 300, "max_entries": 10000,
    "skip_cookies": ["wordpress_logged_in_", "PHPSESSID"]
  },
  "gzip": { "enabled": true, "level": 6, "exclude_types": ["image/", "video/", "application/pdf"] },

  "tls": { "listen_addr": ":443", "min_version": "1.2" },
  "lets_encrypt": { "enabled": true, "domains": ["example.com"], "email": "admin@example.com",
                    "cache_dir": "/var/lib/constable/acme", "challenge": "http" },
  "https_redirect": true,
  "allowed_redirect_hosts": ["example.com", "www.example.com"],

  "security_headers": {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "Referrer-Policy": "strict-origin-when-cross-origin"
  },
  "remove_response_headers": ["Server", "X-Powered-By"],

  "cve_detection": { "enabled": true, "mode": "block" },

  "botnet_detection": {
    "enabled": true, "log_only": false,
    "ip_blocklists": [
      { "url": "https://www.spamhaus.org/drop/drop.txt", "label": "Spamhaus DROP" }
    ],
    "behavioral_enabled": true, "error_threshold": 20, "scan_threshold": 100,
    "ua_fingerprint_enabled": true
  },

  "url_rules": [
    { "label": "block .env files",      "pattern": "\\.env($|\\?)" },
    { "label": "path traversal",        "pattern": "(?i)(\\.\\.[\\\\/]|%2e%2e[%2f%5c])" },
    { "label": "sensitive file access", "pattern": "(?i)\\.(htaccess|htpasswd|git|svn|bak)($|[\\?/])" }
  ],
  "header_rules": [
    { "label": "block scanner user-agents", "pattern": "(?i)User-Agent:.*(sqlmap|nikto|nmap|nuclei)" }
  ],
  "body_rules": [
    { "label": "log4shell JNDI", "pattern": "(?i)\\$\\{jndi:(ldap|rmi|dns)://" }
  ],

  "conditional_rules": [
    {
      "label": "login brute-force",
      "path_pattern": "^/login$", "methods": ["POST"],
      "trigger_on": "failure", "threshold": 3, "window_sec": 1800,
      "action": "block", "block_duration_min": 60
    }
  ]
}