SecretSpec 0.12 adds audit logs and agent access controls
SecretSpec `v0.12.0` ships an audit log for every secret read/write, a reason-on-access policy enforced by default for coding agents, and a new `secretspec audit` CLI command for filtering and summarizing the log.
Score breakdown
Audit every agent-initiated secret access with a stated reason, giving teams a traceable record of what coding agents like Claude Code accessed and why during a session.
- 01SecretSpec `v0.12.0` ships an audit log, a reason-on-access policy, and a `secretspec audit` CLI command.
- 02Every secret read and write is appended to a local JSONL file at `~/.local/state/secretspec/audit.log`; secret values are never recorded.
- 03The audit log captures: secret name, profile, provider, outcome, reason, user, and detected coding agent.
SecretSpec `v0.12.0` addresses a specific problem: a coding agent accessing secrets is indistinguishable in logs from a human running a deploy. The release ships three things to close that gap. First, an audit log that appends one JSON Lines event per secret read or write, capturing metadata such as the secret name, profile, provider (with embedded credentials redacted), outcome, reason, and the detected coding agent — but never the secret value itself. The log lives at `~/.local/state/secretspec/audit.log`, is readable only by the local user, and is capped at 1 MiB as a size-bounded recent record rather than a permanent compliance history.
Second, a reason-on-access policy (`require_reason`) that defaults to `"agents"`, meaning any secret access initiated from within a coding agent like Claude Code is refused until a reason is provided.
Second, a reason-on-access policy (`require_reason`) that defaults to `"agents"`, meaning any secret access initiated from within a coding agent like Claude Code is refused until a reason is provided. The agent receives an explicit error message instructing it to retry with `--reason`, the `SECRETSPEC_REASON` environment variable, or `Secrets::with_reason()` in the SDK. Both the refusal and the successful retry are recorded in the audit log, tying the stated reason to the access event. Projects can opt out by setting `require_reason = false` in the `[project]` table of `secretspec.toml`. Third, the new `secretspec audit` command supports filtering by project, action, and count, and can emit raw JSON Lines for piping to `jq`.
Key facts
- 01SecretSpec `v0.12.0` ships an audit log, a reason-on-access policy, and a `secretspec audit` CLI command.
- 02Every secret read and write is appended to a local JSONL file at `~/.local/state/secretspec/audit.log`; secret values are never recorded.
- 03The audit log captures: secret name, profile, provider, outcome, reason, user, and detected coding agent.
- 04The log is capped at 1 MiB and is configured in the user-global `~/.config/secretspec/config.toml`, not the project file.
- 05By default (`require_reason = "agents"`), secret access from inside a coding agent fails until a human-readable reason is supplied.
- 06A reason can be supplied via the `--reason` flag, `Secrets::with_reason()` in the SDK, or the `SECRETSPEC_REASON` environment variable.
- 07Existing providers and library callers are unaffected; projects can opt out by setting `require_reason = false` in `secretspec.toml`.
Topics
Summary and scoring are generated automatically from the original article. We always link back to the publisher and never republish images or paywalled content. Last processed Jun 8, 2026 · 15:36 UTC. How this works →