Configuration Reference

oguardai.yaml

The primary configuration file controls all server behavior. Pass it with --config oguardai.yaml when starting the server.

Parsing is strict and fails closed. An unrecognized top-level key aborts startup with an error that names it, and nested sections such as tenants reject an unknown or misspelled key the same way. The server never silently drops a setting it validates, so a typo like allowed_polcies cannot quietly disable a control and leave the server running with an unintended default.

server:
  host: "0.0.0.0"
  port: 3000

auth:
  mode: dev                  # dev | api_key | jwt | oidc

session:
  backend: sealed            # sealed | memory | redis (managed is planned)
  ttl_seconds: 3600

detector:
  mode: builtin              # builtin | both | advanced
  # advanced_url is unset by default; set it to the Python NER sidecar
  # URL when mode is both or advanced, e.g. http://detector:9090

policy:
  default: default
  directory: ./policies
  watch: false

transform:
  context_strategy: full
  max_context_tokens: 4096
  shadow_mode: false

output_protection:
  enabled: true   # Enabled by default — set false to disable
  mode: strict
  default_action: mask
  exempt_types: []

prompt_security:
  enabled: true
  input_scanning: true
  action: strip

file_upload:
  max_size_bytes: 52428800   # 50MB

rate_limit:
  enabled: false
  requests_per_second: 100
  burst_size: 200

Server

server:
  host: "0.0.0.0"
  port: 3000
  allowed_origins:
    - "https://app.example.com"
  max_body_size_bytes: 10485760
  tls:
    enabled: true
    cert_path: /etc/guardai/tls/server.crt
    key_path: /etc/guardai/tls/server.key

Auth

Do not use auth.mode: dev in production. Always set a real auth mode and API keys for production deployments.

API keys (auth.api_keys)

In api_key mode, callers authenticate with the X-API-Key header and each key is declared under auth.api_keys. Starting in api_key mode with no keys configured aborts startup.

auth:
  mode: api_key
  api_keys:
    - key: "sk-live-a1b2c3..."      # the raw secret compared in constant time
      identity: "billing-service"    # identity label recorded in the audit log
      name: "production-key-1"        # optional human-readable label
      tenant_id: "acme-corp"          # optional tenant scope for multi-tenancy
      scopes: [transform, rehydrate, detect]
      caller_role: "support-agent"    # optional; overrides any request-supplied caller_role
      caller_purpose: "support"       # optional; overrides any request-supplied caller_purpose

Keys can also be injected from the environment (for Helm or other orchestrators) without touching the config file. GUARDAI_API_KEY_<NAME>=<key> registers a key whose identity is <name> lowercased with underscores turned into hyphens. Companion variables bind extra attributes to that key:

Session

The sealed backend (default) stores session state in an AES-256-GCM encrypted blob returned to the client, so it is stateless and already works across replicas with no shared session store (a multi-replica deployment still needs revocation_backend: redis). The memory backend stores sessions server-side in an in-process HashMap, suitable for development and single-instance testing (sessions are lost on restart and are not shared across replicas). The redis backend stores each session encrypted at rest in a shared Redis (AES-256-GCM under the same key ring as sealed), giving cross-replica, server-side sessions the client references by session_id. It requires session.redis_url, replay_backend: redis, and revocation_backend: redis; Redis holds only ciphertext plus non-PII routing metadata (tenant, policy, and session ids, timestamps, language), never the raw token map. managed is planned.

Key rotation (session.keyring)

With no keyring, a single sealing key is derived from GUARDAI_SESSION_SECRET. To rotate the sealing secret without invalidating live sessions, declare a keyring: new sessions seal under current_kid, while any listed key can still decrypt. Rotate by adding a new key, switching current_kid, and dropping the old key after one session TTL.

session:
  keyring:
    current_kid: 2
    keys:
      - { kid: 1, secret: "previous-secret-at-least-16-chars" }
      - { kid: 2, secret: "current-secret-at-least-16-chars" }

