Audit Logging & Provenance

The predicate-authorityd sidecar generates a cryptographic proof event for every authorization mandate it issues or denies. How you handle these events depends on your environment.

Local Sidecar Logging (Default)

By default, the sidecar writes verification events and mandate receipts to a local queue file. This mode is designed for local development, single-agent testing, and CI/CD pipeline debugging.

predicate-authorityd \
  --local-identity-enabled \
  --local-identity-registry-file ./.predicate-authorityd/local-identities.json

Local queue endpoints:

• GET /ledger/flush-queue - List pending audit events
• GET /ledger/dead-letter - List quarantined events
• POST /ledger/flush-now - Trigger immediate flush
• POST /ledger/requeue - Retry a quarantined event

Ephemeral by Design

Local sidecar logs are deliberately ephemeral:

• 24-hour TTL: Queue items auto-expire after 24 hours by default
• Payload redaction: Sensitive fields (principal_id, action, resource) are redacted in API responses
• No aggregation API: Each sidecar is isolated; no cross-node query capability

# Configure TTL (default: 86400 seconds / 24 hours)
--queue-item-ttl-seconds 86400

This design reflects the operational reality of distributed systems, not an artificial limitation.

Constraints in Distributed Environments

Relying on isolated sidecar logs in a production, multi-agent fleet introduces strict operational constraints:

Building a compliant audit pipeline from ephemeral sidecar logs requires:

• Log forwarding infrastructure (FluentBit, Logstash, Vector)
• Centralized storage with WORM guarantees (S3 Object Lock, Azure Immutable Blob)
• Custom indexing for principal_id, intent_hash, mandate_id queries
• Merkle tree implementation for tamper-evident integrity proofs
• Retention policy enforcement and legal hold workflows

Production Governance: Predicate Audit Vault

For production workloads, connect sidecars to the Predicate Control Plane. Instead of writing to local disk, the sidecar streams signed proof events directly into the Audit Vault.

predicate-authorityd \
  --mode cloud_connected \
  --control-plane-enabled \
  --control-plane-tenant-id "your-tenant" \
  --control-plane-project-id "your-project"

Capabilities

Integrity verification

Verify any audit event is included in the tenant's tamper-evident log:

# Get current Merkle root
curl -s "https://api.predicatesystems.dev/v1/audit/integrity/root?tenant_id=your-tenant" \
  -H "Authorization: Bearer $TOKEN" | jq

# Get inclusion proof for specific event
curl -s "https://api.predicatesystems.dev/v1/audit/integrity/proof/<event_id>?tenant_id=your-tenant" \
  -H "Authorization: Bearer $TOKEN" | jq

Audit exports

Export audit events for compliance reporting or external analysis:

# Create export job
curl -s -X POST "https://api.predicatesystems.dev/v1/audit/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "your-tenant",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-31T23:59:59Z",
    "format": "jsonl"
  }' | jq

# Download completed export
curl -s "https://api.predicatesystems.dev/v1/audit/exports/<export_id>/download" \
  -H "Authorization: Bearer $TOKEN" -o audit-export.jsonl.gz

Choosing Your Audit Strategy