AegisGitea-MCP/docs/audit-logging.md

Audit logging

Every tool call produces exactly one event in an append-only, hash-chained JSON-lines log, whether it succeeded, failed at Gitea, failed validation or hit an internal error. Security events are logged in the same chain.

What an event contains

Each line is one JSON object:

Field	Meaning
timestamp	UTC, ISO 8601
event_type	tool_invocation or security_event
request_id	Correlation id of the request
payload	The event data, see below
prev_hash	entry_hash of the previous line (GENESIS for the first)
entry_hash	SHA-256 over the previous hash and this entry

A tool invocation payload records:

• the tool name, its domain, the HTTP method and the path template (for example /repos/{owner}/{repo}/issues, never the filled-in values);
• the identity: Gitea login and mode (admin-token or oauth), and the sudo user when one was given;
• the HTTP status when Gitea answered, and the outcome: success, or the error kind (not_found, forbidden, invalid_argument, internal_error, ...);
• the duration in milliseconds and the correlation id;
• the argument names, sorted. Argument values are never logged, so request bodies, secret values and file contents do not reach the log.

All payloads also pass through secret masking before they are written (SECRET_DETECTION_MODE other than off).

Integrity

Each entry hashes the previous one, so editing, deleting or reordering a line breaks the chain from that point on. Validate it with:

make validate-audit                                   # default path
uv run python scripts/validate_audit_log.py --path /var/lib/aegis-mcp/audit.log

Exit code 0 means the chain is intact; 1 lists the lines that do not verify. The default path is AUDIT_LOG_PATH, else DATA_DIR/audit.log.

The chain proves that history was not altered after the fact. It does not stop someone with write access to the whole file from rewriting it consistently from the start, so also ship the log to storage the server cannot modify, and compare the latest entry_hash against a copy you keep elsewhere.

Location and permissions

The log is written to AUDIT_LOG_PATH, default DATA_DIR/audit.log (/var/lib/aegis-mcp in the image). Keep it on durable storage, readable and writable only by the service account.

The server opens the file for append at startup and exits with code 2 (message on stderr) when that fails, so it never runs unaudited. Each call also obtains the audit logger before it runs; if that fails the call is refused with audit_unavailable and never reaches Gitea. A write failure after a call has executed is only logged to stderr: the Gitea side effect already happened and the caller must still receive the result. The correlation_id of a tool entry is the request id, which is also the entry's request_id.

Rotation

The server appends to one file and does not rotate it, because rotating mid-stream would break the chain. Rotate externally with logrotate and copytruncate, so the open file handle keeps appending:

/var/lib/aegis-mcp/audit.log {
    weekly
    rotate 12
    compress
    missingok
    notifempty
    copytruncate
}

The validator expects a chain to start at GENESIS, so only the first segment verifies as it is. For a later segment, check that its first prev_hash equals the last entry_hash of the previous segment. Validate segments before archiving them, and keep them in order.

Operating it

• Alert on bursts of forbidden or unauthorized outcomes and on tool calls by unexpected identities.
• Review calls to admin, secret and delete tools. The tool name makes them easy to filter.
• Run the integrity check regularly and during incident response.