q-ring 101 - prove who read what (qring audit)

ガイド

What it does

Every read, write, and delete that goes through q-ring is appended to an audit log at ~/.config/q-ring/audit.jsonl. Each event records the time, the action, the key name, scope, source (CLI, MCP, hook, and so on), and the process id. It never records the value. Each line carries a SHA-256 hash of the line before it, and the chain is anchored with a keyed HMAC kept in the OS keyring, so qring audit:verify can tell when lines were edited, removed from the end, or the whole file was rewritten.

Try it

# Recent events, or one key's history
qring audit
qring audit --key OPENAI_API_KEY --action read --limit 50

# Flag bursts, reads between 1 and 5 a.m., new sources, tampering
qring audit --anomalies

# Prove nobody rewrote history
qring audit:verify

# One timeline per agent session
qring audit:sessions --since 24h

# Hand it to someone else
qring audit:export --format csv --output audit-report.csv

Why it matters

When a key leaks, the first question is which process read it and when. Without a record you are guessing. With MCP clients in the mix, the answer has to cover agents too: events from an MCP session are stamped with the client's name and version, such as a Cursor or Claude Code build, so qring audit --agent <label> and qring audit:sessions can show what one agent touched in one session, by key name. The hash chain matters because a log that can be quietly edited cannot settle anything.

Gotchas and good to know

• The agent label is whatever the client reports at the MCP handshake. It is useful for attribution and trivially spoofable, so q-ring never uses it for authorization.
• The log is local and tamper-evident, not tamper-proof, and it is not a compliance certification. An attacker running code as your user is out of scope in the threat model. What the chain stops is a quiet rewrite: edits, truncation, and replaced files fail audit:verify.
• It records access that goes through q-ring. Reading the keychain with another tool, such as security or secret-tool, bypasses it.
• Agents can see their own history as MCP resources (qring://sessions). Denying the audit_log tool in policy hides those too.
• Run qring audit:verify on a schedule, not just after something goes wrong.

Go deeper

• Rotation and audit habits
• CLI reference
• Threat model