Stirling-PDF/proprietary/src/main/resources/templates/AUDIT_USAGE.md

Stirling PDF Audit System

This document provides guidance on how to use the audit system in Stirling PDF.

Overview

The audit system provides comprehensive logging of user actions and system events, storing them in a database for later review. This is useful for:

• Security monitoring
• Compliance requirements
• User activity tracking
• Troubleshooting

Audit Levels

The audit system supports different levels of detail that can be configured in the settings.yml file:

Level 0: OFF

• Disables all audit logging except for critical security events
• Minimal database usage and performance impact
• Only recommended for development environments

Level 1: BASIC

• Authentication events (login, logout, failed logins)
• Password changes
• User/role changes
• System configuration changes
• HTTP request errors (status codes >= 400)

Level 2: STANDARD (Default)

• Everything in BASIC plus:
• All HTTP requests (basic info: URL, method, status)
• File operations (upload, download, process)
• PDF operations (view, edit, etc.)
• User operations

Level 3: VERBOSE

• Everything in STANDARD plus:
• Request headers and parameters
• Method parameters
• Operation results
• Detailed timing information

Configuration

Audit levels are configured in the settings.yml file under the premium section:

premium:
  proFeatures:
    audit:
      enabled: true           # Enable/disable audit logging
      level: 2                # Audit level (0=OFF, 1=BASIC, 2=STANDARD, 3=VERBOSE)
      retentionDays: 90       # Number of days to retain audit logs

Automatic Auditing

The following events are automatically audited (based on configured level):

HTTP Request Auditing

All HTTP requests are automatically audited with details based on the configured level:

• BASIC level: Only errors (status code >= 400)
• STANDARD level: All requests with basic information (URL, method, status code, latency, IP)
• VERBOSE level: All of the above plus headers, parameters, and detailed timing

Controller Method Auditing

All controller methods with web mapping annotations are automatically audited:

• @GetMapping
• @PostMapping
• @PutMapping
• @DeleteMapping
• @PatchMapping

Methods with these annotations are audited at the STANDARD level by default.

Security Events

The following security events are always audited at the BASIC level:

• Authentication events (login, logout, failed login attempts)
• Password changes
• User/role changes

Manual Auditing

There are two ways to add audit events from your code:

1. Using AuditService Directly

Inject the AuditService and use it directly:

@Service
@RequiredArgsConstructor
public class MyService {

    private final AuditService auditService;
    
    public void processPdf(MultipartFile file) {
        // Process the file...
        
        // Add an audit event with default level (STANDARD)
        auditService.audit("PDF_PROCESSED", Map.of(
            "filename", file.getOriginalFilename(),
            "size", file.getSize(),
            "operation", "process"
        ));
        
        // Or specify an audit level
        auditService.audit("PDF_PROCESSED_DETAILED", Map.of(
            "filename", file.getOriginalFilename(),
            "size", file.getSize(),
            "operation", "process",
            "metadata", file.getContentType(),
            "user", "johndoe"
        ), AuditLevel.VERBOSE);
        
        // Critical security events should use BASIC level to ensure they're always logged
        auditService.audit("SECURITY_EVENT", Map.of(
            "action", "file_access",
            "resource", file.getOriginalFilename()
        ), AuditLevel.BASIC);
    }
}

2. Using the @Audited Annotation

For simpler auditing, use the @Audited annotation on your methods:

@Service
public class UserService {

    // Basic audit level for important security events
    @Audited(type = "USER_REGISTRATION", level = AuditLevel.BASIC)
    public User registerUser(String username, String email) {
        // Method implementation
        User user = new User(username, email);
        // Save user...
        return user;
    }
    
    // Sensitive operations should use BASIC but disable argument logging
    @Audited(type = "USER_PASSWORD_CHANGE", level = AuditLevel.BASIC, includeArgs = false)
    public void changePassword(String username, String newPassword) {
        // Change password implementation
        // includeArgs=false prevents the password from being included in the audit
    }
    
    // Standard level for normal operations (default)
    @Audited(type = "USER_LOGIN")
    public boolean login(String username, String password) {
        // Login implementation
        return true;
    }
    
    // Verbose level for detailed information
    @Audited(type = "USER_SEARCH", level = AuditLevel.VERBOSE, includeResult = true)
    public List<User> searchUsers(String query) {
        // Search implementation
        // At VERBOSE level, this will include both the query and results
        return userList;
    }
}

With the @Audited annotation:

• You can specify the audit level using the level parameter
• Method arguments are automatically included in the audit event (unless includeArgs = false)
• Return values can be included with includeResult = true
• Exceptions are automatically captured and included in the audit
• The aspect handles all the boilerplate code for you
• The annotation respects the configured global audit level

3. Controller Automatic Auditing

In addition to the manual methods above, all controller methods with web mapping annotations are automatically audited, even without the @Audited annotation:

@RestController
@RequestMapping("/api/users")
public class UserController {

    // This method will be automatically audited
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable String id) {
        // Method implementation
        return ResponseEntity.ok(user);
    }
    
    // This method will be automatically audited
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // Method implementation
        return ResponseEntity.ok(savedUser);
    }
    
    // This method uses @Audited and takes precedence over automatic auditing
    @Audited(type = "USER_DELETE", level = AuditLevel.BASIC)
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable String id) {
        // Method implementation
        return ResponseEntity.noContent().build();
    }
}

Important notes about automatic controller auditing:

• All controller methods with web mapping annotations are audited at the STANDARD level
• If a method already has an @Audited annotation, that takes precedence
• The audit event includes controller name, method name, path, and HTTP method
• At VERBOSE level, request parameters are also included
• Exceptions are automatically captured

Common Audit Event Types

Use consistent event types throughout the application:

• FILE_UPLOAD - When a file is uploaded
• FILE_DOWNLOAD - When a file is downloaded
• PDF_PROCESS - When a PDF is processed (split, merged, etc.)
• USER_CREATE - When a user is created
• USER_UPDATE - When a user details are updated
• PASSWORD_CHANGE - When a password is changed
• PERMISSION_CHANGE - When permissions are modified
• SETTINGS_CHANGE - When system settings are changed

Security Considerations

• Sensitive data is automatically masked in audit logs (passwords, API keys, tokens)
• Each audit event includes a unique request ID for correlation
• Audit events are stored asynchronously to avoid performance impact
• The /auditevents endpoint is disabled to prevent unauthorized access to audit data

Database Storage

Audit events are stored in the audit_events table with the following schema:

• id - Unique identifier
• principal - The username or system identifier
• type - The event type
• data - JSON blob containing event details
• timestamp - When the event occurred

Metrics

Prometheus metrics are available at /actuator/prometheus for monitoring system performance and audit event volume.