Why TrailProof?
The legacy audit backend (Attesta’s built-in logger) provides basic hash-chaining and verification. TrailProof adds:- HMAC signatures for cryptographic provenance
- Multi-tenancy isolation via tenant IDs
- Trace correlation for distributed workflows
- Cursor-based pagination for large audit logs
- Pluggable storage (in-memory or JSONL)
- Production-grade features maintained as a dedicated library
Both backends are fully supported. The legacy backend remains the default and will continue to receive updates. TrailProof is optional and requires an additional package installation.
Installation
TrailProof is an optional dependency. Install it alongside Attesta:Configuration
Enable TrailProof by settingaudit.backend in your attesta.yaml:
attesta.yaml
| Field | Required | Default | Description |
|---|---|---|---|
backend | No | legacy | Backend type: legacy or trailproof |
path | No | .attesta/audit.jsonl | File path for the JSONL audit log |
tenant_id | No | default | Tenant identifier for multi-tenancy isolation |
hmac_key | No | None | HMAC signing key for cryptographic provenance |
Field Mapping
TrailProof uses a 10-field event envelope. Attesta audit fields are mapped as follows:| Attesta Field | TrailProof Field | Notes |
|---|---|---|
entry_id | event_id | Auto-generated by TrailProof |
| (derived) | event_type | Set to attesta.approval.{verdict} (e.g., attesta.approval.approved) |
intercepted_at | timestamp | Auto-generated by TrailProof |
agent_id | actor_id | Direct mapping; defaults to "unknown" if not set |
| (config) | tenant_id | Set once at backend initialization from config |
session_id | session_id | Direct mapping |
| (hints) | trace_id | Optional, passed through ActionContext.hints |
| All other fields | payload | Bundled into payload: action_name, risk_score, risk_level, challenge_type, verdict, metadata, etc. |
| (internal) | prev_hash | Managed by TrailProof |
| (internal) | hash | Managed by TrailProof |
| (if HMAC key set) | signature | Managed by TrailProof |
Event Type Convention
Theevent_type field follows the pattern attesta.approval.{verdict}, producing values like:
attesta.approval.approvedattesta.approval.deniedattesta.approval.auto_approvedattesta.approval.timed_out
Usage Examples
Python
TypeScript
Verifying Integrity
TrailProof provides the same verification guarantees as the legacy backend, but uses its own hash-chaining and signature algorithms.What Verification Detects
| Tampering Type | Detection |
|---|---|
| Modified entry | Hash mismatch at the modified entry |
| Deleted entry | Hash mismatch at the entry after the deleted one |
| Inserted entry | Hash mismatch at the inserted entry |
| Reordered entries | Hash mismatch at every reordered position |
| Signature forgery | HMAC signature verification fails (if signing is enabled) |
Querying Events
TrailProof provides a query API that supports filtering by actor, tenant, event type, and more. The Attesta backend adapter exposes a simplified query interface:For advanced queries (filtering by tenant, trace, cursor-based pagination), use the TrailProof library directly. The Attesta backend adapter provides a simplified interface for common use cases.
Multi-Tenancy
TrailProof supports multi-tenancy isolation via tenant IDs. All events logged by a TrailProof backend are tagged with thetenant_id configured at initialization.
attesta.yaml
- Store audit logs for multiple tenants in the same file
- Filter events by tenant in queries
- Maintain separate integrity chains per tenant
HMAC Signing
TrailProof supports HMAC signatures for cryptographic provenance. When you provide anhmac_key, every event is signed with HMAC-SHA256, and verification checks both hash integrity and signature validity.
attesta.yaml
Migration from Legacy Backend
Audit trails are stored as independent JSONL files. When you switch fromlegacy to trailproof, Attesta will start writing to a new TrailProof-formatted log. Your existing legacy audit log remains intact and can still be verified using the LegacyBackend.
Migration Strategy
-
Keep both logs during transition:
Your old
.attesta/audit.jsonlremains unchanged. -
Verify the legacy log one last time:
- Archive the legacy log to immutable storage.
- Switch to TrailProof for all new events.
There is no automatic migration tool to convert legacy JSONL entries into TrailProof format. The two backends use different field structures and hash algorithms. If you need to analyze both logs together, export them to a common format (CSV, JSON) using Attesta’s exporter utilities.
Comparison: Legacy vs TrailProof
| Feature | Legacy Backend | TrailProof Backend |
|---|---|---|
| Hash-chaining | SHA-256 | SHA-256 |
| HMAC signatures | No | Yes (optional) |
| Multi-tenancy | No | Yes |
| Trace correlation | No | Yes |
| Cursor-based pagination | No | Yes |
| Storage format | JSONL | JSONL |
| Verification API | verify_chain() | verify() |
| Query API | Basic filtering | Advanced filtering + cursors |
| Dependencies | Zero | TrailProof package |
| Maintained by | Attesta core | Kyberon AI (sibling project) |
Example Audit Entry
Here’s what a TrailProof-backed audit entry looks like in the JSONL file:Audit Trail Concepts
Understand audit trail fundamentals and hash-chaining
Production Deployment
Best practices for deploying Attesta in production