Audit logging

Every tool call produces exactly one result event (tool_invocation) in an append-only, hash-chained JSON-lines log, whether it succeeded, failed at Gitea, failed validation or hit an internal error. A call to a known tool is preceded by a small write-ahead event (tool_call_started, see Location and permissions). 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`, `tool_call_started`, `access_denied` 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;
who called: the MCP client id of the verified token (aegis-static-bearer for the static bearer), a 12 character hash of the OAuth grant's session id (session, only for OAuth tokens, never the id or a token) and the source address (client_ip, HTTP only; behind a proxy it is the forwarded address only when the proxy is in FORWARDED_ALLOW_IPS);
the argument names, sorted, and only names that are properties of the tool's schema; any other name is counted in rejected_argument_count. Argument values are never logged, so request bodies, secret values and file contents do not reach the log. A call to a tool that does not exist is recorded as (unknown tool, N chars): the caller's string is neither logged nor echoed in the error.

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. The check does not stop at startup: each call to a known tool first writes a tool_call_started entry (tool name, domain and correlation id), and when that write fails (full disk, revoked mount, closed file) the call is refused with audit_unavailable and never reaches Gitea. Calls resume as soon as writes work again. A write failure of the final tool_invocation entry 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 both entries 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.

4.7 KiB Raw Blame History