ClaimsAuditor Contract Specification

If you are building a ClaimsAuditor in a language other than Python (not using the Lucid SDK), your container must implement this interface to be compatible with the Lucid Gateway and Lucid Operator.

Required OCI Labels

Your container image must include the following labels in its metadata. The Lucid CLI uses these during the lucid auditor verify step.

Label	Description	Example
io.lucid.auditor	Must be set to true	true
io.lucid.schema_version	The version of the auditor contract	2.0
io.lucid.phase	The primary phase this auditor targets	request, response
io.lucid.interfaces	Comma-separated list of implemented APIs	health,claims,vocabulary

Required Endpoints

The auditor must listen on a configurable port (defaults to 8080) and implement the following REST endpoints.

1. GET /health

Used by the Lucid Operator and Gateway to determine when the auditor is ready to receive traffic.

• Response: 200 OK
• Body: {"status": "healthy", "auditor_id": "my-auditor", "version": "1.0.0", "ready": true}

2. POST /claims

The main entry point for producing claims (observations). The auditor receives data and returns structured claims. It does not make enforcement decisions.

• Request Body:

  {
    "data": {
      "input": "User prompt or request",
      "output": "Model response (for response phase)",
      "metadata": {
        "model_id": "gpt-4",
        "session_id": "sess-123"
      }
    },
    "phase": "request",
    "lucid_context": {
      "trace_id": "trace-789",
      "agent_id": "agent-abc",
      "auditor_config": {}
    }
  }
  

• Response: 200 OK

  {
    "status": "success",
    "claims": [
      {
        "name": "injection_risk",
        "type": "score_normalized",
        "value": 0.42,
        "timestamp": "2026-02-17T12:00:00Z",
        "confidence": 0.95,
        "provenance": {
          "injection_threshold": 0.9
        }
      },
      {
        "name": "secret_leaked",
        "type": "boolean",
        "value": false,
        "timestamp": "2026-02-17T12:00:00Z"
      }
    ]
  }
  

• Error Response: 200 OK (errors are reported in-band)

  {
    "status": "error",
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "Analysis failed",
      "retryable": true
    },
    "claims": []
  }
  

Important: The /claims endpoint must never return decision responses like "status": "blocked" or "status": "deny". ClaimsAuditors only observe and report.

3. GET /vocabulary

Declares the claim names and types this auditor can produce. Used by the Gateway for schema validation and by the policy editor for claim autocomplete.

• Response: 200 OK

  {
    "auditor_id": "my-auditor",
    "version": "1.0.0",
    "vocabulary": [
      {
        "name": "injection_risk",
        "type": "score_normalized",
        "description": "Prompt injection risk score (0.0 = safe, 1.0 = high risk)",
        "value_schema": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "settings": [
          {"key": "injection_threshold", "type": "number", "default": 0.9}
        ]
      },
      {
        "name": "secret_leaked",
        "type": "boolean",
        "description": "Whether credentials or secrets were detected",
        "value_schema": {
          "type": "boolean"
        },
        "settings": [
          {"key": "secret_detectors", "type": "string[]", "default": null}
        ]
      }
    ],
    "phases": ["request", "response"]
  }
  

Claim Format

Each claim in the response array must have the following fields:

Field	Type	Required	Description
name	string	Yes	Flat descriptive claim name (e.g., injection_risk, pii_found)
type	string	Yes	Claim type: score_normalized, boolean, string, string_list, count, duration_ms, object
value	any	Yes	The observation value (must match the declared type)
timestamp	string	No	ISO 8601 timestamp (auto-generated if omitted)
confidence	number	No	Confidence score between 0.0 and 1.0
metadata	object	No	Additional structured context
provenance	object	No	Settings that produced this claim (auto-stamped by @claims decorator)
detail	object	No	Diagnostic data (scanner breakdowns, per-entity results)

Attestation Protocol

To participate in hardware-signed evidence, your auditor runs inside a TEE environment. However, individual auditors do not sign their own claims. The Gateway handles all signing:

1. Gateway collects claims from your auditor via POST /claims
2. Gateway evaluates the Cedar policy against collected claims
3. Gateway bundles all claims + decision into an Evidence container
4. Gateway sends Evidence to the Attestation Agent for TEE signing
5. Signed Evidence is forwarded to the Verifier

[!NOTE] RFC 9334 Compliance: Lucid uses the RATS (Remote ATtestation procedureS) model: - Claim: Typed observation from a ClaimsAuditor (unsigned) - Evidence: Signed container of all Claims + Cedar decision from the Gateway - AttestationResult: Verifier's assessment stored in the AI Passport

[!TIP] Using the SDK is recommended. The Lucid SDK handles all endpoint setup, vocabulary generation, and claim construction automatically via ClaimsAuditor + @claims + serve().