The ring fails closed at startup on an empty keys, a duplicate kid, a current_kid not present in the ring, or a secret shorter than the derivation minimum.

Detector

Degraded mode: both vs advanced on a NER outage

Both both and advanced run the built-in Rust regex detectors alongside the Python NER sidecar. They differ only in what happens when the sidecar is unreachable or times out:

• both (graceful fallback): the request continues with builtin regex only. The NER-only entity types (person, company, location) are simply not detected for that request. No crash, no error. The transform response reports the actual result on its detector_mode and warnings fields, so a caller can see that NER did not run.
• advanced (fail-closed): NER is required, so a sidecar outage fails the request closed with GUARDAI_DETECTION_FAILED rather than silently returning regex-only results. Choose advanced when passing input through undetected is worse than rejecting it.

Independently of the configured mode, a policy that lists a type under detection.required_for fails a request closed when NER did not actually run for it, so a mandatory type is never dropped by a silent fallback. GET /v1/health reports the CONFIGURED mode, not live NER reachability (so liveness/readiness probes stay stable). Read ner_active on GET /v1/capabilities to see whether NER is configured, and the transform response's detector_mode and warnings to see whether NER ran for a given request.

Bring your own or fine-tuned NER model

The NER models are not pinned into the runtime, only the shipped defaults are. The variables below configure NER without a code change. The model-selection variables (NER_BACKEND, GLINER_MODEL, GUARDAI_SPACY_MODELS, NER_BACKEND_STRICT) are set on the Python detector service; the detection-floor variables (GUARDAI_NER_MIN_CONFIDENCE, GUARDAI_NER_MIN_LENGTH, GUARDAI_NER_ACRONYM_ALLOW, GUARDAI_NER_ACRONYM_STOPLIST) are read by the server runtime; and GUARDAI_DETECTOR_API_KEY secures the hop between them:

Because GLINER_MODEL accepts a local path, a fine-tuned model is used by mounting it into the detector container and pointing GLINER_MODEL at it. The pinned defaults exist for reproducible builds; they never prevent an operator from running their own model. Zero-shot detection labels are still driven per policy via detection.ner_labels, so a domain vocabulary needs no model change at all.

Tuning detection for your domain and language (detector.vocab)

The detector ships defaults for ~30 languages and the common PII formats. Extend it for your domain or locale without recompiling via detector.vocab. The overlay is additive: it can only add or strengthen detection, never silently weaken it, and invalid config fails startup.

detector:
  vocab:
    # Context-boost words per entity type (raise confidence when seen near a match).
    context_words:
      money: ["honorar", "rechnungsbetrag"]
      person: ["mandant", "ansprechpartner"]
    # Currency markers beyond ISO 4217 (each 2-8 uppercase ASCII alphanumerics).
    currency_codes: ["XBT"]
    # Extend ANY entity type with locale/domain regexes. A built-in label (address,
    # date_of_birth, ...) yields the built-in entity; use "custom:<name>" for a new type.
    extra_patterns:
      address: ['〒\d{3}-\d{4}[^\n]{0,40}']          # Japanese postal address
      date_of_birth: ['\b\d{4}年\d{1,2}月\d{1,2}日\b']  # Japanese date
      "custom:vat_id": ['\bVAT-\d{6}\b']

Narrowing money detection is the only detector.vocab control that reduces detection, so it is a gated break-glass requiring explicit acknowledgement (logged at startup):

detector:
  vocab:
    money_colliding_codes: ["TRY"]
    allow_money_detection_suppression: true
    money_suppression_reason: "TRY collides with the verb 'try' in our corpus"

Per-policy detection (custom regex detectors, required-NER fail-closed, confidence floors) is set in policy YAML via custom_patterns and a detection block. The proxy reads the detection vocabulary overlay from GUARDAI_DETECTOR_VOCAB (JSON). For the end-to-end extension model that ties these overlays to custom entity types and channels, see the extensibility guide.

