Skip to content
TruthVouch Docs

Firewall: Config Reference

Complete configuration reference for the TruthVouch Governance Gateway. Configure scanning behavior, thresholds, allowlists, and model routing in config.yaml.

Full Configuration Schema

server:
  # Network binding
  host: 0.0.0.0
  port: 50052


  # Worker processes
  workers: 4


  # Request timeout in milliseconds
  request_timeout_ms: 30000


  # Max payload size (bytes)
  max_payload_size: 10485760  # 10MB


database:
  # Connection pool settings
  pool_size: 20
  max_overflow: 40
  pool_timeout_sec: 30


  # Query timeout (seconds)
  query_timeout_sec: 10


  # Enable connection SSL
  ssl_mode: require  # require, prefer, allow, disable


logging:
  # Log level
  level: INFO  # DEBUG, INFO, WARN, ERROR


  # Output format
  format: json  # json, text


  # Log file path
  file: /app/logs/gateway.log


  # Max file size in MB (for rotation)
  max_size_mb: 100


  # Keep last N rotated files
  max_backups: 10


  # Log retention days
  max_age_days: 30


  # Fields to include in logs
  include_fields:
    - timestamp
    - level
    - message
    - request_id
    - duration_ms
    - error


scanning:
  # Enabled scan stages
  stages:
    - name: truth_scan
      enabled: true


    - name: pii_scanner
      enabled: true


    - name: injection_scanner
      enabled: true


    - name: toxicity_scanner
      enabled: true


    - name: contamination_check
      enabled: true


    - name: hallucination_detector
      enabled: true


    - name: output_truth_scanner
      enabled: true


  # Per-stage configuration
  stage_config:
    pii_scanner:
      # Detect PII patterns
      patterns:
        ssn: true
        credit_card: true
        phone_number: true
        email: true
        passport: true


      # Fail open on pattern error (don't block request)
      fail_open: true


    injection_scanner:
      # Enable injection detection
      enabled: true


      # Fail open on detection error
      fail_open: true


    toxicity_scanner:
      # Minimum confidence for toxic classification (0.0-1.0)
      confidence_threshold: 0.6


      # Fail open on classification error
      fail_open: true


  # Scan thresholds
  thresholds:
    # PII risk score (0-1.0)
    pii_risk: 0.6


    # Toxicity score (0-1.0)
    toxicity_score: 0.7


    # Hallucination confidence (0-1.0)
    hallucination_score: 0.8


    # Injection likelihood (0-1.0)
    injection_score: 0.5


allowlists:
  # Domains that bypass scanning
  whitelisted_domains:
    - trusted-partner.com
    - internal.company.local


  # PII patterns to ignore
  pii_exceptions:
    patterns:
      - "[email protected]"
      - "555-1234"


  # Users exempt from scanning
  exempt_users:
    - [email protected]
    - [email protected]


  # IP addresses exempt from scanning
  exempt_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12


models:
  # LLM provider configurations
  providers:
    openai:
      enabled: true
      api_key: ${OPENAI_API_KEY}


      # Route specific models
      models:
        gpt-4:
          enabled: true
          max_requests_per_minute: 500


        gpt-3.5-turbo:
          enabled: true
          max_requests_per_minute: 1000


    anthropic:
      enabled: true
      api_key: ${ANTHROPIC_API_KEY}


      models:
        claude-3-opus:
          enabled: true
          max_requests_per_minute: 200


    azure_openai:
      enabled: true
      api_key: ${AZURE_OPENAI_API_KEY}


      deployment: my-deployment
      api_version: 2024-01-01


caching:
  # Redis cache for embeddings
  enabled: true


  host: redis
  port: 6379


  # Cache TTL in seconds
  ttl_seconds: 3600


  # Cache key prefix
  key_prefix: truthvouch_


  # Max cache size
  max_items: 100000


  # Optional: password
  password: ${REDIS_PASSWORD}


  # Optional: SSL
  ssl: true


embeddings:
  # Vector database backend
  provider: pgvector  # pgvector, weaviate, pinecone


  # Embedding dimension
  dimension: 1536


  # Model to use for embeddings
  model: text-embedding-3-small


  # Batch size for embedding requests
  batch_size: 32


  # Fail open if embedding fails
  fail_open: true


compliance:
  # Enable GDPR compliance mode
  gdpr_mode: false


  # Enable HIPAA compliance mode
  hipaa_mode: false


  # PII retention period (days)
  pii_retention_days: 30


  # Require audit logging
  audit_logging: true


  # Hash PII in logs
  hash_pii_in_logs: true


