Configuration reference

Full dhal.json shape and common blocks.

Configuration reference

Dhal configuration lives in dhal.json.

Minimal config

{
  "mode": "monitor"
}

Alpha-public baseline

{
  "mode": "monitor",
  "trustProxy": false,
  "runtime": {
    "onInternalError": "allow",
    "internalErrorStatusCode": 500,
    "maxInspectionMs": 25,
    "bypass": {
      "enabled": true,
      "paths": ["/health", "/healthz", "/ready", "/readyz", "/live", "/livez"],
      "methods": ["OPTIONS"]
    }
  },
  "observability": {
    "redaction": {
      "enabled": true,
      "ip": "mask",
      "identity": "hash",
      "userAgent": "full"
    }
  }
}

Full production-shaped example

{
  "mode": "monitor",
  "trustProxy": true,
  "runtime": {
    "onInternalError": "allow",
    "internalErrorStatusCode": 500,
    "maxInspectionMs": 25,
    "bypass": {
      "enabled": true,
      "paths": ["/health", "/readyz", "/livez"],
      "methods": ["OPTIONS"]
    }
  },
  "identity": {
    "headers": {
      "userId": ["x-dhal-user-id", "x-user-id"],
      "tenantId": ["x-dhal-tenant-id", "x-tenant-id"],
      "apiKeyId": ["x-dhal-api-key-id", "x-api-key-id"]
    }
  },
  "ip": {
    "allow": [],
    "block": ["203.0.113.0/24"],
    "reputation": {
      "enabled": true,
      "provider": "abuseipdb",
      "apiKeyEnv": "ABUSEIPDB_API_KEY",
      "minScore": 75,
      "cacheTtlSeconds": 86400,
      "maxAgeInDays": 30,
      "mode": "async",
      "timeoutMs": 750
    }
  },
  "rateLimit": {
    "enabled": true,
    "store": "redis",
    "keyBy": ["ip", "route"],
    "default": {
      "windowSeconds": 60,
      "max": 120
    }
  },
  "rules": {
    "packs": ["generic-web", "api", "auth"],
    "sqli": true,
    "xss": true,
    "pathTraversal": true,
    "largePayload": {
      "enabled": true,
      "maxBytes": 1048576
    },
    "bot": {
      "enabled": true,
      "scoreThreshold": 70
    },
    "credentialStuffing": {
      "enabled": true,
      "loginPathPatterns": ["/api/login", "/login"],
      "failureStatusCodes": [400, 401, 403],
      "windowSeconds": 300,
      "maxFailures": 8,
      "keyBy": ["ip", "route"]
    }
  },
  "routes": {
    "/api/login": {
      "mode": "block",
      "rateLimit": {
        "windowSeconds": 60,
        "max": 5,
        "keyBy": ["ip", "route"]
      }
    }
  },
  "observability": {
    "redaction": {
      "enabled": true,
      "ip": "mask",
      "identity": "hash",
      "userAgent": "full"
    },
    "webhooks": {
      "enabled": true,
      "urls": ["https://security.example.com/dhal"],
      "signing": {
        "enabled": true,
        "secretEnv": "DHAL_WEBHOOK_SECRET"
      }
    },
    "otel": {
      "enabled": true,
      "serviceName": "api"
    }
  }
}

Schema

Export schema:

npx dhal schema dhal.schema.json