@noukha/audit-module

Comprehensive audit logging and monitoring module for NestJS applications with MongoDB support.

Installation

npm install @noukha/audit-module

Features

• Comprehensive Audit Logging: Track all user actions, system events, and data changes
• Flexible Configuration: Customizable audit rules and retention policies
• Real-time Monitoring: Live audit trail with filtering and search capabilities
• Performance Tracking: Monitor response times and system performance
• Security Auditing: Track security events, permission changes, and access patterns
• Data Export: Export audit logs in various formats
• Automatic Cleanup: Configurable retention and cleanup policies
• RESTful API: Complete REST API for audit log management
• MongoDB Integration: Optimized for MongoDB with proper indexing
• NestJS Integration: Seamless integration with NestJS applications

Quick Start

1. Import the Module

import { AuditModule } from '@noukha/audit-module';

@Module({
  imports: [
    AuditModule.forRoot({
      connectionString: 'mongodb://localhost:27017/audit',
      database: 'audit',
      retentionDays: 30,
      enableControllers: true,
      enableGlobalLogger: true,
      logLevel: 'info',
      autoCleanup: true,
      cleanupInterval: 24 * 60 * 60 * 1000, // 24 hours
    })
  ]
})
export class AppModule {}

2. Use the Services

import { AuditLoggerService, AuditService } from '@noukha/audit-module';

@Injectable()
export class MyService {
  constructor(
    private readonly auditLogger: AuditLoggerService,
    private readonly auditService: AuditService
  ) {}

  async createUser(userData: any) {
    // Your business logic here
    const user = await this.userRepository.create(userData);
    
    // Log the audit event
    await this.auditLogger.logDataCreate('user', user.id, userData, {
      userId: 'current-user-id',
      sessionId: 'session-123',
      ipAddress: '192.168.1.1',
      userAgent: 'Mozilla/5.0...',
      endpoint: '/api/users',
      method: 'POST',
      correlationId: 'req-123'
    });
    
    return user;
  }

  async updateUser(userId: string, updateData: any) {
    const oldUser = await this.userRepository.findById(userId);
    const updatedUser = await this.userRepository.update(userId, updateData);
    
    // Log the audit event
    await this.auditLogger.logDataUpdate('user', userId, oldUser, updatedUser, {
      userId: 'current-user-id',
      sessionId: 'session-123',
      ipAddress: '192.168.1.1',
      userAgent: 'Mozilla/5.0...',
      endpoint: '/api/users/' + userId,
      method: 'PUT',
      correlationId: 'req-124'
    });
    
    return updatedUser;
  }
}

3. Use Decorators (Optional)

import { AuditLog } from '@noukha/audit-module';

@Controller('users')
export class UserController {
  
  @Post()
  @AuditLog({
    action: 'CREATE',
    resource: 'user',
    message: 'User created'
  })
  async createUser(@Body() userData: any) {
    return this.userService.create(userData);
  }
  
  @Put(':id')
  @AuditLog({
    action: 'UPDATE',
    resource: 'user',
    message: 'User updated'
  })
  async updateUser(@Param('id') id: string, @Body() updateData: any) {
    return this.userService.update(id, updateData);
  }
}

API Reference

AuditService

Core Methods

• createAuditLog(auditOptions: AuditOptions): Promise<AuditLog>
• createAuditLogFromDto(createAuditLogDto: CreateAuditLogDto): Promise<AuditLog>
• findAuditLogs(searchOptions: AuditSearchOptions): Promise<PaginatedResponse<AuditLog>>
• findAuditLogById(id: string): Promise<AuditLog>
• updateAuditLog(id: string, updateAuditLogDto: UpdateAuditLogDto): Promise<AuditLog>
• deleteAuditLog(id: string): Promise<void>
• archiveAuditLog(id: string): Promise<AuditLog>
• restoreAuditLog(id: string): Promise<AuditLog>
• bulkArchiveAuditLogs(ids: string[]): Promise<void>
• bulkDeleteAuditLogs(ids: string[]): Promise<void>

Utility Methods

• getAuditStats(startDate?: Date, endDate?: Date): Promise<any>
• exportAuditLogs(searchOptions: AuditSearchOptions): Promise<any>
• cleanupExpiredLogs(): Promise<number>
• getAuditTrail(resource: string, resourceId: string): Promise<AuditLog[]>

AuditLoggerService

Logging Methods

• log(options: AuditOptions): Promise<void>
• logAction(action: string, resource: string, resourceId: string, context: any): Promise<void>
• logError(error: Error, context: any): Promise<void>
• logSecurity(event: string, context: any): Promise<void>
• logPerformance(operation: string, duration: number, context: any): Promise<void>

Convenience Methods

• logUserLogin(userId: string, context: AuditContext): Promise<void>
• logUserLogout(userId: string, context: AuditContext): Promise<void>
• logDataCreate(resource: string, resourceId: string, data: any, context: AuditContext): Promise<void>
• logDataUpdate(resource: string, resourceId: string, oldData: any, newData: any, context: AuditContext): Promise<void>
• logDataDelete(resource: string, resourceId: string, data: any, context: AuditContext): Promise<void>
• logPermissionChange(userId: string, targetUserId: string, permissions: any, context: AuditContext): Promise<void>
• logRoleAssignment(userId: string, targetUserId: string, role: string, context: AuditContext): Promise<void>

