Implement audit logging for compliance #60
Description
User Story
As a compliance officer, I want comprehensive audit logs of all CLI operations so that I can track who did what and when for security and compliance purposes.
Design
Command Interface
# View audit logs
qctl audit list --since 24h
qctl audit list --user james.maes --since 7d
qctl audit list --action deploy --app my-app
# Export audit logs
qctl audit export --format json --since 30d > audit.json
qctl audit export --format csv --since 90d > audit.csv
# Query specific events
qctl audit show <event-id>
# Configure audit settings
qctl audit config --retention 365d --level detailedAudit Event Model
┌─────────────────────────────────────────────────────────────────┐
│ Audit Event Structure │
├─────────────────────────────────────────────────────────────────┤
│ │
│ { │
│ "id": "evt_abc123", │
│ "timestamp": "2026-01-03T14:30:00Z", │
│ "actor": { │
│ "id": "usr_xyz789", │
│ "email": "james.maes@acme.com", │
│ "type": "user|service_account", │
│ "ip": "192.168.1.100", │
│ "user_agent": "qctl/0.2.0" │
│ }, │
│ "action": "deploy", │
│ "resource": { │
│ "type": "app", │
│ "id": "orders-api", │
│ "environment": "production" │
│ }, │
│ "request": { │
│ "command": "qrun deploy --env prod", │
│ "version": "1.2.3", │
│ "channel": "stable" │
│ }, │
│ "result": { │
│ "status": "success|failure", │
│ "details": "Deployed version 1.2.3" │
│ }, │
│ "context": { │
│ "org_id": "org_123", │
│ "team_id": "team_456", │
│ "correlation_id": "corr_789" │
│ } │
│ } │
│ │
└─────────────────────────────────────────────────────────────────┘
Audited Actions
┌────────────────────────┬───────────────────────────────────────┐
│ Category │ Actions │
├────────────────────────┼───────────────────────────────────────┤
│ Authentication │ login, logout, token_refresh, sso │
│ Deployments │ deploy, rollback, promote │
│ Operations │ start, stop, restart, scale │
│ Configuration │ config_update, secret_update │
│ Package Management │ package_add, package_remove │
│ RBAC │ role_create, permission_grant, assign │
│ Team Management │ team_create, member_add, member_remove│
│ Template │ template_init, template_upgrade │
└────────────────────────┴───────────────────────────────────────┘
Output Format
$ qctl audit list --since 24h
TIMESTAMP USER ACTION RESOURCE STATUS
2026-01-03 14:30:00 james.maes deploy orders-api/prod success
2026-01-03 14:15:00 alice.smith scale orders-api/prod success
2026-01-03 13:45:00 ci-service-acct deploy orders-api/dev success
2026-01-03 12:00:00 james.maes login - success
2026-01-03 11:30:00 bob.jones deploy orders-api/prod failure
Showing 5 of 23 events. Use --limit to show more.
$ qctl audit show evt_abc123
Event ID: evt_abc123
Timestamp: 2026-01-03T14:30:00Z
Actor:
User: james.maes@acme.com
IP: 192.168.1.100
Client: qctl/0.2.0 (darwin/arm64)
Action: deploy
Resource: orders-api (production)
Request:
Command: qrun deploy --env prod --version 1.2.3
Channel: stable
Result: Success
Message: Deployed version 1.2.3 to production
Duration: 45s
Deployment ID: dep_xyz789
Context:
Organization: ACME Corp
Team: Platform Engineering
Correlation ID: corr_abc123
Export Formats
// JSON export
[
{
"id": "evt_abc123",
"timestamp": "2026-01-03T14:30:00Z",
"actor_email": "james.maes@acme.com",
"action": "deploy",
"resource_type": "app",
"resource_id": "orders-api",
"environment": "production",
"status": "success"
}
]// CSV export
id,timestamp,actor_email,action,resource_type,resource_id,environment,status
evt_abc123,2026-01-03T14:30:00Z,james.maes@acme.com,deploy,app,orders-api,production,success
API Integration
GET /v1/audit/events
GET /v1/audit/events/{eventId}
GET /v1/audit/export?format=json&since=30d
PUT /v1/audit/config
Files to Create/Modify
| File | Action | Description |
|---|---|---|
qctl-core/src/main/java/io/qrun/qctl/core/audit/AuditCommand.java |
Create | Audit command group |
qctl-core/src/main/java/io/qrun/qctl/core/audit/ListCommand.java |
Create | List audit events |
qctl-core/src/main/java/io/qrun/qctl/core/audit/ShowCommand.java |
Create | Show event details |
qctl-core/src/main/java/io/qrun/qctl/core/audit/ExportCommand.java |
Create | Export audit logs |
qctl-core/src/main/java/io/qrun/qctl/core/audit/ConfigCommand.java |
Create | Configure audit settings |
qctl-core/src/main/java/io/qrun/qctl/core/audit/AuditEvent.java |
Create | Audit event model |
qctl-core/src/main/java/io/qrun/qctl/core/audit/AuditActor.java |
Create | Actor information model |
qctl-core/src/main/java/io/qrun/qctl/core/audit/AuditExporter.java |
Create | Export to JSON/CSV |
qctl-core/src/main/java/io/qrun/qctl/core/audit/AuditFilter.java |
Create | Filter audit queries |
qctl-core/src/main/java/io/qrun/qctl/core/http/AuditInterceptor.java |
Create | HTTP interceptor for audit |
Implementation Tasks
- Create AuditCommand subcommand group
- Implement audit event list with filtering
- Add time range parsing (24h, 7d, 30d, date ranges)
- Implement event detail view
- Add JSON export format
- Add CSV export format
- Create HTTP interceptor to capture all API calls
- Add client metadata (IP, user agent, version)
- Implement pagination for large result sets
- Add audit config for retention and detail level
- Write unit tests for filtering and export
Acceptance Criteria
- Can list audit events with time filters
- Can filter by user, action, resource
- Event details show full context
- Export to JSON format works
- Export to CSV format works
- All mutating operations are audited
- Actor IP and client info captured
- Failed operations are logged with error details
- Audit log cannot be tampered with (server-side)