monitoring:
  # Prometheus metrics
  prometheus:
    enabled: true
    port: 9090
    path: /metrics


  # Health check settings
  health_check:
    port: 8080
    path: /health
    check_interval_sec: 10


  # Alert thresholds
  alerts:
    error_rate_threshold: 0.05  # 5%
    latency_threshold_ms: 5000
    pii_detection_spike: 10  # per minute


audit:
  # Store audit logs in database
  enabled: true


  # Audit log table
  table_name: gateway_audit_logs


  # Retain audit logs (days)
  retention_days: 90


  # Sampled audit (audit every Nth request)
  sample_rate: 0.1  # 10% sampling for high-volume environments


rate_limiting:
  # Global rate limit
  enabled: true


  # Requests per second
  requests_per_second: 1000


  # Per-client limits
  per_client:
    # Requests per minute per IP
    requests_per_minute: 10000


    # Burst limit
    burst_size: 100


  # Rate limit response
  rate_limit_exceeded_status: 429


security:
  # Enable mutual TLS
  mtls_enabled: false


  # Client certificate path
  client_cert_path: /app/certs/client.crt


  # Client key path
  client_key_path: /app/certs/client.key


  # CA certificate for client verification
  ca_cert_path: /app/certs/ca.crt


  # Enable request signing
  request_signing: true


  # Request signing key
  signing_key: ${GATEWAY_SIGNING_KEY}


# Environment variable substitution
env_vars:
  OPENAI_API_KEY: sk-...
  ANTHROPIC_API_KEY: sk-ant-...
  AZURE_OPENAI_API_KEY: key-...
  REDIS_PASSWORD: redis-password
  GATEWAY_SIGNING_KEY: signing-key

Common Configurations

Development

server:
  workers: 2
logging:
  level: DEBUG
scanning:
  thresholds:
    pii_risk: 0.3
    toxicity_score: 0.5
caching:
  enabled: false

Production

server:
  workers: 8
logging:
  level: INFO
scanning:
  thresholds:
    pii_risk: 0.6
    toxicity_score: 0.7
caching:
  enabled: true
  ttl_seconds: 3600
autoscaling:
  enabled: true

High Security

scanning:
  thresholds:
    pii_risk: 0.9
    toxicity_score: 0.9
    hallucination_score: 0.9
security:
  mtls_enabled: true
  request_signing: true
compliance:
  hipaa_mode: true
  audit_logging: true
  hash_pii_in_logs: true

Stage Configuration Details

Truth Scan

Detects hallucinations using semantic similarity:

stage_config:
  truth_scan:
    # Similarity threshold (0-1)
    similarity_threshold: 0.7
    # Vector embedding model
    embedding_model: text-embedding-3-small

PII Scanner

Detects personally identifiable information:

stage_config:
  pii_scanner:
    patterns:
      ssn: true              # 123-45-6789
      credit_card: true      # 1234-5678-9012-3456
      phone_number: true     # (555) 123-4567
      email: true            # [email protected]
      passport: true         # AB123456
      ip_address: true       # 192.168.1.1
      bank_account: true     # Account numbers

Injection Scanner

Detects prompt injection and code injection:

stage_config:
  injection_scanner:
    types:
      prompt_injection: true
      sql_injection: true
      command_injection: true
      xpath_injection: true

Toxicity Scanner

Detects harmful, toxic, or inappropriate content:

stage_config:
  toxicity_scanner:
    categories:
      hate_speech: true
      harassment: true
      self_harm: true
      violence: true
      sexual_content: true

Environment Variable Substitution

Use environment variables in config:

# In config.yaml
models:
  openai:
    api_key: ${OPENAI_API_KEY}


# In .env or container env vars
OPENAI_API_KEY=sk-...

Config Validation

Validate configuration before deployment:

Terminal window
# Docker
docker run truthvouch/gateway --validate-config config.yaml


# Kubernetes
kubectl exec deployment/gateway -- gateway --validate-config /app/config/config.yaml

Hot Reload

Reload configuration without restarting:

Terminal window
# Send SIGHUP to gateway process
kill -HUP <pid>


# Or via API (if enabled)
curl -X POST http://localhost:8080/reload-config

Migration Guide

From v1 to v2 config format

The v2 configuration adds stage_config for per-stage settings. Migration:

v1:

pii_detection: true
pii_threshold: 0.6

v2:

scanning:
  stages:
    - name: pii_scanner
      enabled: true
  stage_config:
    pii_scanner:
      confidence_threshold: 0.6

See Monitoring for metrics configuration.