Audit Readiness

Big Picture maintains append-only audit logs that record all administrative actions, policy changes, and release operations. Audit logs include timestamps, actors, and full context for each event. This enables compliance verification and forensic analysis.

Prerequisites

• API credentials with audit read permissions
• Understanding of your organization’s audit requirements
• Access to audit log storage and export capabilities

Understanding Audit Logs

Audit logs record:

• Administrative actions — User management, role assignments, configuration changes
• Policy changes — Update policy creation, modification, deletion
• Release operations — Release creation, approval, rejection, distribution
• License operations — Entitlement import, lease issuance, revocation
• Access events — Authentication, authorization failures, permission changes

All audit events include:

• Event identifier
• Timestamp
• Actor (user or service account)
• Event type
• Full context (before/after values, request details)
• IP address (if available)

Step 1: Verify Audit Logging is Enabled

Check that audit logging is enabled and functioning:

curl "${BP_BASE_URL}/v1/audit/status" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "enabled": true,
  "retention_days": 2555,
  "storage_backend": "database",
  "last_event_at": "2024-01-15T10:30:00Z",
  "total_events": 1234567
}

Step 2: Query Audit Events

Query audit events by type, actor, or time range:

curl "${BP_BASE_URL}/v1/audit/events?event_type=policy_updated&start_time=2024-01-01T00:00:00Z&end_time=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "events": [
    {
      "event_id": "evt_abc123",
      "event_type": "policy_updated",
      "actor": "admin@example.com",
      "timestamp": "2024-01-15T10:30:00Z",
      "tenant_id": "tenant_abc123",
      "product_id": "prod_xyz789",
      "payload": {
        "old_policy": {
          "mode": "NOTIFY_ONLY",
          "pinned_range": null
        },
        "new_policy": {
          "mode": "AUTO_INSTALL",
          "pinned_range": ">=1.2.0,<2.0.0"
        }
      },
      "ip_address": "192.0.2.1"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

Step 3: Query Release Approval Events

Query all release approval events:

curl "${BP_BASE_URL}/v1/audit/events?event_type=release_approved&tenant_id=tenant_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "events": [
    {
      "event_id": "evt_xyz789",
      "event_type": "release_approved",
      "actor": "admin@example.com",
      "timestamp": "2024-01-15T10:30:00Z",
      "release_id": "rel_abc123",
      "payload": {
        "release_id": "rel_abc123",
        "product_id": "prod_xyz789",
        "version": "1.2.3",
        "channel": "stable",
        "approval_notes": "Reviewed release notes and verified artifacts."
      }
    }
  ]
}

Step 4: Query License Usage Events

Query license lease and revocation events:

curl "${BP_BASE_URL}/v1/audit/events?event_type=lease_issued&start_time=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "events": [
    {
      "event_id": "evt_def456",
      "event_type": "lease_issued",
      "actor": "system",
      "timestamp": "2024-01-15T10:30:00Z",
      "tenant_id": "tenant_abc123",
      "product_id": "prod_xyz789",
      "payload": {
        "lease_id": "lease_abc123",
        "entitlement_id": "ent_xyz789",
        "subject_type": "user",
        "subject_id": "user@example.com",
        "expires_at": "2024-01-16T10:30:00Z"
      }
    }
  ]
}

Step 5: Export Audit Logs

Export audit logs for a time period:

curl -X POST "${BP_BASE_URL}/v1/audit/export" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-31T23:59:59Z",
    "format": "json",
    "event_types": ["policy_updated", "release_approved", "lease_issued"]
  }'

Response:

{
  "export_id": "exp_abc123",
  "status": "pending",
  "estimated_completion": "2024-01-15T10:35:00Z"
}

Poll for export completion:

curl "${BP_BASE_URL}/v1/audit/exports/exp_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "export_id": "exp_abc123",
  "status": "completed",
  "download_url": "https://storage.example.com/exports/exp_abc123.json",
  "expires_at": "2024-01-22T10:30:00Z",
  "event_count": 12345
}

Step 6: Verify Audit Log Integrity

Verify that audit logs are complete and unmodified:

curl "${BP_BASE_URL}/v1/audit/integrity?start_time=2024-01-01T00:00:00Z&end_time=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "verified": true,
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-31T23:59:59Z",
  "total_events": 12345,
  "gaps": [],
  "checksum": "sha256:abc123..."
}

Common Audit Queries

Policy Changes by Tenant

curl "${BP_BASE_URL}/v1/audit/events?event_type=policy_updated&tenant_id=tenant_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Release Approvals by Approver

curl "${BP_BASE_URL}/v1/audit/events?event_type=release_approved&actor=admin@example.com" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Access Failures

curl "${BP_BASE_URL}/v1/audit/events?event_type=access_denied&start_time=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer $BP_API_TOKEN"

License Usage by Product

curl "${BP_BASE_URL}/v1/audit/events?event_type=lease_issued&product_id=prod_xyz789&start_time=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Audit Event Types

Common audit event types include:

• policy_created — Policy created
• policy_updated — Policy modified
• policy_deleted — Policy removed
• release_created — Release created
• release_approved — Release approved
• release_rejected — Release rejected
• release_distributed — Release distributed to clients
• entitlement_imported — License entitlement imported
• lease_issued — License lease issued
• lease_revoked — License lease revoked
• role_assigned — Role assigned to user
• role_removed — Role removed from user
• access_denied — Authorization failure
• tenant_created — Tenant created
• tenant_updated — Tenant modified

Preparing for Audits

Before an Audit

1. Verify audit logging is enabled — Ensure all events are being recorded
2. Review retention policy — Confirm logs are retained for required periods
3. Test export functionality — Verify you can export logs in required formats
4. Document access procedures — Ensure auditors can access audit logs
5. Review recent events — Identify any anomalies or gaps

During an Audit

1. Provide read-only access — Grant auditors read-only access to audit logs
2. Export requested data — Generate exports for specific time periods or event types
3. Explain context — Provide context for events if needed
4. Document findings — Record any issues or gaps identified

After an Audit

1. Address findings — Remediate any issues identified
2. Update procedures — Improve audit readiness based on lessons learned
3. Review retention — Ensure retention policies meet requirements
4. Test recovery — Verify audit log backup and recovery procedures

Audit Log Retention

Audit logs are retained according to your configuration:

• Default retention: 7 years (2555 days)
• Configurable: Retention can be adjusted per organization
• Backup: Audit logs are backed up separately from operational data
• Export: Logs can be exported before retention expiration

Best Practices

Regular reviews: Periodically review audit logs to identify anomalies or unauthorized access.

Export before expiration: Export logs before retention expiration if long-term storage is required.

Monitor gaps: Alert on audit log gaps or failures to ensure continuous logging.

Secure storage: Store exported audit logs securely with appropriate access controls.

Document procedures: Document audit log access and export procedures for auditors.

Related Documentation

• Compliance Reporting — Generate compliance reports from audit data
• Role-Based Access Control — Control who can access audit logs
• Operational Best Practices — Security and operational guidance