Auditor Configuration Reference

This document describes how to configure Lucid auditors through environment variables, pod annotations, the auditors.yaml manifest, and LucidWorkspace YAML definitions.

LucidWorkspace: Declarative Auditor Configuration

The preferred way to configure auditors is via a LucidWorkspace YAML resource, which declares the complete auditor chain alongside model, app, and policy configuration:

apiVersion: lucid.io/v1alpha1
kind: LucidWorkspace
metadata:
  name: my-workspace
spec:
  model:
    id: qwen3-8b
  app:
    id: open-webui
  auditorChain:
    preRequest:
      - auditorId: lucid-guardrails-auditor
        policyRef: pol-guardrails-input
      - auditorId: lucid-pii-compliance-auditor
        policyRef: pol-pii-gdpr
    postResponse:
      - auditorId: lucid-watermark-auditor
  policies:
    - policyId: pol-guardrails-input
      version: "1.0.0"
      name: Input Guardrails
      verificationMethod: lucid-guardrails-auditor
      requiredClaims:
        - name: guardrails.input_safe
          type: score_binary
          required: true
          minConfidence: 0.8
      rules:
        - id: injection-block
          condition: "claims['guardrails.risk_score'].value > 0.7"
          action: deny
          message: "Request blocked"
      enforcement: block

Deploy with: lucid apply -f workspace.yaml

See the LucidWorkspace schema for the full specification.

Legacy Configuration Methods

The methods below configure auditors at the infrastructure level. For new deployments, prefer LucidWorkspace for a unified, portable configuration.

Configuration Precedence

Configuration values are resolved in the following order (highest priority first):

Environment Variables - Highest priority, overrides all other sources
Pod Annotations - Kubernetes pod-level configuration
auditors.yaml Manifest - Policy-as-code definitions
Hardcoded Defaults - Fallback values in auditor code

Configuration Methods

1. Environment Variables

Environment variables are the primary configuration method for auditors.

# In auditors.yaml
chain:
  - name: lucid-guardrails-auditor
    image: "lucid-guardrails-auditor:latest"
    port: 8090
    env:
      INJECTION_THRESHOLD: "0.8"
      INJECTION_BLOCK_ON_DETECTION: "true"

2. Pod Annotations

Kubernetes pod annotations allow per-workload configuration:

apiVersion: v1
kind: Pod
metadata:
  labels:
    lucid.io/secured: "true"
  annotations:
    lucid.computing/auditors: "injection,toxicity"
    lucid.computing/injection-threshold: "0.9"
    lucid.computing/toxicity-block: "true"
spec:
  containers:
    - name: my-llm
      image: my-llm:latest

Supported annotations:

Annotation	Description	Default
`lucid.computing/auditors`	Comma-separated list of auditors	`""`
`lucid.computing/audit-mode`	Audit mode (`enforce`, `observe`)	`enforce`
`lucid.computing/skip-audit`	Skip auditing for this pod	`false`

3. Auditors YAML Manifest

Define your audit chain in auditors.yaml:

chain:
  - name: string          # Unique name for the auditor instance
    description: string   # (Optional) Description
    image: string         # OCI image tag
    port: integer         # Internal port (e.g., 8090)
    env:                  # Environment variables
      KEY: VALUE

4. Auditor Catalog (`auditors.yaml`)

The auditor catalog at deploy/applications/catalog/auditors.yaml is the single source of truth for all auditor definitions. It drives both the backend API and the Observer UI's auditor configuration forms.

Each auditor entry supports the following fields:

Field	Type	Description
`id`	string	Unique auditor identifier (e.g., `lucid-guardrails-auditor`)
`name`	string	Human-readable display name
`description`	string	Detailed description
`category`	enum	One of: `security`, `compliance`, `observability`, `evaluation`, `provenance`
`phase`	enum	Pipeline phase: `artifact_safety`, `input_guarding`, `execution_monitoring`, `output_policy`
`icon`	string	Lucide icon name for the UI
`color`	string	Color theme for the UI
`defaultPort`	integer	Default container port
`envVariables`	list	Environment variable definitions (see below)
`policyOptions`	list	UI-driven policy option definitions (see below)
`defaultPolicy`	object	Default policy with rules and enforcement mode

Policy Options

The policyOptions array defines the configuration form rendered in the Observer UI when editing an auditor's policy settings. Each option generates a form control:

policyOptions:
  - key: injectionThreshold     # Key used in the policy dict
    label: "Injection Threshold" # Display label
    description: ""              # Optional help text
    type: number                 # Input type: number | boolean | string | select
    default: "0.9"              # Default value (as string)
    min: 0                      # Min value (number type only)
    max: 1                      # Max value (number type only)
    step: 0.1                   # Step increment (number type only)
  - key: blockOnInjection
    label: "Block on injection detection"
    type: boolean
    default: "true"
  - key: piiAction
    label: "PII Action"
    type: select
    default: "redact"
    options:                    # Choices (select type only)
      - "redact"
      - "block"
      - "warn"

