Auditor Contract Specification

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

🏷️ 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	1.0
io.lucid.phase	The primary phase this auditor targets	request, response
io.lucid.interfaces	comma-separated list of implemented APIs	health,audit

📡 Required Endpoints

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

1. GET /health

Used by the Lucid Operator to determine when the sidecar is ready to receive traffic. - Response: 200 OK - Body: {"status": "ok"}

2. POST /audit

The main entry point for safety checks. - Request Body: The data to be audited (varies by phase). - Responses: - 200 OK: Data passed the audit. - Body: {"status": "proceed", "modifications": {}} - 200 OK: Data should be redacted. - Body: {"status": "redact", "modifications": {"key": "masked_val"}} - 200 OK: Data is dangerous and must be blocked. - Body: {"status": "deny", "message": "Reason for denial"}

🔏 Attestation Protocol

To produce hardware-signed evidence, your auditor must communicate with the local Attestation Agent (usually listening on http://localhost:8006).

For every audit decision, you should: 1. Generate a Measurement JSON. 2. Send the blob to the Attestation Agent for signing. 3. Forward the signed evidence to the Lucid Verifier.

[!TIP] Using the SDK is recommended. The Lucid SDK handles all label generation, endpoint setup, and attestation signing automatically.