Skip to main content

Module audit

Module audit 

Source
Expand description

S7 (#573, epic #547) — tamper-evident, complete audit of every MAC authorization decision, with OpenTelemetry fan-out.

This is the Accounting leg of the MAC security model: every allow/deny the PDP (crate::mac::avc) produces is recorded tamper-evidently, and a decision that cannot be audited is denied (fail-closed). The store is a data-plane structure — append-only, content-addressed, signed, and WAL-durable on write (a write is durable before the decision returns).

§Design (the four properties the task requires)

  1. Append-only — the on-disk log is opened append-only; the API exposes no mutate/delete. The CAS layer writes content-addressed blobs whose names are their own hash, so overwrites are no-ops and a name never points at different bytes. See WalAuditStore and its tests.
  2. Content-addressed — every AuditRecord is BLAKE3-hashed over its canonical CBOR encoding (deterministic: sorted maps, sorted keys), so the same decision yields the same hash (AuditRecord::content_hash). Tamper-evident by construction: changing any field changes the hash, which breaks the signature that covers it.
  3. WAL-durable on write — WalAuditStore::record appends the signed record to a journal, then fsyncs the file and its parent directory before returning Ok(()). The caller (the AVC) does not return a Permit until record returns, so a Permit is never handed out ahead of a durable audit entry. See the wal_record_is_durable_before_return test.
  4. Signed + hash-chained — each record is signed via the existing COSE path (crate::mac::compiled::cose / sign_composite), and each record carries the prev_hash of its predecessor, so the journal is an append-only chain. Tamper evidence is conjoint: altering a record breaks its hash (and thus its signature); reordering or deleting a middle record breaks the successor’s prev_hash link. A deleted tail leaves a still-valid shorter chain, so it is caught instead by the signed checkpoint (§ Truncation) — the head anchor written out-of-band after every record.

§Truncation detection (the actual guarantee — and its limit)

After every durable append, the store writes a signed checkpoint (a separate checkpoint file) recording the current head (seq, head_hash). On open, the store fails closed if the journal’s head sequence is below the checkpoint’s — i.e. the tail was truncated. [WalAuditStore:: verify_journal] additionally verifies the checkpoint’s signature and that it matches the journal head, so a forged or rolled-back checkpoint is rejected offline.

Residual limit (honest): the checkpoint is a local anchor. An attacker with write access to BOTH the journal and the checkpoint can truncate both consistently and evade local detection. Closing that requires an off-host anchor (replicate the signed head to OTel / a second host); that is tracked as a follow-up and deliberately out of scope here. What this store guarantees today: no tampering, reordering, or middle-deletion goes undetected, and tail-truncation is detected unless the checkpoint is destroyed in the same act.

§Complete mediation (the hook point)

AuditedAvc wraps any Avc and routes every decide / decide_with_token call through the audit sink. Because the AVC is the single per-op entry point the PEP (S2) calls, auditing there is complete mediation: no decision bypasses it. On a cache hit the cached decision is still re-recorded (cheap: a hash + append + fsync) so the audit log reflects every op the PEP actually performed, not just PDP misses — completeness over cache efficiency.

§Fail-closed on audit failure

If the audit write fails (disk full, IO error, signer error), the audited AVC downgrades a Permit to Deny and records the deny it actually enforced. A decision that cannot be audited is never allowed through. This is the explicit fail-closed contract; see the permit_downgrades_to_deny_ when_audit_write_fails test.

§OpenTelemetry fan-out (fixes #453)

Every decision emits a structured [tracing] event on the dedicated hyprstream.mac.audit target with fields decision, subject, resource, action, generation, and reason. OTel is wired as a tracing subscriber (see bin/main.rs init_telemetry), so these events fan out to OTLP automatically when the otel feature is active — denials become first-class observable signals, no longer buried at debug level.

§What is deferred (documented TODOs)

  • Cross-host replication of the audit store — S7 ships the local tamper-evident store; replication (gossip/OTLP log export to a central audit collector) is TODO(S7-followup): in WalAuditStore.
  • Retention / rotation — the journal grows unbounded; rotation + remote archival is TODO(S7-followup): below.
  • Policy-evolution feedback — denials feeding back into PolicyService is TODO(S7-followup): — the records are here, the consumer is not.
  • Hybrid (EdDSA + ML-DSA-65) signing of audit records — S8 (#574) made the cose::CoseAuditSigner policy-aware: under a Hybrid crypto policy it fails closed if no ML-DSA-65 key is provisioned (no silent downgrade of a security-critical accounting artifact). Production wiring of the audited AVC (constructing a WalAuditStore with the node’s PQ audit key and installing it in the PEP) is TODO(S7-followup):.

Modules§

cose
Production signer/verifier adapters over hyprstream_rpc::crypto::cose_sign, mirroring crate::mac::compiled::cose.

Structs§

AuditRecord
A single authorization decision, as recorded by the audit store. This is the unit of tamper-evidence: it is content-addressed (BLAKE3 over canonical CBOR), signed, and append-logged.
AuditedAvc
An Avc that routes every decision through an AuditSink. This is the S7 complete-mediation hook: because the PEP (S2) calls the AVC per op, wrapping it here audits every decision with no bypass.
DelegationPrincipal
The delegator principal recorded on a delegated (two-principal, #680/#681) decision — the source of authority on whose behalf the record’s subject_* (the effective, met context) was evaluated.
NullAuditSink
A no-op sink for environments that opt out of durable audit (e.g. tests of the PDP itself that are not exercising S7). Not for production — production requires tamper-evident audit, which this provides none of.
WalAuditStore
The authoritative tamper-evident audit store. Append-only journal + content-addressed CAS blobs, each record signed. WAL-durable on write.

Enums§

AuditError
Audit-store failures. All are fail-closed at the AVC boundary.
DecisionReason
Why the PDP returned this decision. Recorded so denials are diagnosable and so the policy-evolution feedback (deferred) can bucket denials by cause.

Traits§

AuditSigner
Abstraction over the authority that signs audit records. Production wires the hybrid COSE composite (EdDSA + ML-DSA-65) via crate::mac::compiled::cose; tests use a trivial stub.
AuditSink
Where the audited AVC sends records. The authoritative impl is WalAuditStore; tests / non-durable deployments can swap a no-op or in-memory sink. Fail-closed contract: a record error makes the audited AVC downgrade a Permit to Deny (see AuditedAvc).
AuditVerifier
Abstraction over signature verification (for log-integrity checks / replay).

Functions§

audit_signing_input
Domain-separated signing input: a fixed tag + the content hash. Binding the hash (not the raw bytes) keeps the signed payload small and stable, and makes the signature independent of the canonical-bytes serialization choice.
checkpoint_signing_input
Domain-separated signing input for the head-anchor checkpoint (seq, head_hash). The tag differs from audit_signing_input so a per-record signature can never be replayed as a checkpoint signature (and vice-versa).