Option Type	Rendered As	Extra Fields
`number`	Number input	`min`, `max`, `step`
`boolean`	Checkbox	—
`string`	Text input	—
`select`	Dropdown	`options` (list of choices)

Policy option values are persisted in the agent's auditChain[phase][instance].policy object and sent to the auditor at runtime.

Common Auditor Configuration

These variables are common across all auditors:

Variable	Default	Description
`PORT`	varies	Server port (8090-8098 depending on auditor)
`LUCID_AUDITOR_ID`	varies	Unique auditor identifier
`LUCID_SESSION_ID`	`demo-session`	Session identifier for audit logs

Injection Auditor

Port: 8090

Variable	Default	Description
`INJECTION_THRESHOLD`	`0.8`	Detection threshold (0.0-1.0). Higher = more strict.
`INJECTION_BLOCK_ON_DETECTION`	`true`	Block requests when injection is detected.
`INJECTION_BAN_SUBSTRINGS`	`ignore previous,...`	Comma-separated list of banned substrings.
`INJECTION_MAX_TOKEN_LIMIT`	`4096`	Maximum tokens allowed in input.
`INJECTION_INVISIBLE_CHAR_CHECK`	`true`	Check for invisible/zero-width Unicode characters.
`INJECTION_TOXICITY_THRESHOLD`	`0.7`	Toxicity score threshold for flagging.

Toxicity Auditor

Port: 8093

Detection Thresholds

Variable	Default	Description
`TOXICITY_MODEL`	`unitary/toxic-bert`	Toxicity detection model.
`TOXICITY_THRESHOLD`	`0.7`	Overall toxicity threshold (0.0-1.0).
`TOXICITY_SEVERE_THRESHOLD`	`0.5`	Severe toxicity threshold.
`TOXICITY_THREAT_THRESHOLD`	`0.6`	Threat detection threshold.
`TOXICITY_INSULT_THRESHOLD`	`0.7`	Insult detection threshold.
`TOXICITY_IDENTITY_ATTACK_THRESHOLD`	`0.5`	Identity attack threshold.

Behavior

Variable	Default	Description
`TOXICITY_BLOCK_ON_DETECTION`	`true`	Block response on detection.
`TOXICITY_REPLACEMENT_MESSAGE`	`Content filtered for safety`	Replacement text for blocked content.
`TOXICITY_MULTILINGUAL`	`true`	Enable multilingual toxicity detection.

Eval Auditor

Port: 8091

Variable	Default	Description
`EVAL_BENCHMARK_SUITE`	`wmdp,harmbench,truthfulqa`	Comma-separated benchmarks to run.
`EVAL_SAFETY_THRESHOLD`	`0.85`	Minimum weighted safety score (0.0-1.0).
`EVAL_DANGEROUS_CAP_THRESHOLD`	`0.15`	Maximum dangerous capability score (0.0-1.0).
`EVAL_MAX_SAMPLES_PER_BENCHMARK`	`1000`	Maximum samples per benchmark.
`EVAL_TIMEOUT_SECONDS`	`3600`	Total evaluation timeout in seconds.
`EVAL_PARALLEL_WORKERS`	`4`	Number of parallel evaluation workers.

Observability Auditor

Port: 8092

Core Tracing

Variable	Default	Description
`TRACE_ENABLED`	`true`	Enable/disable tracing.
`TRACE_SAMPLE_RATE`	`1.0`	Sampling rate (0.0-1.0).
`TRACE_CAPTURE_INPUT`	`true`	Capture input prompts.
`TRACE_CAPTURE_OUTPUT`	`true`	Capture model outputs.
`TRACE_SIGN_IN_TEE`	`true`	Sign traces in TEE for immutability.
`TRACE_RETENTION_DAYS`	`90`	Trace retention period in days.

Cost Tracking

Variable	Default	Description
`TRACE_COST_TRACKING`	`true`	Enable cost tracking.
`TRACE_COST_MODEL`	`gpt-4:0.03,gpt-3.5:0.002`	Cost per 1K tokens (format: `model:price,...`).

SOC2 Auditor

Port: 8094

PII Detection

Variable	Default	Description
`SOC2_PII_DETECTION_ENABLED`	`true`	Enable PII detection scanning.
`SOC2_PII_BLOCK_ON_DETECTION`	`false`	Block request entirely when PII detected.
`SOC2_PII_REDACT_ON_DETECTION`	`true`	Redact PII and allow request to proceed.

Compliance

Variable	Default	Description
`SOC2_CONFIDENTIAL_MARKERS`	`confidential,internal only,...`	Comma-separated confidentiality markers.
`SOC2_LOG_ALL_REQUESTS`	`true`	Log all requests for audit trail.
`SOC2_DATA_RETENTION_DAYS`	`90`	Audit log retention period in days.

Sovereignty Auditor

Port: 8095

Location Verification

Variable	Default	Description
`SOVEREIGNTY_ALLOWED_REGIONS`	`US,EU,UK`	Comma-separated allowed jurisdiction codes.
`SOVEREIGNTY_MIN_CONFIDENCE`	`0.7`	Minimum confidence score (0.0-1.0).
`SOVEREIGNTY_BLOCK_ON_VIOLATION`	`true`	Block requests on sovereignty violation.

