QRun-IO/qctl
3
0 Fork 0
Code Issues 45 Pull Requests 7 Actions Packages Projects Releases 4 Wiki Activity

Implement audit logging for compliance #60

New Issue
Open
opened 2026-01-03 23:47:16 +00:00 by KofTwentyTwo · 0 comments
KofTwentyTwo commented 2026-01-03 23:47:16 +00:00 (Migrated from github.com)
Copy link
Copy source

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 detailed

Audit 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)
## 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 ```bash # 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 detailed ``` ### Audit 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 // 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 // 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)
Sign in to join this conversation.
No Branch/Tag Specified
Labels
Clear labels
Feature
bug
Something isn't working
 dependencies
documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 enterprise
Enterprise feature
 epic
Epic-level tracking issue
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 in-progress
invalid
This doesn't seem right
 module:core
Core infrastructure
 module:qbit
Package management module
 module:qqq
Template scaffolding module
 module:qrun
Build/deploy module
 module:qstudio
AI planning module
 question
Further information is requested
 secuurity
story
Feature story linked to epic
 wontfix
This will not be worked on
No labels enterprise story
Milestone
No items
No Milestone v1.0.0 - Production Ready
Projects
Clear projects
No projects
Assignees
Clear assignees
forge-recovery (Forge Recovery) james.maes (James Maes)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: QRun-IO/qctl#60