Admin Audit Trail
A comprehensive Drupal audit logging module that tracks and records all content management and administrative actions within your website for compliance, accountability, and security purposes.
admin_audit_trail
Install
composer require 'drupal/admin_audit_trail:^1.0'
Overview
The Admin Audit Trail module automatically logs events performed by users through the Drupal administrative interface and system operations. All logged events are saved in a dedicated database table and can be viewed on a dedicated audit trail report page with filtering capabilities.
This module is designed to help organizations maintain compliance audit trails for regulatory requirements (HIPAA, GDPR, SOC 2, etc.), investigate when and how content was modified, and review administrative actions for security and accountability. Each log entry captures the event type, operation performed, human-readable description, the user who performed the action, timestamp, IP address, and the page path where the action occurred.
The module features an extensible architecture that makes it easy to add custom event tracking through a hook-based API. It includes 14 specialized sub-modules for tracking different entity types including nodes, users, authentication events, menus, taxonomy, comments, media, files, block content, redirects, workflows, entityqueues, paragraphs, groups, and user roles.
Features
- Comprehensive logging of all Create, Update, and Delete (CUD) operations across Drupal entities
- Dedicated audit trail report page at /admin/reports/audit-trail with sortable columns and pagination
- Advanced filtering by event type, operation, user, entity ID, IP address, name/machine name, path, and description keyword
- User identification with every log entry including user account, IP address, and timestamp
- Configurable log retention with automatic cleanup via cron (options: All, 100, 500, 1,000, 3,000, 10,000, or 100,000 entries)
- Collapsible filter section with configurable default state (expanded or collapsed)
- Extensible architecture via hook_admin_audit_trail_handlers() for registering custom event handlers
- 14 specialized sub-modules for tracking specific entity types out of the box
- Zero configuration required - sub-modules begin logging immediately upon enabling
- CLI operations are automatically ignored to prevent log pollution from automated scripts
- Log entries include type, operation, description, user, timestamp, IP address, path, and optional numeric/character references
Use Cases
Regulatory Compliance Auditing
Organizations subject to regulatory requirements such as HIPAA (healthcare), GDPR (data protection), SOC 2 (security), or PCI-DSS (payment card industry) can use Admin Audit Trail to maintain comprehensive audit logs of all content changes and user activities. Set the log retention to 'All' to preserve complete records for compliance audits, and use the filtering capabilities to quickly locate specific activities during audits.
Security Incident Investigation
When investigating potential security incidents, administrators can filter the audit trail by IP address, user, or time range to trace suspicious activities. The authentication sub-module is particularly useful for identifying failed login attempts, unusual login patterns, or unauthorized access attempts.
Content Change Tracking
Content managers and editors can use the audit trail to track who made specific changes to content, when changes occurred, and what pages were affected. This is useful for managing editorial workflows, resolving content disputes, and maintaining accountability in multi-author environments.
User Administration Oversight
Site administrators can monitor user account management activities including new registrations, account updates, deletions, and role assignments. The user roles sub-module provides detailed tracking of permission changes, helping identify potential privilege escalation or unauthorized access grants.
Menu and Site Structure Changes
Track all changes to the site's navigation structure including menu creation, menu link additions, updates, and deletions. This helps maintain visibility into how the site's information architecture evolves over time and who makes structural changes.
Media Asset Management
Organizations managing large media libraries can track when images, videos, and documents are uploaded, modified, or deleted. This is particularly useful for maintaining chain of custody for digital assets and investigating missing or incorrectly modified media.
Workflow State Transitions
For sites using content moderation, the workflows sub-module tracks every state transition (e.g., Draft to Review, Review to Published). This provides a complete history of the editorial process and helps identify bottlenecks or issues in the publishing workflow.
Tips
- Enable only the sub-modules you need to track - this reduces database overhead and keeps the audit trail focused on relevant activities
- For high-traffic sites, configure a reasonable log retention limit (e.g., 10,000 or 100,000) to prevent the database table from growing unbounded
- Use the Type filter first to narrow down results, as the Operation filter dynamically shows options based on the selected type with entry counts
- Bookmark filtered views by saving the URL - filter parameters are preserved in the query string
- Grant 'Access admin audit trail' permission to auditors and security personnel, but restrict 'Configure admin audit trail' to senior administrators only
- The module automatically ignores CLI operations to prevent log pollution from automated scripts and Drush commands
- Consider enabling the authentication sub-module on all sites for security monitoring of login activities and failed login attempts
Technical Details
Admin Pages 2
/admin/reports/audit-trail
View and search all logged audit trail events. This page displays a comprehensive table of all tracked events including the timestamp, event type, operation performed, path, description, user who performed the action, IP address, entity ID, and entity name. The table is sortable by any column and includes pagination for browsing large numbers of entries.
/admin/config/development/audit-trail/settings
Configure global settings for the Admin Audit Trail module including filter display preferences and log retention limits.
Permissions 2
Hooks 3
hook_admin_audit_trail_handlers
Registers event log handlers to define which form submissions should be tracked and how. Returns an associative array keyed by event type with handler configuration including title, form_ids, form_ids_regexp, and form_submit_callback.
hook_admin_audit_trail_log_alter
Allows modules to alter the log array before it is saved to the database. Can be used to modify type, operation, description, ref_numeric, or ref_char values.
hook_admin_audit_trail_handlers_alter
Allows modules to alter the registered event handlers. Can be used to modify, add, or remove handlers defined by other modules.
Troubleshooting 5
Ensure that the base Admin Audit Trail module and appropriate sub-modules are enabled. Check that the user has permission to perform the action being logged. Note that CLI operations (Drush, scripts) are intentionally not logged.
Configure the log retention limit at /admin/config/development/audit-trail/settings. Select an appropriate limit (e.g., 10,000 or 100,000 entries) and ensure cron is running regularly to perform the cleanup.
Log cleanup requires cron to run. Verify that cron is configured and running on your site. Check the Status Report page at /admin/reports/status to see when cron last ran.
Adjust the 'Filters Expanded' setting at /admin/config/development/audit-trail/settings to control the default filter display behavior.
Create a custom sub-module that implements hook_admin_audit_trail_handlers() to register your entity type, and use entity hooks (insert/update/delete) to call admin_audit_trail_insert() with appropriate log data.
Security Notes 6
- Audit trail entries are permanent unless explicitly cleaned up via cron - consider data retention policies when configuring log limits
- IP addresses are stored in log entries which may be considered personal data under GDPR - ensure your privacy policy reflects this
- Restrict the 'Configure admin audit trail' permission carefully as users with this permission can reduce log retention and potentially hide evidence of their activities
- The module logs the user who performed actions, but administrators can potentially impersonate other users - combine with other security measures for complete accountability
- Log entries are stored in plain text in the database - consider database-level encryption if audit data is highly sensitive
- Failed login attempts are logged with the attempted username which could expose valid usernames to database readers