External HTTP detector (detector.webhook)

Register an external detector over HTTP. Per request the runtime POSTs {text, language} to the endpoint and merges the returned spans additively, so a domain-specific detector augments the built-in and NER detectors. Absent = detection unaffected; invalid config aborts startup.

detector:
  webhook:
    url: https://detector.internal/scan
    entity_types: [employee_id, case_ref]   # only these types are accepted; no built-in shadowing
    api_key: ${DETECTOR_KEY}                 # optional, sent as X-Detector-API-Key
    timeout_secs: 5
    required: false                          # true => a failure (timeout/error/malformed) rejects the request

The plugin can only ADD coverage: a span overlapping a built-in or NER span is dropped, and an offset that disagrees with a returned value is rejected. See the plugin guide for the full contract.

Chunk detection concurrency (rag.chunk_detection_concurrency)

During RAG ingest, per-chunk detection runs concurrently up to this bound (0 = host CPU count, maximum 256). Tokenization stays ordered, so output is identical regardless of the value.

Notifications (notifications)

Deliver the runtime's PII-free audit events to an external endpoint (a SIEM or observability pipeline). Delivery is fire-and-forget and fail-open, so a slow or down endpoint never blocks or fails a request. The payload carries entity types and counts, never values, with session id, trace id, and tenant id as one-way fingerprints. Absent = disabled.

notifications:
  webhook_url: https://sink.internal/guardai-events
  api_key: ${SINK_KEY}                       # optional, sent as X-Notification-Key
  timeout_secs: 5
  events: [transform, policy_denied, session_expired]   # empty => all events

Language packs

Language enrichment (gender, honorifics, formality) is fully data-driven: every language ships a built-in JSON lexicon (the immutable floor), and operators add, extend, or override any language from data, with no source change, via the Python detector's GUARDAI_LANGUAGE_PACKS (a JSON file mapping a language code to a lexicon). Each entry's optional _mode selects the operation:

{
  "yue": { "female_titles": ["女士"], "male_titles": ["先生"] },
  "de":  { "male_names": ["acmebob"], "informal_markers": ["servus "] },
  "fr":  { "_mode": "replace", "female_titles": ["Mme "], "male_titles": ["M. "] }
}

• add a brand-new language (no built-in for the code): registered as-is.
• extend a built-in (default, _mode absent or "extend"): the overlay can only widen the built-in. The built-in's gender/honorific stay authoritative (the overlay only fills gaps for inputs the built-in cannot classify), so an extend overlay can never flip a built-in confident result; new formality markers join the built-in's vote; structural fields (rtl, name_order) stay built-in.
• replace a built-in (_mode: "replace"): full override.

A malformed pack fails loudly at startup. Lexicon fields: female_titles, male_titles, female_names, male_names, formal_markers, informal_markers, honorific_suffixes ([suffix, label] pairs), patronymic_suffixes ({ "female": [...], "male": [...] }), rtl, name_order ("given_first" | "given_last"), and default_formality.

Policy

Policy integrity (policy.integrity)

Optional signed-manifest verification of the policy directory. It is fail-closed and both-or-neither: when both manifest and secret are set, the server verifies every policy file against the signed manifest at startup and refuses to start on any mismatch. Both absent disables it; setting exactly one is a config error (a security control is not half-enabled).

policy:
  integrity:
    manifest: /etc/guardai/policies/.signatures.json  # relpath -> HMAC map from `oguardai-server policy sign-dir`
    secret: "${GUARDAI_POLICY_SIGNING_KEY}"            # HMAC signing secret (min 16 chars)
    kid: "policy-signer-1"                             # optional key id (informational)

Transform

Output Protection

output_protection.enabled is a production invariant: with auth.mode other than dev, the server refuses to start when it is false (use auth.mode=dev to bypass for testing).