Audit Actions

Standard Actions

• CREATE: Data creation
• READ: Data retrieval
• UPDATE: Data modification
• DELETE: Data deletion
• LOGIN: User login
• LOGOUT: User logout
• EXPORT: Data export
• IMPORT: Data import
• BULK_UPDATE: Bulk data updates
• BULK_DELETE: Bulk data deletion
• SEARCH: Search operations
• FILTER: Filter operations
• SORT: Sort operations
• PAGINATE: Pagination operations
• DOWNLOAD: File downloads
• UPLOAD: File uploads
• APPROVE: Approval actions
• REJECT: Rejection actions
• PUBLISH: Publishing actions
• UNPUBLISH: Unpublishing actions
• ARCHIVE: Archiving actions
• RESTORE: Restoration actions
• SHARE: Sharing actions
• COPY: Copy operations
• MOVE: Move operations
• RENAME: Rename operations
• PERMISSION_CHANGE: Permission changes
• ROLE_ASSIGN: Role assignments
• ROLE_REMOVE: Role removals
• PASSWORD_CHANGE: Password changes
• PROFILE_UPDATE: Profile updates
• SYSTEM_CONFIG: System configuration changes
• CUSTOM: Custom actions

Audit Levels

• DEBUG: Debug information
• INFO: General information
• WARN: Warning messages
• ERROR: Error conditions
• CRITICAL: Critical errors

Audit Categories

• AUTHENTICATION: Authentication events
• AUTHORIZATION: Authorization events
• DATA_ACCESS: Data access events
• DATA_MODIFICATION: Data modification events
• SYSTEM_OPERATION: System operations
• USER_ACTIVITY: User activities
• SECURITY: Security events
• PERFORMANCE: Performance events
• ERROR: Error events
• BUSINESS: Business events
• COMPLIANCE: Compliance events
• INTEGRATION: Integration events
• CUSTOM: Custom categories

Audit Sources

• API: API requests
• WEB: Web interface
• MOBILE: Mobile application
• DESKTOP: Desktop application
• SYSTEM: System operations
• BATCH: Batch processes
• SCHEDULED: Scheduled tasks
• WEBHOOK: Webhook events
• INTEGRATION: External integrations
• MANUAL: Manual operations

Configuration Options

interface AuditModuleOptions {
  connectionString?: string;        // MongoDB connection string
  database?: string;                // Database name (default: 'audit')
  collectionPrefix?: string;        // Collection name prefix
  retentionDays?: number;           // Log retention in days (default: 30)
  enableControllers?: boolean;     // Enable REST controllers (default: true)
  enableGlobalLogger?: boolean;     // Enable global logger (default: true)
  logLevel?: 'debug' | 'info' | 'warn' | 'error'; // Log level
  autoCleanup?: boolean;           // Enable automatic cleanup (default: true)
  cleanupInterval?: number;        // Cleanup interval in milliseconds
}

REST API Endpoints

Audit Logs

• GET /audit-logs - Get audit logs with filtering and pagination
• GET /audit-logs/:id - Get specific audit log
• POST /audit-logs - Create new audit log
• PUT /audit-logs/:id - Update audit log
• DELETE /audit-logs/:id - Delete audit log
• PUT /audit-logs/:id/archive - Archive audit log
• PUT /audit-logs/:id/restore - Restore archived audit log
• POST /audit-logs/bulk/archive - Bulk archive audit logs
• POST /audit-logs/bulk/delete - Bulk delete audit logs
• GET /audit-logs/stats - Get audit statistics
• GET /audit-logs/export - Export audit logs
• GET /audit-logs/trail/:resource/:resourceId - Get audit trail
• POST /audit-logs/cleanup - Cleanup expired logs

Audit Configuration

• GET /audit-configs - Get all audit configurations
• GET /audit-configs/:id - Get specific audit configuration
• POST /audit-configs - Create new audit configuration
• PUT /audit-configs/:id - Update audit configuration
• DELETE /audit-configs/:id - Delete audit configuration
• PUT /audit-configs/:id/activate - Activate configuration
• PUT /audit-configs/:id/deactivate - Deactivate configuration

Query Parameters

Find Audit Logs

• action: Filter by audit action
• level: Filter by audit level
• category: Filter by audit category
• source: Filter by audit source
• userId: Filter by user ID
• sessionId: Filter by session ID
• resource: Filter by resource type
• resourceId: Filter by resource ID
• correlationId: Filter by correlation ID
• parentAuditId: Filter by parent audit ID
• tags: Filter by tags (array)
• search: Text search across multiple fields
• startDate: Filter by start date
• endDate: Filter by end date
• ipAddress: Filter by IP address
• endpoint: Filter by endpoint
• method: Filter by HTTP method
• minResponseTime: Minimum response time filter
• maxResponseTime: Maximum response time filter
• statusCode: Filter by HTTP status code
• isArchived: Filter by archive status
• metadataFilters: Filter by metadata fields
• page: Page number (default: 1)
• limit: Items per page (default: 10)
• sortBy: Sort field (default: 'timestamp')
• sortOrder: Sort order ('asc' | 'desc', default: 'desc')

