> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://developer.onetrust.com/onetrust/docs/ai-guard-authentication) 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](https://developer.onetrust.com/onetrust/docs/ai-guard-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](https://developer.onetrust.com/onetrust/docs/ai-guard-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

```yaml
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)](https://www.elastic.co/guide/en/ecs/current/index.html) format. Log level is controlled by the `RUST_LOG` environment variable:

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

## What's Next?

* [Authentication & Authorization](https://developer.onetrust.com/onetrust/docs/ai-guard-authentication) — Configure authorization modes
* [TLS & Certificate Pinning](https://developer.onetrust.com/onetrust/docs/ai-guard-tls-certificate-pinning) — Configure TLS and certificate pinning
* [Classification Profiles](https://developer.onetrust.com/onetrust/docs/ai-guard-classification-profiles) — Configure classification profiles