The output guard runs the built-in regex detectors on every response. The model only ever sees tokens, so a real-looking name it emits is generated and structured-only regex would miss it. Set detector.scan_output_with_ner: true (modes both/advanced) to add a NER pass on output: it runs additively over the regex floor (only adds detections, never suppresses one). Because output scanning is an explicit safety net, it fails closed: a NER-sidecar outage blocks the response rather than silently degrading to regex-only (independent of the ingress mode). The proxy enables the same pass with GUARDAI_OUTPUT_SCAN_NER=1, covering both plain-text output and structured JSON response field values (object keys stay regex-only, since per-key NER multiplies sidecar calls for little gain).

Restore Templates

Localized restore output (honorifics, abstract labels) merged over the built-in defaults for ~30 languages. Override only what you need; everything else keeps its default.

restore_templates:
  person_titles:
    de:
      formal_female: "Sehr geehrte Frau {name}"
      formal_male: "Sehr geehrter Herr {name}"
    tr:
      formal_female: "Sayın {name}"
  company_abstract_labels:
    ja: "（会社名）"

The proxy reads the same overrides from GUARDAI_RESTORE_TEMPLATES (JSON).

Restore strategies (partial reveal)

A partial restore reveals a bounded, deterministic fragment of a value instead of the full original. You configure it per entity type under restore_templates.partial_formats (deployment-wide) or per policy under restore_strategies (same shape, policy-scoped). Each entry is keyed by the entity type name, for example credit_card or salary.

restore_templates:
  partial_formats:
    # Reveal only the last n characters, mask the rest.
    credit_card:
      kind: reveal_last_n
      n: 4
      mask_char: "*"
    # Always mask, never reveal.
    ssn:
      kind: mask
    # Generalize a numeric value into a labelled band (e.g. salary bands).
    salary:
      kind: bucket
      ranges:
        - { max: 50000, label: "<50k" }
        - { max: 100000, label: "50k-100k" }
        - { label: "100k+" }   # open-ended top band: omit max

The same per-policy form lives in policy YAML:

restore_strategies:
  credit_card:
    kind: reveal_last_n
    n: 4
    mask_char: "*"

Five kinds are available:

Use restore_strategies in a policy when the format should be scoped to that policy, and restore_templates.partial_formats when the format should apply deployment-wide across policies.

These rules hold:

• Channel-ceiling gated. A partial format applies only when the channel-resolved restore mode is Partial. It never widens what the channel allows: if the channel ceiling is Masked or stricter, the value stays masked regardless of the format.
• Fail closed. If a strategy cannot produce a bounded result, it masks. reveal_last_n masks the whole value when the value is no longer than n. bucket masks when the value does not parse as a number or no range matches.
• Invalid config aborts startup. A reveal_last_n with n outside 1..64, an empty bucket ranges, or a missing required field is rejected at load time, so a misconfigured format cannot silently reveal more than intended.

For the broader extension model (custom entity types, caller-role conditions, custom output channels, detector and language overlays), see the extensibility guide.

Prompt Security

The built-in injection patterns are an immutable floor: English plus a baseline for the canonical attacks (instruction override, system-prompt extraction) in German, French, Spanish, Italian, Portuguese, and Dutch. Config can only add, never remove them. Extend detection to any other language or house style with extra_patterns (each a Rust regex; set case-insensitivity inline with (?i)); an entry that fails to compile is skipped with an error log so the floor still applies.

prompt_security:
  action: strip
  extra_patterns:
    - pattern: '(?i)önceki\s+talimat.{0,20}(?:yok\s*say|unut)'   # Turkish instruction override
      label: "instruction_override (tr)"

File Upload

Request Limits

Operational request limits, each bounded by a built-in maximum. The batch and streaming caps default to their maximum, so they are tighten-only (a DoS ceiling you can only lower). The heavy-op knobs default below their maximum, so they are tunable to your workload up to a built-in safety maximum. A value above its maximum, or zero, aborts startup, so a misconfiguration can never weaken the bound.

