Strapi Audit Logs Plugin

A comprehensive audit logging plugin for Strapi v5 that tracks all user interactions and system events with a clean admin interface and automatic cleanup.

> ⚠️ Version Compatibility
> - v2.x: Supports Strapi v5 only
> - v1.x: Supports Strapi v4 only
>
> If you're using Strapi v4, please install v1.x: npm install strapi-plugin-audit-logs@^1.0.0

✨ Features

- 🔍 Comprehensive Logging: Track content operations, media uploads, user management, and authentication events
- 🎯 Smart Event Tracking: Automatically logs content creation, updates, deletions, publishing, and more
- 🔒 Data Security: Configurable sensitive data redaction
- 🗂️ Rich Admin UI: Beautiful interface with filtering, search, pagination, and detailed log views
- 🧹 Automatic Cleanup: Configurable log retention with manual cleanup option
- 📊 Detailed Logging: Captures user info, IP addresses, HTTP context, and operation details
- 🔐 Role-Based Permissions: Granular access control with super admin cleanup controls

🚀 Installation

$3

``bash
npm install strapi-plugin-audit-logs@^2.0.0
`

$3

`bash
yarn add strapi-plugin-audit-logs@^2.0.0
`

⚙️ Configuration

After installation, configure the plugin in your config/plugins.js (or config/plugins.ts for TypeScript):

`javascript
module.exports = {
"audit-logs": {
enabled: true,
config: {
enabled: true,
deletion: {
enabled: true,
frequency: "logAge", // 'logAge' or 'logCount'
options: {
value: 90, // Keep logs for 90 days
interval: "day", // 'day', 'week', 'month', 'year'
},
},
excludeContentTypes: [
"plugin::any-custom-type.any-custom-type",
],
excludeEndpoints: [
"/admin/renew-token",
"/api/upload",
"/api/any-custom-type/any-custom-route",
],
redactedValues: [
"password",
"token",
"jwt",
"authorization",
"secret",
"key",
"private",
],
events: {
track: [
"entry.create",
"entry.update",
"entry.delete",
"entry.publish",
"entry.unpublish",
"media.create",
"media.update",
"media.delete",
"media-folder.create",
"media-folder.update",
"media-folder.delete",
"user.create",
"user.update",
"user.delete",
"role.create",
"role.update",
"role.delete",
"admin.auth.success",
"admin.auth.failure",
"admin.logout",
],
},
},
},
};
`

$3

For TypeScript projects, create or update config/plugins.ts:

`typescript
export default {
"audit-logs": {
enabled: true,
config: {
// ... same configuration as above
},
},
};
`

🔧 Setup

1. Install the plugin using npm or yarn (see installation section above)

2. Configure the plugin in config/plugins.js or config/plugins.ts

3. Restart your Strapi application:
`bash
npm run develop
# or
yarn develop
`

4. Set up permissions in the Strapi admin panel:
- Go to Settings → Roles
- Edit the roles that should have access to audit logs
- Enable "View Audit Logs" permission for the Audit Logs plugin

📋 Configuration Options

$3

#### enabled
- Type: boolean
- Default: true
- Description: Enable/disable the entire plugin

#### deletion
Configure automatic log cleanup:
- enabled: boolean - Enable automatic cleanup (runs daily at midnight)
- frequency: 'logAge' | 'logCount' - Cleanup strategy
- options:
- For logAge: { value: 90, interval: 'day' } (delete logs older than 90 days)
- For logCount: { value: 1000 } (keep only latest 1000 logs)

#### excludeEndpoints
Array of API endpoints to exclude from logging. Supports:
- Exact matches: /api/my-custom-endpoint
- Prefix matches: /admin/renew-token (matches /admin/renew-token/anything)
- Wildcards: /api/upload/* (matches any endpoint starting with /api/upload/)

#### excludeContentTypes
Array of content type UIDs to exclude from logging (e.g., ["api::private-content.private-content"])

#### redactedValues
Array of field names to redact in logged data for security purposes.

#### events
Configure automatic event tracking:
- track: string[] - Array of events to log automatically

📊 Tracked Events

The plugin automatically tracks these system events:

$3


- entry.create - Content entry created
- entry.update - Content entry updated
- entry.delete - Content entry deleted
- entry.publish - Content entry published
- entry.unpublish - Content entry unpublished

$3

- media.create - Media file uploaded
- media.update - Media file updated
- media.delete - Media file deleted
- media-folder.create - Media folder created
- media-folder.update - Media folder updated
- media-folder.delete - Media folder deleted

$3

- user.create - User account created
- user.update - User account updated
- user.delete - User account deleted

$3

- role.create - Role created
- role.update - Role updated
- role.delete - Role deleted

$3

- admin.auth.success - Successful admin login
- admin.auth.failure - Failed admin login attempt
- admin.logout - Admin logout

🎯 Usage

$3

1. Navigate to the Strapi admin panel
2. Look for "Audit Logs" in the main navigation menu
3. Click to view the audit logs interface

$3

The audit logs interface provides:
- Table View: See all logs with action, date, user, method, status, and IP address
- Action Filter: Dropdown to filter by specific action types
- User Search: Text input to search by username or email
- Advanced Pagination: Page size selector (10, 25, 50, 100) with smart navigation
- Details Modal: Click "View" to see full log details including JSON payload data

$3

Each log entry contains:
- Action: The type of action performed (with color-coded badges)
- Date: When the action occurred
- User: Who performed the action (username/email)
- Method: HTTP method used (GET, POST, PUT, DELETE)
- Status Code: Response status code (with color coding)
- IP Address: Client IP address
- User Agent: Client browser/application

- Payload Data: Full operation details in JSON format

$3

Super administrators can manually trigger log cleanup by clicking the "Cleanup Old Logs" button in the interface.

🔐 Permissions

The plugin uses a role-based permission system:

- View Audit Logs: Basic access to view the audit logs page and browse logs
- View Details: Access to detailed log information (available to all users with read access)
- Cleanup: Manual cleanup functionality (super administrators only)

To grant access:
1. Go to Settings → Roles
2. Select the role to modify
3. Under "Plugins" → "Audit Logs", enable "View Audit Logs"
4. Cleanup functionality is automatically available to super administrators

🔌 API Endpoints

The plugin provides these API endpoints (admin authentication required):

- GET /admin/audit-logs - List audit logs with filtering and pagination
- GET /admin/audit-logs/:id - Get specific log details
- GET /admin/audit-logs/count - Count total logs
- POST /admin/audit-logs/cleanup - Trigger manual cleanup (super admin only)

🗄️ Database Schema

The plugin creates an audit_logs table with these fields:

| Field | Type | Description |
|-------|------|-------------|
| id | Primary Key | Unique identifier |
| documentId | String | Document identifier (Strapi v5) |
| action | String | Action performed (e.g., entry.create, media.delete) |
| date | DateTime | Timestamp of the action |
| payload | JSON | Operation details and context |
| userId | Integer | User ID (if authenticated) |
| userDisplayName | String | User display name |
| userEmail | String | User email |
| endpoint | String | API endpoint accessed |
| method | String | HTTP method (GET, POST, PUT, DELETE) |
| statusCode | Integer | HTTP response status code |
| ipAddress | String | Client IP address |
| userAgent | Text | Client user agent string |




🔒 Security Considerations

- Sensitive data is automatically redacted based on configuration
- Logs are only accessible to users with proper permissions
- IP addresses and user agents are logged for security auditing
- Cleanup functionality restricted to super administrators
- Consider log retention policies for compliance requirements

🛠️ Troubleshooting

$3


1. Ensure the plugin is enabled in config/plugins.js
2. Restart Strapi after configuration changes
3. Check that your user role has the "View Audit Logs" permission

$3

1. Verify enabled: true in plugin configuration
2. Check that the events you want to track are in the events.track array
3. Restart Strapi after configuration changes
4. Look for error messages in Strapi logs

$3

1. Reduce the number of tracked events in configuration
2. Decrease log retention period for faster cleanup
3. Use logCount` cleanup strategy for high-traffic sites

🔄 Compatibility

- Strapi: 5.x
- Node.js: 18.x, 20.x, 22.x
- Database: PostgreSQL, MySQL/MariaDB, SQLite
- Operating System: Windows, macOS, Linux

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This plugin was inspired by Strapi Enterprise Edition's audit logs feature and the community plugin by Marje3PSUT.

📞 Support

If you encounter any issues or have questions:

1. Check the troubleshooting section
2. Search existing GitHub issues
3. Create a new issue if needed