# RBAC Audit Log Format Specification

## Version: 1.0  
**Last Updated:** 2025-05-05  
**Author:** Symphony Security Team  
**Applicable Requirements:** SYM-SEC-004  

## Log Entry Format
Each audit log entry is a JSON object with the following required fields:

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| timestamp | string | UTC timestamp in ISO 8601 format with 'Z' suffix | Yes |
| sequence | integer | Monotonically increasing sequence number | Yes |
| user | string | User identifier | Yes |
| resource | string | Resource being accessed | Yes |
| action | string | Action being performed | Yes |
| operation_type | string | Combined resource.action identifier | Yes |
| success | boolean | Whether access was granted | Yes |
| reason | string | Reason for success/failure | No |
| role | string | Role involved in the attempt | No |
| cert_fingerprint | string | Certificate fingerprint if available | No |
| signature | string | HMAC-SHA256 signature for integrity | Yes |

## Example Log Entry
```json
{
  "timestamp": "2025-05-05T20:58:13.123456Z",
  "sequence": 42,
  "user": "admin@example.com",
  "resource": "admin",
  "action": "configure",
  "operation_type": "admin.configure",
  "success": true,
  "role": "admin",
  "cert_fingerprint": "a1b2c3...",
  "signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
```

## Integrity Verification
1. Each log entry contains an HMAC-SHA256 signature
2. To verify:
   - Remove the 'signature' field from the entry
   - Sort the JSON keys alphabetically
   - Generate HMAC using the system's secret key
   - Compare with the stored signature

## Security Considerations
- Log entries must never contain sensitive data
- HMAC key must be rotated periodically (recommended every 90 days)
- Logs should be stored in append-only, tamper-evident storage
- Sequence numbers must never decrease or repeat
- All timestamps must be in UTC

## Implementation Notes
- See `RBACEngine._audit_access_attempt()` for implementation
- Test coverage must verify:
  - All required fields are present
  - HMAC verification works correctly
  - Sequence numbers increment properly
  - Thread safety of audit logging