PDF text extraction runs in a short-lived child process under a hard RLIMIT_AS address-space cap and a wall-clock timeout, so a decompression-bomb PDF (a small file whose compressed streams inflate to gigabytes) exhausts the bounded child and is rejected with a clean error instead of exhausting the server. Both limits are security ceilings: a deployment may only lower them, and a value above the maximum or zero aborts startup. The raw PDF never leaves the runtime: the sandbox child is a re-exec of the server binary, not an external service.

The address-space cap is a hard fail-closed extraction ceiling. A genuinely large or structurally complex PDF whose extraction would need more than the cap is rejected rather than risk the server, so a small fraction of legitimate documents may be refused. This is deliberate: raising the ceiling above the built-in maximum requires a code change, since config may only lower it.

Rate Limiting

Tenants

Per-tenant overrides allow different policies and rate limits per tenant:

tenants:
  acme-corp:
    default_policy: gdpr-strict
    allowed_policies:
      - gdpr-strict
      - healthcare
    rate_limit:
      requests_per_second: 50
      burst_size: 100

• allowed_policies: Optional allowlist of policy names this tenant may use. When set, request-level policy overrides are validated against this list. If absent or empty, all loaded policies are permitted.
• Unknown tenants fall through to global defaults.
• A misspelled key inside a tenant entry aborts startup, it is not ignored. For example allowed_polcies (a typo of allowed_policies) fails the load rather than leaving the allowlist unset, which would otherwise permit every loaded policy.

RAG access control