Text Watermark Auditor

Port: 8096

Embeds statistical watermarks into LLM token generation for provenance verification.

Variable	Default	Description
`TEXT_WATERMARK_ALGORITHM`	`kgw`	Watermark algorithm: `kgw`, `sweet`, `unigram`, `dipmark`.
`TEXT_WATERMARK_GREENLIST_RATIO`	`0.25`	Fraction of vocabulary in greenlist (0.0-0.5).
`TEXT_WATERMARK_BIAS`	`2.0`	Logit bias applied to greenlist tokens.
`TEXT_WATERMARK_DETECTION_THRESHOLD`	`0.5`	Minimum z-score for watermark detection.
`TEXT_WATERMARK_INCLUDE_IN_PASSPORT`	`true`	Include watermark proof in AI Passport.

Image Watermark Auditor

Port: 8097

Embeds C2PA Content Credentials and invisible TrustMark watermarks into AI-generated images.

Variable	Default	Description
`IMAGE_WATERMARK_C2PA_ENABLED`	`true`	Enable C2PA manifest embedding.
`IMAGE_WATERMARK_TRUSTMARK_ENABLED`	`true`	Enable invisible TrustMark watermark.
`IMAGE_WATERMARK_SUPPORTED_FORMATS`	`png,jpeg,webp`	Comma-separated supported formats.
`IMAGE_WATERMARK_PRESERVE_QUALITY`	`true`	Minimize quality degradation.

Video Watermark Auditor

Port: 8098

Variable	Default	Description
`VIDEO_WATERMARK_C2PA_ENABLED`	`true`	Enable C2PA manifest embedding.
`VIDEO_WATERMARK_FRAME_WATERMARK_ENABLED`	`true`	Enable per-frame watermarks.
`VIDEO_WATERMARK_FRAME_INTERVAL`	`30`	Frames between watermark refresh.
`VIDEO_WATERMARK_SUPPORTED_FORMATS`	`mp4,webm,mov`	Comma-separated supported formats.

Deployment Type Configuration

The deployment_type field on an environment spec determines which components are provisioned. Set it at the top level of the spec:

apiVersion: lucid.io/v1alpha1
kind: LucidEnvironment
metadata:
  name: my-backend
spec:
  deployment_type: model  # full | model | app | bridge
  agents:
    - name: backend-llm
      model:
        id: meta-llama/Llama-3.3-70B

Value	Components Provisioned	Description
`full`	Model + App + Auditors	Traditional end-to-end deployment (default)
`model`	Model + Auditors	Headless API backend, no user-facing app
`app`	App only	Frontend that receives LLM backend from a workflow
`bridge`	Protocol adapter + Auditors	Webhook-to-OpenAI translator (e.g., Chatwoot)

See the Deployment Modes guide for usage patterns.

Workflow API Endpoints

Workflows are managed through the Verifier API. Key endpoints:

Method	Endpoint	Description
`POST`	`/api/v1/workflows`	Create a new workflow
`GET`	`/api/v1/workflows`	List all workflows
`GET`	`/api/v1/workflows/{id}`	Get workflow details
`PUT`	`/api/v1/workflows/{id}`	Update workflow graph
`POST`	`/api/v1/workflows/{id}/deploy`	Deploy a workflow
`POST`	`/api/v1/workflows/{id}/stop`	Stop a running workflow
`GET`	`/api/v1/workflows/{id}/passport`	Get composite workflow passport

See the Workflows concept page for schema details.

MCP Environment Variables

Environment variables for configuring MCP tool exposure and the MCP Gateway.

Per-Service MCP Configuration

Variable	Default	Description
`MCP_ENABLED`	`true`	Enable or disable the `/mcp` endpoint on a service
`MCP_TOOLS_PATH`	`/mcp`	Path where MCP tools are served
`MCP_METADATA_PATH`	`/.well-known/mcp`	Path for MCP tool discovery metadata
`MCP_MAX_CONCURRENT_CALLS`	`10`	Maximum concurrent MCP tool invocations

MCP Gateway Configuration

Variable	Default	Description
`MCP_GATEWAY_ENABLED`	`true`	Enable the MCP Gateway service
`MCP_GATEWAY_PORT`	`8100`	Port for the MCP Gateway
`MCP_GATEWAY_OAUTH_ISSUER`	`""`	OAuth 2.1 issuer URL for external client auth
`MCP_GATEWAY_MTLS_ENABLED`	`true`	Require mTLS for internal service-to-service calls
`MCP_GATEWAY_DISCOVERY_INTERVAL`	`30`	Seconds between service discovery refreshes

See the MCP concept page for architecture details.

Best Practices

Use environment variables for configuration - Easy to override per-deployment
Set thresholds based on your use case - More sensitive applications need stricter thresholds
Enable logging - Audit trails are essential for compliance
Test in observe mode first - Use audit-mode: observe to monitor before enforcing
Use deployment_type explicitly - Avoid relying on the full default when composing workflows
Secure the MCP Gateway - Always configure MCP_GATEWAY_OAUTH_ISSUER in production