Examples

Basic Usage

// Log a simple action
await auditLogger.logAction('CREATE', 'user', 'user-123', {
  userId: 'admin-1',
  sessionId: 'session-456',
  ipAddress: '192.168.1.100',
  userAgent: 'Mozilla/5.0...',
  endpoint: '/api/users',
  method: 'POST'
});

// Log an error
await auditLogger.logError(new Error('Database connection failed'), {
  userId: 'system',
  sessionId: 'system',
  resource: 'database',
  resourceId: 'connection-1',
  metadata: { database: 'main', host: 'localhost' }
});

// Log performance metrics
await auditLogger.logPerformance('database-query', 150, {
  userId: 'user-1',
  sessionId: 'session-789',
  resource: 'database',
  resourceId: 'query-1',
  metadata: { query: 'SELECT * FROM users', table: 'users' }
});

Advanced Filtering

// Find audit logs with complex filtering
const auditLogs = await auditService.findAuditLogs({
  action: AuditAction.CREATE,
  category: AuditCategory.USER_ACTIVITY,
  userId: 'user-123',
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
  search: 'user creation',
  page: 1,
  limit: 20,
  sortBy: 'timestamp',
  sortOrder: 'desc'
});

Audit Trail

// Get complete audit trail for a resource
const auditTrail = await auditService.getAuditTrail('user', 'user-123');
console.log(`Found ${auditTrail.length} audit events for user user-123`);

Statistics

// Get audit statistics
const stats = await auditService.getAuditStats(
  new Date('2024-01-01'),
  new Date('2024-01-31')
);
console.log(`Total logs: ${stats.totalLogs}`);
console.log(`Unique users: ${stats.uniqueUsers}`);
console.log(`Average response time: ${stats.avgResponseTime}ms`);
console.log(`Error rate: ${stats.errorRate}%`);

Best Practices

1. Consistent Context

Always provide consistent context information:

const auditContext = {
  userId: req.user?.id || 'anonymous',
  sessionId: req.sessionID || 'no-session',
  ipAddress: req.ip || req.connection.remoteAddress,
  userAgent: req.get('User-Agent') || 'unknown',
  endpoint: req.originalUrl,
  method: req.method,
  correlationId: req.headers['x-correlation-id'] || nanoid()
};

2. Meaningful Messages

Use descriptive messages that provide context:

// Good
await auditLogger.logAction('CREATE', 'user', userId, {
  ...context,
  message: `User ${userId} created with email ${userData.email}`
});

// Bad
await auditLogger.logAction('CREATE', 'user', userId, {
  ...context,
  message: 'User created'
});

3. Appropriate Log Levels

Use appropriate log levels for different types of events:

// Critical security events
await auditLogger.logSecurity('Failed login attempt', {
  ...context,
  level: AuditLevel.CRITICAL,
  metadata: { attempts: 5, locked: true }
});

// Performance warnings
await auditLogger.logPerformance('slow-query', 5000, {
  ...context,
  level: AuditLevel.WARN
});

4. Data Privacy

Be careful with sensitive data in audit logs:

// Remove sensitive fields before logging
const sanitizedData = { ...userData };
delete sanitizedData.password;
delete sanitizedData.ssn;
delete sanitizedData.creditCard;

await auditLogger.logDataCreate('user', userId, sanitizedData, context);

5. Retention Policies

Configure appropriate retention policies:

// Different retention for different types of logs
await auditService.createAuditLog({
  ...auditOptions,
  expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000), // 1 year for security logs
});

Performance Considerations

1. Async Logging

Always use async logging to avoid blocking the main application:

// Good - fire and forget
this.auditLogger.logAction('CREATE', 'user', userId, context).catch(err => {
  console.error('Audit logging failed:', err);
});

// Bad - blocking
await this.auditLogger.logAction('CREATE', 'user', userId, context);

2. Batch Operations

For bulk operations, consider batching audit logs:

// Batch multiple audit logs
const auditLogs = users.map(user => ({
  action: AuditAction.CREATE,
  resource: 'user',
  resourceId: user.id,
  // ... other fields
}));

await Promise.all(auditLogs.map(log => auditService.createAuditLog(log)));

3. Indexing

The module automatically creates indexes for common query patterns:

• userId + timestamp
• resource + resourceId + timestamp
• action + category + timestamp
• sessionId + timestamp
• correlationId
• expiresAt (for TTL)

Troubleshooting

Common Issues

1. High Memory Usage: Reduce retention period or implement log rotation
2. Slow Queries: Check if proper indexes are created
3. Missing Logs: Verify audit configuration and service injection
4. Performance Impact: Use async logging and consider batching

Debug Mode

Enable debug logging to troubleshoot issues:

AuditModule.forRoot({
  logLevel: 'debug',
  // ... other options
})

License

MIT

Support

For support and questions, please open an issue on the GitHub repository.