/secrets — credentials in the keystore, never in plain text
One CLI, scripts/secret (stdlib Python 3.10+, no install), and one registry of
metadata only. Values live in the OS keystore; everything a human or an agent sees
is masked to the first 4 characters and the length: cfut…(45).
S=${CLAUDE_PLUGIN_ROOT:-.}/skills/secrets/scripts/secret # or copy the path; alias it
When a secret appears — do this, in order
- Never echo it back. Do not repeat, quote or "confirm" the value in a reply, a
commit, a file or a command line. Refer to it by name.
- Was it seen anywhere that keeps logs? A chat, an agent transcript, a screenshot,
CI output, a ticket, a commit (even one later amended): it is leaked. Run
secret leak <name> --where "<where>" and tell the user to rotate it now.
Claude Code writes prompts to ~/.claude/projects/*/*.jsonl; a blocked prompt is
still echoed there.
- Store it from stdin, never argv:
pbpaste | secret set example-api-token --class api-scoped --used-in "<tool>"
(or run secret set <name> for a hidden prompt). Shell history and ps both see argv.
- Point the code at the keystore (
secret migrate prints the snippet), then blank
the plaintext. Keep the old value until the new one works; never delete the only copy.
- Rotate when it is leaked or due:
secret rotate <name> shows where to issue a new
value, stores it, and resets the clock. Revoke the old value at the provider.
Commands
| Command |
Does |
secret set <name> [--class C --scope S --used-in P --rotate-url U --note T] |
value from stdin or a hidden prompt → keystore; metadata → registry |
secret add <name> [same flags] |
metadata only: an item already in the keystore, or one tracked for rotation |
secret get <name> |
value to stdout, for piping: TOKEN="$(secret get x)" |
secret exec A=ENV [B=ENV2] -- cmd |
runs one command with the values in its environment, nothing exported |
secret list |
metadata + whether the keystore holds the item |
secret due |
overdue / due in 30 days; exit 1 when overdue |
secret rotate <name> [--revoked] |
guided rotation; --revoked = old value killed, no replacement |
secret leak <name> --where W |
class → leaked, due today |
secret scan [paths] [--json] [--min high] [--gh] |
plaintext secrets, masked; --gh asks GitHub if a remote is PUBLIC |
secret migrate <file> <key> <name> [--remove] |
a.b.c in YAML or KEY in env/toml/ini → keystore, read back, then (optionally) blanked |
secret check [paths] |
one counted line for a recurring health check; exit 1 on critical/high/overdue |
Registry: $SECRETS_REGISTRY, default ~/.config/secrets/registry.json. It holds no
values, so it can be committed to a private repo. Its scan block takes paths
(default scan roots), exclude (globs) and owners (remote substrings that are yours;
a tracked hit in a clone of someone else's repo is reported low).
Policies
| Class |
Rotate every |
For |
prod-admin |
90 days |
account-wide or write access to production: cloud admin, DNS, payments, DB owner |
api-scoped |
180 days |
a token limited to one API and one project (the default) |
personal-low |
365 days |
read-only or low-blast-radius personal tokens |
leaked |
now |
anything seen in a chat, log, screenshot, commit or public place |
Rules that do not bend:
- Never in git, not even a private repo, not even "for a minute". History keeps it.
- Never in argv or shell history. Pipe from stdin or use the hidden prompt.
- Never in a plain config that a tool reads; configs hold the keystore name.
- Least privilege, one token per tool. A token shared by three tools cannot be
rotated without breaking two of them, and its leak has three blast radii.
- Leak → rotate now, not at the next due date. Removing it from the file does not
un-leak it.
- Files that must exist as files (
.p8, .pem, service-account JSON): keep them in
~/.secrets/ with chmod 600 (directory 700), outside every repo, and register
them with secret add <name> --note "file: ~/.secrets/…". If a tool can take the
content instead of a path, store it base64: base64 < key.p8 | secret set example-p8-key
and decode at use: secret get example-p8-key | base64 -d.
Scan
secret scan walks the paths (skipping node_modules, venvs, build output, lockfiles,
files over 1 MB) and reports three kinds of evidence:
- prefixed tokens —
sk-, sk-ant-, ghp_, github_pat_, glpat-, xox?-,
AKIA, AIza, cfut_, hf_, npm_, whsec_, Telegram bot tokens, JWTs, private key
blocks, DSN passwords. Counted anywhere, docs and tests included.
- name = value — a secret-sounding name (
*_TOKEN, api_key, clientSecret…)
with a value that is not a reference (${X}, os.environ, config.x), a placeholder,
a URL, a path or an identifier, and has the entropy of a key. In code files only quoted
literals count; in tests, docs, examples and translations only long high-entropy ones.
- key files by name —
AuthKey_*.p8, *.pem, *.p12, service-account JSON,
*token*.txt.
Severity is about where it sits, not what it is: critical = tracked in git (strong
rule, or any rule in a PUBLIC repo); high = untracked but not gitignored, one git add -A
from a commit; medium = gitignored or outside git, plaintext still to move; low = a
Supabase anon JWT (public by design) or a third-party clone. A bare hash or UUID is never
flagged on its own. A line can opt out with secret-scan: ignore.
A tracked secret is not fixed by deleting the file. It is in history and in every
clone: rotate first, then decide whether to rewrite history (git filter-repo) — that is
the owner's call, it breaks every clone and fork.
Other keystores
The CLI picks the backend: macOS security (Keychain, generic password,
service=<name>, account=$USER), else Linux secret-tool (libsecret, needs a running
Secret Service such as GNOME Keyring). For 1Password, store with
op item create --category "API Credential" --title example-api-token and read with
op read "op://Private/example-api-token/credential"; op run --env-file is the
equivalent of secret exec. Keep the registry either way: rotation dates are the part no
keystore tracks for you.
Gotchas
security add-generic-password -w <value> puts the value in argv. The CLI writes
through security -i on stdin with a hex value instead.
security find-generic-password -w prints hex for values with non-printable bytes;
store binary as base64.
- The first read of a Keychain item from a new binary may raise a macOS prompt; "Always
Allow" binds it to that binary path.
- A gitignored
.env is still plaintext on disk and in every backup; it is medium, not fine.
Don't
- Don't paste the value into the chat to "check it". Use
secret list (masked).
- Don't commit the registry to a public repo: names, scopes and file paths are a map for
an attacker even without values.
- Don't rewrite git history to "fix" a leak before rotating. The old value is already out.
1---2name: solo-secrets3description: Keep API keys, tokens and passwords out of repos, configs, argv and chat logs — store them in the OS keystore (macOS Keychain, Linux libsecret), track rotation, scan for plaintext and migrate it. Use when user says "куда положить токен", "где хранить ключ", "секрет", "пароль в конфиге", "api key", "store this token", ".env", "rotate the key", "ротация", "токен утёк", "scan for secrets", or a credential shows up in a file, a prompt or a tool output. Do NOT use for auth flows inside an app (use /deploy or the stack template) or for redacting transcripts (the secret_guard hook does that).4license: MIT5metadata:6 source: https://skillmd.com/skills/fortunto2/solo-secrets7 author: fortunto28 version: "1.0.0"9 openclaw:10 emoji: "🔐"11allowed-tools: Read, Bash, Grep, Glob, Edit12argument-hint: "[scan <path> | set <name> | migrate <file> <key> <name> | due]"13---1415# /secrets — credentials in the keystore, never in plain text1617One CLI, `scripts/secret` (stdlib Python 3.10+, no install), and one registry of18**metadata only**. Values live in the OS keystore; everything a human or an agent sees19is masked to the first 4 characters and the length: `cfut…(45)`.2021```bash22S=${CLAUDE_PLUGIN_ROOT:-.}/skills/secrets/scripts/secret # or copy the path; alias it23```2425## When a secret appears — do this, in order26271. **Never echo it back.** Do not repeat, quote or "confirm" the value in a reply, a28 commit, a file or a command line. Refer to it by name.292. **Was it seen anywhere that keeps logs?** A chat, an agent transcript, a screenshot,30 CI output, a ticket, a commit (even one later amended): it is **leaked**. Run31 `secret leak <name> --where "<where>"` and tell the user to rotate it now.32 Claude Code writes prompts to `~/.claude/projects/*/*.jsonl`; a blocked prompt is33 still echoed there.343. **Store it** from stdin, never argv: `pbpaste | secret set example-api-token --class api-scoped --used-in "<tool>"`35 (or run `secret set <name>` for a hidden prompt). Shell history and `ps` both see argv.364. **Point the code at the keystore** (`secret migrate` prints the snippet), then blank37 the plaintext. Keep the old value until the new one works; never delete the only copy.385. **Rotate** when it is leaked or due: `secret rotate <name>` shows where to issue a new39 value, stores it, and resets the clock. Revoke the old value at the provider.4041## Commands4243| Command | Does |44|---|---|45| `secret set <name> [--class C --scope S --used-in P --rotate-url U --note T]` | value from stdin or a hidden prompt → keystore; metadata → registry |46| `secret add <name> [same flags]` | metadata only: an item already in the keystore, or one tracked for rotation |47| `secret get <name>` | value to stdout, for piping: `TOKEN="$(secret get x)"` |48| `secret exec A=ENV [B=ENV2] -- cmd` | runs one command with the values in its environment, nothing exported |49| `secret list` | metadata + whether the keystore holds the item |50| `secret due` | overdue / due in 30 days; exit 1 when overdue |51| `secret rotate <name> [--revoked]` | guided rotation; `--revoked` = old value killed, no replacement |52| `secret leak <name> --where W` | class → `leaked`, due today |53| `secret scan [paths] [--json] [--min high] [--gh]` | plaintext secrets, masked; `--gh` asks GitHub if a remote is PUBLIC |54| `secret migrate <file> <key> <name> [--remove]` | `a.b.c` in YAML or `KEY` in env/toml/ini → keystore, read back, then (optionally) blanked |55| `secret check [paths]` | one counted line for a recurring health check; exit 1 on critical/high/overdue |5657Registry: `$SECRETS_REGISTRY`, default `~/.config/secrets/registry.json`. It holds no58values, so it can be committed to a **private** repo. Its `scan` block takes `paths`59(default scan roots), `exclude` (globs) and `owners` (remote substrings that are yours;60a tracked hit in a clone of someone else's repo is reported `low`).6162## Policies6364| Class | Rotate every | For |65|---|---|---|66| `prod-admin` | 90 days | account-wide or write access to production: cloud admin, DNS, payments, DB owner |67| `api-scoped` | 180 days | a token limited to one API and one project (the default) |68| `personal-low` | 365 days | read-only or low-blast-radius personal tokens |69| `leaked` | now | anything seen in a chat, log, screenshot, commit or public place |7071Rules that do not bend:7273- **Never in git**, not even a private repo, not even "for a minute". History keeps it.74- **Never in argv or shell history.** Pipe from stdin or use the hidden prompt.75- **Never in a plain config** that a tool reads; configs hold the keystore *name*.76- **Least privilege, one token per tool.** A token shared by three tools cannot be77 rotated without breaking two of them, and its leak has three blast radii.78- **Leak → rotate now**, not at the next due date. Removing it from the file does not79 un-leak it.80- **Files that must exist as files** (`.p8`, `.pem`, service-account JSON): keep them in81 `~/.secrets/` with `chmod 600` (directory `700`), outside every repo, and register82 them with `secret add <name> --note "file: ~/.secrets/…"`. If a tool can take the83 content instead of a path, store it base64: `base64 < key.p8 | secret set example-p8-key`84 and decode at use: `secret get example-p8-key | base64 -d`.8586## Scan8788`secret scan` walks the paths (skipping `node_modules`, venvs, build output, lockfiles,89files over 1 MB) and reports three kinds of evidence:9091- **prefixed tokens** — `sk-`, `sk-ant-`, `ghp_`, `github_pat_`, `glpat-`, `xox?-`,92 `AKIA`, `AIza`, `cfut_`, `hf_`, `npm_`, `whsec_`, Telegram bot tokens, JWTs, private key93 blocks, DSN passwords. Counted anywhere, docs and tests included.94- **name = value** — a secret-sounding name (`*_TOKEN`, `api_key`, `clientSecret`…)95 with a value that is not a reference (`${X}`, `os.environ`, `config.x`), a placeholder,96 a URL, a path or an identifier, and has the entropy of a key. In code files only quoted97 literals count; in tests, docs, examples and translations only long high-entropy ones.98- **key files by name** — `AuthKey_*.p8`, `*.pem`, `*.p12`, service-account JSON,99 `*token*.txt`.100101Severity is about **where it sits**, not what it is: `critical` = tracked in git (strong102rule, or any rule in a PUBLIC repo); `high` = untracked but not gitignored, one `git add -A`103from a commit; `medium` = gitignored or outside git, plaintext still to move; `low` = a104Supabase anon JWT (public by design) or a third-party clone. A bare hash or UUID is never105flagged on its own. A line can opt out with `secret-scan: ignore`.106107**A tracked secret is not fixed by deleting the file.** It is in history and in every108clone: rotate first, then decide whether to rewrite history (`git filter-repo`) — that is109the owner's call, it breaks every clone and fork.110111## Other keystores112113The CLI picks the backend: macOS `security` (Keychain, generic password,114service=`<name>`, account=`$USER`), else Linux `secret-tool` (libsecret, needs a running115Secret Service such as GNOME Keyring). For 1Password, store with116`op item create --category "API Credential" --title example-api-token` and read with117`op read "op://Private/example-api-token/credential"`; `op run --env-file` is the118equivalent of `secret exec`. Keep the registry either way: rotation dates are the part no119keystore tracks for you.120121## Gotchas122123- `security add-generic-password -w <value>` puts the value in argv. The CLI writes124 through `security -i` on stdin with a hex value instead.125- `security find-generic-password -w` prints hex for values with non-printable bytes;126 store binary as base64.127- The first read of a Keychain item from a new binary may raise a macOS prompt; "Always128 Allow" binds it to that binary path.129- A gitignored `.env` is still plaintext on disk and in every backup; it is `medium`, not fine.130131## Don't132133- Don't paste the value into the chat to "check it". Use `secret list` (masked).134- Don't commit the registry to a public repo: names, scopes and file paths are a map for135 an attacker even without values.136- Don't rewrite git history to "fix" a leak before rotating. The old value is already out.