The RAG access-control lattice (used to filter document chunks by access_level vs each chunk's classification) defaults to public < internal < confidential < restricted. Override it for your domain scheme without code:

rag:
  classification_levels: ["unclassified", "cui", "confidential", "secret", "top_secret"]

Levels are ordered least to most restrictive. An access level grants a chunk when its rank is greater than or equal to the chunk's. Any label not in the lattice ranks most-restrictive (fail closed), so an unknown or misspelled classification is never over-exposed. The list must be non-empty, unique, and at most 255 entries.

Providers

Per-provider behavior profiles. Each key is a provider name, and its context_strategy sets how much entity context metadata that provider receives. Built-in defaults exist for openai, anthropic, and local; the reserved key default sets the profile used for any provider without an explicit entry. When the providers map is omitted, the built-in defaults apply.

providers:
  openai:
    name: openai
    context_strategy: full
  anthropic:
    name: anthropic
    context_strategy: full
  local:
    name: local
    context_strategy: minimal
  default:
    name: default
    context_strategy: full

Audit

Where audit events are written. Every data-path request produces a PII-free audit event.

audit:
  backend: file
  file:
    path: /var/log/guardai/audit.log
  queue_capacity: 8192
  strict: true

A non-dev start (auth.mode of api_key, jwt, or oidc) requires a durable, strict trail: audit.backend: file AND audit.strict: true. Startup fails otherwise, so a successful request can never have its audit record silently dropped. Set audit.allow_ephemeral: true (or GUARDAI_ALLOW_EPHEMERAL_AUDIT=1) to explicitly accept an ephemeral or non-strict trail. The compliance preset ignores this waiver and always forces durable, strict.

To pin both at once, start the server with the --compliance flag or GUARDAI_COMPLIANCE=1. The compliance preset only tightens: it forces audit.backend: file and audit.strict: true, and it fails closed at startup if the resulting audit trail is not both durable and strict (for example when audit.file.path is unset). It also floors detect.include_values_default to false when the operator has not set it. The gate runs regardless of auth.mode, so it holds even in dev mode. The audit event schema additionally reserves optional GDPR Art. 30 labels (purpose, legal_basis, data_category), PII-free controlled labels a deployment may populate from policy/config; see the compliance controls page.

Revocation and Replay backends

Two top-level backends control session revocation and request-replay protection. Both default to memory and can be switched to redis for a shared store across replicas. A redis backend requires session.redis_url (or GUARDAI_REDIS_URL) and fails startup validation without it.

When running more than one replica, use redis for both so a revoked session and a replayed session_state are recognized on every instance. Redis stores only HMAC digests, never raw PII.

revocation_backend: redis
replay_backend: redis
session:
  redis_url: "redis://redis:6379"

Idempotency

Mutating, non-streaming routes (transform, batch transform, RAG ingest/delete, revoke, session delete) accept an Idempotency-Key header so a client can safely retry without executing the mutation twice. The store is configured under idempotency:

idempotency:
  backend: memory
  ttl_seconds: 86400
  in_progress_ttl_seconds: 60

Environment Variables

Environment variables override configuration file values.

GLINER_LABELS and GLINER_LABEL_MAP set the deployment-wide default label set. A single policy can also request its own semantic NER labels with detection.ner_labels / detection.ner_label_map in its YAML (additive, fail-closed); see the policy authoring guide.

detection.required_for fails a request closed when the required NER backend is unavailable or degraded, and the Rust-side confidence floors exempt required types after detection. It does not override the GLiNER model boundary above: a span the model scores below GLINER_CONFIDENCE_THRESHOLD is never delivered to the policy. A high-recall deployment lowers that threshold.

GUARDAI_SESSION_SECRET

This is the only required environment variable. It has a 16 character minimum and is used for AES-256-GCM encryption of session state blobs. Generate a strong one with openssl rand -base64 32. All server instances in an HA deployment must share the same secret.

# Generate a suitable secret
openssl rand -base64 32

RUST_LOG

Controls log verbosity using the tracing filter syntax:

# Info level for server, debug for session handling
RUST_LOG=guardai_server=info,guardai_session=debug

# Trace everything (very verbose, development only)
RUST_LOG=trace

# Include HTTP request/response logging
RUST_LOG=guardai_server=info,tower_http=info

Example: Minimal Production Config

server:
  host: "0.0.0.0"
  port: 3000
session:
  backend: sealed
  ttl_seconds: 3600
policy:
  default: default
  directory: /etc/guardai/policies
auth:
  mode: api_key            # requires at least one API key (env or auth.api_keys)
audit:
  backend: file            # non-dev requires the durable, strict trail
  strict: true
  file:
    path: /var/log/guardai/audit.log
detector:
  advanced_url: ""

GUARDAI_SESSION_SECRET=$(openssl rand -base64 32)
GUARDAI_API_KEY_1=$(openssl rand -hex 32)
RUST_LOG=guardai_server=info,tower_http=info

Example: Full Stack with NER

server:
  host: "0.0.0.0"
  port: 3000
session:
  backend: sealed
  ttl_seconds: 7200
policy:
  default: default
  directory: /etc/guardai/policies
auth:
  mode: api_key            # requires at least one API key (env or auth.api_keys)
audit:
  backend: file            # non-dev requires the durable, strict trail
  strict: true
  file:
    path: /var/log/guardai/audit.log
transform:
  context_strategy: full
  max_context_tokens: 4096
detector:
  advanced_url: http://detector:9090

GUARDAI_SESSION_SECRET=$(openssl rand -base64 32)
GUARDAI_API_KEY_1=$(openssl rand -hex 32)
GUARDAI_DETECTOR_API_KEY=$(openssl rand -hex 32)   # same value on the detector service
RUST_LOG=guardai_server=info,tower_http=info

Note: For a shared server-side session store across replicas, set session.backend: redis with GUARDAI_REDIS_URL plus replay_backend: redis and revocation_backend: redis. A redis session or replay backend advertises a multi-replica topology, so startup fails closed unless revocation is the shared (redis) authority too. Each session is encrypted at rest (AES-256-GCM). The default sealed backend is stateless and also works for HA, but a multi-replica sealed deployment still needs revocation_backend: redis (advertise it with high_availability: true).