Evidence Service Audit Trails

This guide covers the Evidence Service (SDS-043) for maintaining tamper-evident audit trails.

1. Overview

The Evidence Service provides:

2. Architecture

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

┌───────────────────────────────────────────────────────────────────────────────┐
│                          EVIDENCE SERVICE ARCHITECTURE                        │
├───────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│   Service Events → Event Buffer → Hash Generation → Merkle Tree → Storage    │
│                                                                               │
│   ┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────────┐   │
│   │ API Request│    │ Policy     │    │ LLM        │    │ Privileged     │   │
│   │ Events     │    │ Violations │    │ Interactions│   │ Actions        │   │
│   └────────────┘    └────────────┘    └────────────┘    └────────────────┘   │
│         ↓                 ↓                 ↓                  ↓              │
│   ┌──────────────────────────────────────────────────────────────────────┐   │
│   │                    SHA256 Hash Chain + Merkle Root                    │   │
│   └──────────────────────────────────────────────────────────────────────┘   │
│         ↓                                                                     │
│   ┌──────────────────────────────────────────────────────────────────────┐   │
│   │                    Immutable Storage (7 years)                        │   │
│   └──────────────────────────────────────────────────────────────────────┘   │
│                                                                               │
└───────────────────────────────────────────────────────────────────────────────┘

3. Event Types

3.1 Standard Events

Event Type Fields Retention
api_request timestamp, actor, method, resource, status 7 years
api_response timestamp, request_id, status, duration 7 years
authentication timestamp, actor, method, success 7 years
authorization timestamp, actor, resource, decision 7 years

3.2 Governance Events

Event Type Fields Retention
policy_violation timestamp, policy, violation_type, context, severity 7 years
policy_decision timestamp, policy, decision, reasoning 7 years
governance_alert timestamp, alert_type, details, recipients 7 years

3.3 AI-Specific Events

Event Type Fields Retention
llm_request timestamp, prompt_hash, model, tokens, filters_applied 7 years
llm_response timestamp, response_hash, model, tokens, filtered 7 years
model_decision timestamp, model, decision, confidence, features 7 years
bias_alert timestamp, model, metric, value, threshold 7 years

4. Logging Events

4.1 Automatic Logging

Events are automatically logged when governance is enabled:

1
2
3
4
5
6
7
8

# In SDS
governance:
  evidence_service:
    enabled: true
    events:
      - api_request
      - policy_violation
      - llm_interaction

4.2 Manual Logging

1
2
3
4
5
6
7
8
9
10
11

# Python example
from sea_forge.evidence import log_event

log_event(
    event_type="custom_event",
    actor="service-a",
    action="data_export",
    resource="customer-records",
    context={"format": "csv", "record_count": 1500},
    justification="Monthly reporting requirement"
)

1
2
3
4
5
6
7
8
9
10
11

// TypeScript example
import { logEvent } from '@sea-forge/evidence';

await logEvent({
  eventType: 'custom_event',
  actor: 'service-a',
  action: 'data_export',
  resource: 'customer-records',
  context: { format: 'csv', recordCount: 1500 },
  justification: 'Monthly reporting requirement'
});

5. Querying Logs

5.1 Basic Queries

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Recent events
curl http://localhost:8083/api/v1/logs \
  -d '{"limit": 100}'

# Filter by type
curl http://localhost:8083/api/v1/logs \
  -d '{"event_type": "policy_violation"}'

# Filter by time range
curl http://localhost:8083/api/v1/logs \
  -d '{"start": "2026-01-01T00:00:00Z", "end": "2026-01-31T23:59:59Z"}'

# Filter by actor
curl http://localhost:8083/api/v1/logs \
  -d '{"actor": "user-123"}'

5.2 Advanced Queries

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Multiple filters
curl http://localhost:8083/api/v1/logs \
  -d '{
    "event_type": "llm_interaction",
    "start": "2026-01-01",
    "filters": {
      "model": "gpt-4",
      "filtered": true
    },
    "limit": 1000
  }'

