Latte
8b7bb7205c
Inventory and gap analysis of the 0.2.0 codebase against the full Gitea API and the official gitea-mcp toolset, the B1..B11 + security chunk plan, ADRs 0001-0006 for the full-access rebuild, SDK/OAuth research notes, and the instance swagger pinned for tool generation. The audit-logging doc moves to docs/audit-logging.md.
54 lines
1.2 KiB
Markdown
54 lines
1.2 KiB
Markdown
# Audit Logging
|
|
|
|
## Design
|
|
|
|
Audit logs are append-only JSON lines with hash chaining:
|
|
- `prev_hash`: previous entry hash.
|
|
- `entry_hash`: hash of current entry payload + previous hash.
|
|
|
|
This makes tampering detectable.
|
|
|
|
## Event Types
|
|
|
|
- `tool_invocation`
|
|
- `access_denied`
|
|
- `security_event`
|
|
|
|
Each event includes timestamps and correlation context.
|
|
|
|
## Integrity Validation
|
|
|
|
Use:
|
|
|
|
```bash
|
|
python3 scripts/validate_audit_log.py --path /var/log/aegis-mcp/audit.log
|
|
```
|
|
|
|
Exit code `0` indicates valid chain, non-zero indicates tamper/corruption.
|
|
|
|
## Operational Expectations
|
|
|
|
- Persist audit logs to durable storage.
|
|
- Protect write permissions (service account only).
|
|
- Validate integrity during incident response and release checks.
|
|
|
|
## Rotation
|
|
|
|
The server appends to a single audit file and does not rotate it in process — rotating
|
|
mid-stream would break the `prev_hash`/`entry_hash` chain. Manage growth externally with
|
|
`logrotate` using `copytruncate` so the open file handle keeps appending:
|
|
|
|
```
|
|
/var/log/aegis-mcp/audit.log {
|
|
weekly
|
|
rotate 12
|
|
compress
|
|
missingok
|
|
notifempty
|
|
copytruncate
|
|
}
|
|
```
|
|
|
|
Run `scripts/validate_audit_log.py` against each rotated segment to confirm the chain
|
|
remains intact across rotations before archiving.
|