ai-agent/symphony-ai-agent/security/audit-log-format.md

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

{
  "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