Technical Component Specification: Audit Events

Overview

The Audit Events system provides comprehensive tracking and logging of system operations and is integrated with tje OpsML server EventBus. The goal of Audit logging is to capture relevant information about how the OpsML server is being used and operational details. Audit events are currently opt-in and will expand as the server evolves.

Audit event capture is integrated via an audit middleware that parses response extensions for AuditContext. If AuditContext is present, it is extracted and used to create an AuditEvent. The event is then sent to the EventBus for asynchronous processing and storage in the connected SQL database. Thus for a server route to become auditable, it must return an AuditContext in the response extensions. Note that the AuditContext is a custom response extension and is removed after it is processed and is not exposed to the client.

Component Definition

pub struct AuditContext {
    pub resource_id: String,
    pub resource_type: ResourceType,
    pub metadata: String,
    pub operation: Operation,
    pub registry_type: Option<RegistryType>,
    pub access_location: Option<String>,
}

pub struct AuditEvent {
    pub username: String,
    pub client_ip: String,
    pub user_agent: String,
    pub operation: Operation,
    pub resource_type: ResourceType,
    pub resource_id: String,
    pub access_location: Option<String>,
    pub status: AuditStatus,
    pub error_message: Option<String>,
    pub metadata: String,
    pub registry_type: Option<RegistryType>,
    pub route: String,
}

Core Responsibilities

1. Event Creation
2. Request context capture
3. User identification
4. Operation tracking

5. Resource monitoring

6. Audit Context Management

7. Resource tracking
8. Operation classification
9. Registry type handling

10. Metadata collection

11. Event Persistence

12. Asynchronous storage
13. SQL backend integration
14. Error handling
15. Event querying

Key Methods

Event Creation

pub fn create_audit_event(
    addr: SocketAddr,
    agent: UserAgent,
    headers: HeaderMap,
    route: String,
    context: AuditContext,
) -> AuditEvent

Event Logging

pub async fn log_audit_event(
    event: AuditEvent,
    sql_client: Arc<SqlClientEnum>,
) -> Result<(), EventError>

Dependencies

• External Crates
• axum: Web framework integration
• headers: HTTP header handling
• tracing: Logging and instrumentation

• sqlx: Database operations

• Internal Components

• SqlClient: Database interface
• EventBus: Event distribution
• EventError: Error handling

Error Handling

• Custom EventError type
• SQL operation error handling
• Debug logging for failures
• Error context preservation

Security Considerations

1. User Tracking
2. Username capture
3. IP address logging
4. User agent recording

5. Access location tracking

6. Operation Auditing

7. Resource access logging
8. Operation classification
9. Status tracking

10. Error message capture

11. Data Privacy

12. Sensitive data handling
13. User information protection
14. Access control integration

Performance Considerations

1. Asynchronous Processing
2. Non-blocking event creation
3. Async database operations

4. Efficient event distribution

5. Resource Usage

6. Minimal memory overhead
7. Shared SQL connection via server AppState

Future Considerations

1. Event aggregation capabilities
2. Enhanced filtering options
3. Real-time audit monitoring
4. Advanced security features
5. Audit data analysis tools
6. Compliance reporting features

---

Version: 1.0
Last Updated: 2025-04-04
Component Owner: Steven Forrester