# Aggregations
curl http://localhost:8083/api/v1/logs/aggregate \
  -d '{
    "group_by": "event_type",
    "metrics": ["count", "avg_duration"],
    "start": "2026-01-01"
  }'

6. Integrity Verification

6.1 Verify Single Event

1
2
3
4
5
6
7
8
9
10
11

curl http://localhost:8083/api/v1/verify \
  -d '{"event_id": "evt-abc123"}'

# Response:
# {
#   "event_id": "evt-abc123",
#   "hash": "sha256:abcd1234...",
#   "merkle_proof": [...],
#   "verified": true,
#   "timestamp": "2026-01-15T10:30:00Z"
# }

6.2 Verify Time Range

1
2
3
4
5
6
7
8
9
10

curl http://localhost:8083/api/v1/verify/range \
  -d '{"start": "2026-01-01", "end": "2026-01-31"}'

# Response:
# {
#   "range": {"start": "...", "end": "..."},
#   "events_count": 15234,
#   "merkle_roots": [...],
#   "all_verified": true
# }

6.3 Export for External Audit

1
2
3
4
5
6
7
8

# Export with proof chain
curl http://localhost:8083/api/v1/export \
  -d '{
    "start": "2026-01-01",
    "end": "2026-03-31",
    "include_proofs": true,
    "format": "json"
  }' > audit_export_q1_2026.json

7. Compliance Reporting

7.1 Pre-Built Reports

1
2
3
4
5
6
7
8
9
10
11

# NIST AI RMF compliance report
curl http://localhost:8083/api/v1/reports/compliance \
  -d '{"framework": "NIST-AI-RMF", "period": "Q1-2026"}'

# GDPR data access report
curl http://localhost:8083/api/v1/reports/data-access \
  -d '{"subject": "user-123", "period": "2026"}'

# Policy violation summary
curl http://localhost:8083/api/v1/reports/violations \
  -d '{"period": "2026-01", "severity": ["high", "critical"]}'

7.2 Custom Reports

1
2
3
4
5
6
7
8
9
10
11

# Custom query for audit
curl http://localhost:8083/api/v1/reports/custom \
  -d '{
    "name": "FinanceAudit2026",
    "filters": {
      "resource_pattern": "finance/*",
      "event_types": ["api_request", "policy_decision"]
    },
    "period": "2026",
    "format": "xlsx"
  }' > finance_audit_2026.xlsx

8. Retention Management

8.1 Retention Policy

1
2
3
4
5
6
7
8
9
10
11
12

# Default retention by event type
retention:
  default: 7_years
  
  overrides:
    system_health: 1_year
    debug_logs: 30_days
    
  archive:
    enabled: true
    after: 1_year
    destination: s3://archive-bucket/evidence/

1
2
3
4
5
6

# Place legal hold (prevents deletion)
curl -X POST http://localhost:8083/admin/legal-hold \
  -d '{"matter": "Case-2026-001", "filters": {"actor": "user-456"}}'

# Release hold
curl -X DELETE http://localhost:8083/admin/legal-hold/Case-2026-001

9. Security

9.1 Access Control

1
2
3
4
5
6
7
8
9
10
11
12

# Role-based access
access_control:
  roles:
    auditor:
      read: true
      write: false
      verify: true
    admin:
      read: true
      write: true
      verify: true
      manage: true

9.2 Key Rotation

1
2
3
4
5
6

# Rotate signing keys (monthly recommended)
curl -X POST http://localhost:8083/admin/rotate-keys \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

# Verify rotation
curl http://localhost:8083/admin/keys/status

10. Integration with SDS-035 Invariants

The Evidence Service enforces these SDS-035 invariants:

Invariant Implementation
#13: Tamper-evident logs SHA256 + Merkle tree
#14: Key rotation Automated monthly rotation
#15: Fail-closed Unknown events blocked
Last Updated: January 2026 Version: 1.0.0