Audit Chain

Audit Chain is for Drupal module developers, security operators, and compliance teams that need to detect whether historical audit records were inserted, deleted, reordered, or edited. Wilkes & Liberty maintains the GPL-licensed module as a reusable audit primitive for Drupal 10.6+ and 11.3+. A consumer records structured events through one service; operators verify the resulting chain independently through Drush.

Why it exists

Ordinary logs answer “what does the application currently say happened?” They do not prove that an earlier row was left alone. A privileged database user can remove an embarrassing event, alter metadata, or rebuild a sequence unless the log carries an integrity relationship that makes later changes visible.

Audit Chain binds each row to the previous row's hash and to a canonical payload that includes channel, operation, actor, timestamp, promoted entity identifiers, network context, and metadata. Optional HMAC signing means repairing a modified chain also requires signing-key access. Optional encryption protects stored metadata without confusing confidentiality with integrity.

Who should use it, and when

• Drupal module authors who need a shared audit API instead of another private log table.
• Security operators monitoring sensitive changes, access events, break-glass actions, controlled downloads, or automated-agent activity.
• Compliance teams that need an independently testable signal when audit history changes.
• Site-reliability teams that want verification in scheduled jobs, deployment gates, or SIEM workflows.

Use it when the integrity of prior records matters after the request has completed. Use ordinary application logging alongside it for high-volume diagnostics, debug context, and operational search.

Where it sits

Audit Chain runs inside Drupal and exposes a logging service to other modules. Consumers write channel-specific events into one site-wide sequence. A request-scoped collector can deduplicate noisy access-hook events and flush after the response, keeping the append lock away from the user's critical path. Structured records also flow through Drupal's audit_chain logging channel for forwarding through Syslog, Monolog, or a SIEM.

The module was extracted from MCP Sentinel, where the mechanism records governed AI-agent operations. It is intentionally independent so file delivery, configuration governance, permissions, or custom mission modules can use the same evidence layer.

How the chain works

1. A consumer submits a structured event to the Audit Chain service.
2. The module canonicalizes the payload, links it to the previous stored hash, and appends under a site-wide lock.
3. If a signing key is configured, the row uses HMAC; otherwise it is explicitly recognized as unkeyed rather than misreported as tampering.
4. If metadata encryption is enabled, the row records which encryption profile produced the stored bytes.
5. drush audit-chain:verify recomputes the sequence and returns a nonzero exit code when the chain is not fully healthy.

Verification distinguishes altered content/order from intact rows written without the expected key. It can try explicitly trusted retired signing keys after rotation. A historical prefix whose original content can no longer be verified may be sealed as a local genesis point; the seal promises only that later changes to that frozen prefix will be detected.

Operational safeguards

• Status checks report a configured signing key that no longer resolves.
• Rows record the actual encryption profile, exposing history that will become unreadable if an old profile is removed.
• Malformed UTF-8 metadata is normalized instead of creating a permanently unverifiable row.
• Key rotation accepts named retired keys without silently trusting a row's advisory key_id.
• A single global sequence prevents deletion of one consumer channel from remaining invisible.

Honest boundaries

Audit Chain does not prevent deletion; it makes deletion evident at the next verification. A database administrator who can alter both data and site configuration remains a larger trust problem. The module orders events in one Drupal database, not across multiple databases or servers. It is not a write-once store, a legal-records policy, a SIEM, or a replacement for backups.

Unsigned history cannot be signed retroactively. A prefix seal does not prove old records were truthful. Encryption-key custody and profile retention remain operator responsibilities, and encrypted history must be re-encrypted before an old profile is removed.

Install and verify

Requires PHP 8.1+, Drupal 10.6+ or 11.3+, Key 1.20+, and Encrypt 3.2+.

composer require drupal/audit_chain
drush en audit_chain
drush audit-chain:verify

Configure signing and encryption under Drupal's system configuration. Keep key material outside the database through an appropriate Key provider. Add the verification command to a schedule or monitoring workflow; the nonzero exit status is the stable automation contract.

Project, source, issues, and related work

• Audit Chain project page and releases on Drupal.org
• Source code and documentation on GitHub
• Issue queue on Drupal.org
• MCP Sentinel, the original consumer
• File Gate, an optional audit consumer

Maintained by Jeremy Michael Cerda and Wilkes & Liberty under GPL-2.0-or-later. The checked source release for this page is 1.3.0.