audit_chain 1.x-dev

First published snapshot of Audit Chain. This is a development release, not a stable one — see the caveats below before using it on a site you care about.

Tamper-evident, hash-chained audit logging that any module can write to. Each entry's hash covers its own content and the previous entry's hash, so a later insertion, deletion or edit breaks the chain and is detectable by an independent verification pass. With an HMAC key configured, forging a repair also requires the key.

What is in this release

• AuditChainLoggerInterface and its implementation, writing to the audit_chain_log table. Consumers are identified by a channel, which is bound into the row hash so an entry cannot be re-attributed after the fact.
• Optional HMAC signing via a Key entity, and optional at-rest encryption of entry metadata via an Encryption Profile. Encryption is applied after hashing, so enabling it later does not invalidate earlier entries.
• drush audit-chain:verify — walks every entry and verifies the chain. The exit code is the contract: non-zero means the chain does not verify, so it can be wired into monitoring or a deploy gate without parsing output.
• A settings form at Configuration → System → Audit Chain for the signing key, the encryption profile, and streaming entries to the audit_chain logger channel for a SIEM.

Verified

The kernel suite runs on Drupal 10.6, 11.3 and 11 (PHPUnit 9.6 and 11.5), and covers chain verification, detection of an edited entry, a deleted entry and a re-attributed channel, keyed versus unkeyed chains, channel-scoped pruning, and compatibility with entries migrated from a consumer's own table.

Caveats

• The API may change before 1.0.0. The interface has exactly one consumer so far, and that integration is not finished. The first real consumer is what shakes out an API.
• The migration path has not been exercised on a production site. Entries migrated from a consumer's own table keep their original hashes and an empty channel, and that is covered by a kernel test — not yet by a real audit table with a live signing key.
• This project is not covered by Drupal's security advisory policy.

Two constraints for consumers

Do not log per access check. A hook such as hook_entity_field_access() fires per field, per entity, per render; an entry each time produces a chain nobody can read. Dedupe per request and flush once at kernel.terminate.

Rotating the encryption profile orphans existing entries. The chain is computed over the plaintext, so entries encrypted under the previous profile stop verifying — and the failure looks exactly like tampering. Export or re-encrypt first.

Installing

composer require drupal/audit_chain:1.x-dev — your project needs minimum-stability: dev (with prefer-stable: true) or an explicit @dev suffix.

Requires Drupal 10.6+ or 11.3+, Key, and Encrypt.