Libro

Libro (Italian/Spanish: book, record) — cryptographic audit chain for tamper-proof event logging

Libro provides an append-only, hash-linked audit chain where every event is chained to the previous via SHA-256. Any modification to any entry breaks the chain, making tampering detectable.

Architecture

libro (this crate)
  └── sha2 (SHA-256 hash linking)

Consumers:
  daimon ──→ libro (agent lifecycle audit: register, sandbox, deregister)
  aegis  ──→ libro (security events: policy violations, intrusion attempts)
  stiva  ──→ libro (container lifecycle: create, start, stop, kill)
  sigil  ──→ libro (trust decisions: signature verification, key rotation)
  ark    ──→ libro (package events: install, update, remove)

Features

• Hash-linked entries — each entry contains SHA-256 of the previous, forming a tamper-proof chain
• Append-only — no update, no delete. Immutable audit trail
• Chain verification — verify integrity of entire chain or any subsequence
• Severity levels — Debug, Info, Warning, Error, Critical, Security
• Agent tracking — optional agent_id per entry for per-agent audit trails
• Storage backends — AuditStore trait with memory, file (JSON Lines), and SQLite backends
• Chain rotation — archive old entries, start new chain linked to previous head
• Composable queries — filter by source, severity, agent, action, time range (all ANDed)
• Export — JSON Lines and CSV to any io::Write target
• Retention policies — keep N entries, keep by duration, keep after timestamp
• Merkle tree — build from chain, O(1) root comparison, O(log N) inclusion proofs
• Digital signatures — Ed25519 per-entry signing and verification (feature: signing)
• Severity ordering — Ord on EventSeverity, min_severity query filter
• Batch append — append_batch for multiple entries in one call
• Pagination — page() on chain, load_page() on stores (SQL LIMIT/OFFSET for SQLite)
• Streaming — real-time pub/sub via majra with MQTT-style topic wildcards (feature: streaming)
• Structured details — arbitrary JSON payload per entry

Quick Start

use libro::{AuditChain, EventSeverity};

let mut chain = AuditChain::new();

chain.append(
    EventSeverity::Info,
    "daimon",
    "agent.register",
    serde_json::json!({ "agent_id": "web-agent-01", "sandbox": "landlock" }),
);

chain.append(
    EventSeverity::Security,
    "aegis",
    "intrusion.detected",
    serde_json::json!({ "source": "10.0.0.5", "port": 22, "attempts": 5 }),
);

// Verify chain integrity
chain.verify().expect("chain is valid");

// Query security events
let alerts = chain.query(&libro::QueryFilter::new()
    .min_severity(EventSeverity::Security));
assert_eq!(alerts.len(), 1);

Modules

Roadmap

Phases 1–4 are complete. Remaining items (MCP tools, TPM attestation, multi-node sync) are infrastructure-dependent — MCP tools will be implemented in bote. See docs/development/roadmap.md for details.

Reference Code

License

AGPL-3.0 — see LICENSE for details.