q-ring 101 - prove who read what (qring audit)
q-ring logs every read, write, and delete in a hash-chained audit log. qring audit shows who read what; audit:verify proves nobody rewrote it.
指南
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
securityorsecret-tool, bypasses it. - Agents can see their own history as MCP resources (
qring://sessions). Denying theaudit_logtool in policy hides those too. - Run
qring audit:verifyon a schedule, not just after something goes wrong.
Go deeper
文字稿
选择时间戳，即可从该时间点开始播放视频。