Service Configuration

The AI Guard service is configured via a YAML file. All values support shell-style environment variable expansion using ${VAR} syntax, which is resolved at startup.

Configuration File

The default configuration is located at /etc/ai-guard/config.yaml inside the Docker image. Override it by mounting a custom config file or setting environment variables.

Environment Variable Syntax

Syntax	Behavior
`${VAR}`	Replaced with the value of `VAR`. If `VAR` is unset, the server exits with an error.
`${VAR:-default}`	Replaced with the value of `VAR`. If `VAR` is unset, uses `default`.

This makes it straightforward to parameterize a single config file across environments.

Configuration Reference

Service Section

Config Path	Env Var	Default	Description
`service.timeout`	—	`10`	HTTP request timeout in seconds
`service.listen`	`AI_GUARD_SERVICE_PORT`	`0.0.0.0:4443`	Server listen address and port

Authorization Section

See Authentication & Authorization for full details.

Config Path	Env Var	Default	Description
`service.authorization.type`	—	`onetrust`	Authorization mode: `onetrust` or `shared-secret`

TLS Section

See TLS & Certificate Pinning for full details.

Config Path	Env Var	Default	Description
`service.tls.key-path`	`TLS_KEY_PATH`	`/etc/ssl/litenode/tls.key`	TLS private key path (PEM)
`service.tls.certificate-path`	`CERTIFICATE_PATH`	`/etc/ssl/litenode/tls.crt`	TLS certificate path (PEM)

📘
Disabling TLS
If the tls section is omitted from the config file, the server falls back to plain HTTP. You can also pass the --no-tls CLI flag to explicitly disable TLS.

Classification Section

Config Path	Env Var	Default	Description
`classification.min-allowed-likelihood`	—	`LIKELY`	Minimum confidence threshold for classification matches
`classification.client.type`	—	`client`	Classification client type: `client` (HTTP) or `fs` (file-based)
`classification.client.classifier-base-url`	`JOB_EXECUTOR_BASE_URL`	`http://scan-job-manager:8080`	URL or path for classification profiles

Classification Client Types

Type	Description
`fs`	File-based classifiers loaded from a local path
`client`	HTTP client connecting to a remote OneTrust classifier service

Metrics Section

See Metrics Exporters for full details.

Config Path	Env Var	Default	Description
`metrics.allowed-attributes`	—	—	Optional additional attribute keys beyond `agent_id` and `platform`
`metrics.exporter.type`	—	`onetrust`	Exporter type: `onetrust` or `otlp`
`metrics.exporter.collector-endpoint`	`DATADISCOVERY_ONPREM_AGENT_URI`	`http://datadiscovery-onprem-agent:8080`	Metrics collector endpoint
`metrics.exporter.interval`	`METRICS_EXPORT_INTERVAL`	`hour`	Export interval

📘
Disabling Metrics
If the metrics section is omitted entirely, metrics collection is disabled and POST /metric will return 400 Bad Request.

Complete Configuration Example

service:
  timeout: 10
  listen: 0.0.0.0:${AI_GUARD_SERVICE_PORT:-4443}
  authorization:
    type: onetrust
    validation-endpoint: "${OT_SERVICE_BASE_URL}/api/label-manager/v2/custom-classifiers?searchTerm=4a72ec89d3b4798c"
    initial-backoff: 0.15
    max-retry-duration: 2.0
    cache-max-capacity: 1000
    cache-ttl: 300
  tls:
    key-path: "${TLS_KEY_PATH}"
    certificate-path: "${CERTIFICATE_PATH}"

classification:
  min-allowed-likelihood: LIKELY
  client:
    type: client
    classifier-base-url: "${JOB_EXECUTOR_BASE_URL:-http://scan-job-manager:8080}"

metrics:
  exporter:
    type: onetrust
    collector-endpoint: "${DATADISCOVERY_ONPREM_AGENT_URI:-http://datadiscovery-onprem-agent:8080}"
    interval: ${METRICS_EXPORT_INTERVAL:-hour}
    initial-backoff: 0.15
    max-retry-duration: 30.0

Debugging — Trusted Root Overrides

These optional settings allow overriding the CA certificate and endpoint address for each outbound connection. Useful for debugging TLS issues, routing through proxies, or testing against alternate endpoints.

Config Path	Env Var	Description
`service.authorization.trusted-root-path`	`VALIDATION_ENDPOINT_TRUSTED_ROOT_PATH`	PEM CA cert for validation endpoint
`service.authorization.trusted-root-address`	`VALIDATION_ENDPOINT_TRUSTED_ROOT_ADDRESS`	Override host:port for validation endpoint
`classification.client.trusted-root-path`	`JOB_EXECUTOR_ENDPOINT_TRUSTED_ROOT_PATH`	PEM CA cert for scan job manager
`classification.client.trusted-root-address`	`JOB_EXECUTOR_ENDPOINT_TRUSTED_ROOT_ADDRESS`	Override host:port for scan job manager
`metrics.exporter.trusted-root-path`	`METRICS_ENDPOINT_TRUSTED_ROOT_PATH`	PEM CA cert for collector endpoint
`metrics.exporter.trusted-root-address`	`METRICS_ENDPOINT_TRUSTED_ROOT_ADDRESS`	Override host:port for collector endpoint

Logging

Logs are formatted using Elastic Common Schema (ECS) format. Log level is controlled by the RUST_LOG environment variable:

RUST_LOG=info   # Default
RUST_LOG=debug  # Verbose logging for troubleshooting
RUST_LOG=warn   # Reduced logging

What's Next?

Authentication & Authorization — Configure authorization modes
TLS & Certificate Pinning — Configure TLS and certificate pinning
Classification Profiles — Configure classification profiles