Audit Log
Audit log and chain verification¶
Every access decision Portunus makes is recorded in a tamper-evident hash chain. The log is append-only; any deletion or modification breaks the chain in a way portunus verify detects.
What is logged¶
Every event recorded to the audit log follows this shape:
| Field | Contents |
|---|---|
seq |
Monotonic sequence number (from a .clock file, never a wall clock) |
actor |
The identity making the request (DOSTAL_AGENT env var for agents, USER for humans) |
task |
The task identifier (DOSTAL_TASK env var, if set) |
action |
What happened: resolve, drop, approve, gate, grant, retag, session_store, session_load, etc. |
secret |
The reference name or SM name being acted on — never the secret value |
result |
Outcome string, e.g. ok:env:MY_VAR, denied-dropped, would-allow:no-policy-configured |
prev |
The hash of the immediately preceding entry (or "genesis" for the first entry) |
h |
SHA-256 of prev + the current entry's JSON body |
The secret value, raw credentials, and caller environment variables are never written. The secret field contains the reference or SM name only — the metadata that describes what was accessed, not what the value is.
How the hash chain works¶
Each entry's hash h is computed over the previous entry's hash (prev) plus the current entry's JSON body:
h = SHA-256(prev_hash + json_body)
The prev field of each entry carries the previous h, forming a chain. The chain root uses the literal string "genesis" as the initial prev. Any edit to any entry — even changing a single character — produces a different h that no longer matches the next entry's prev, making the tampering detectable.
Browsing the log¶
# Show the last 20 entries (default)
portunus audit
# Show only entries for a specific secret reference
portunus audit --secret my-sm-name
# Show more entries
portunus audit --n 100
# Output as JSON
portunus audit --json
Each line shows: sequence number, actor, action, secret name, and result.
Verifying the chain¶
portunus verify
Output is one of:
audit chain: INTACT (N entries)— the hash chain is unbroken; exit code 0.audit chain: BROKEN at line L: <reason> (N entries verified before it)— lineLofaudit.logis unparseable, is missing chain fields, or its hash/prevdoes not match; exit code 2. A corrupt line is reported this way rather than crashing the command.
Run this after a vault restore or whenever you suspect tampering. The reported line is the first point at which the chain stops verifying — everything from there forward cannot be trusted.
The sequence counter¶
seq comes from a counter file (.clock) in the state home. If .clock is missing, unparseable, or behind the log, the next seq is recovered from the highest seq already in audit.log and .clock is rewritten, so the sequence never restarts while the log has entries. Approval TTLs (measured in audit-clock ticks) use the same recovery, so deleting .clock does not change whether an approval is still valid.
What is NOT logged¶
The following are deliberately excluded from every audit entry:
- Secret values — the plaintext of any managed credential.
- Raw credentials — refresh tokens, access tokens, OAuth client secrets.
- Caller environment variables — shell env at the time of the resolve.
- The WIF audience or access token — only the identity and scope metadata of a minted token appear in auth events, never the token itself.
The audit log is safe to share with an administrator for compliance review without risk of exposing any managed secret.