Skip to content

token-hygiene.md

Latest commit

 

History

History
55 lines (30 loc) · 5.39 KB

token-hygiene.md

File metadata and controls

55 lines (30 loc) · 5.39 KB

Token hygiene

The CLAUDE.md ### Token hygiene section is the headline rule plus the canonical env-var name; this file is the full spec and the surrounding placeholder / cross-repo-path conventions.

Headline

Never emit the raw value of any secret to tool output, commits, comments, or replies. The .claude/hooks/token-guard/ PreToolUse hook blocks the deterministic patterns (literal token shapes, env dumps, .env* reads, unfiltered curl -H "Authorization:", sensitive-name commands without redaction). When the hook blocks a command, rewrite — don't bypass.

Behavior the hook can't catch: redact token / jwt / access_token / refresh_token / api_key / secret / password / authorization fields when citing API responses. Show key names only when displaying .env.local. If a user pastes a secret, treat it as compromised and ask them to rotate.

Full hook spec in .claude/hooks/token-guard/README.md.

Where tokens live

Tokens belong in env vars (CI) or the OS keychain (dev local) — nowhere else. Never in .env / .env.local / .envrc / ~/.sfw.config / ~/.config/socket/* / any dotfile. Dotfiles leak via accidental commits, file-indexers, backup clients, shell-history dumps. Enforced by .claude/hooks/no-token-in-dotenv-guard/.

Initial setup + rotation

  • Initial setup: node .claude/hooks/setup-security-tools/install.mts (prompts + persists via macOS Keychain / Linux libsecret / Windows CredentialManager).
  • Rotation: node .claude/hooks/setup-security-tools/install.mts --rotate — TTY-muted prompt, overwrites the keychain entry unconditionally, ignores stale dotfile / env-var lookup. This is the ONLY correct rotator. Suggesting any other path (socket login, hand-editing ~/.sfw.config, export SOCKET_API_TOKEN=… in a shell rc) is a token-hygiene violation.

The Stop-hook flags broken sfw shims, free-vs-enterprise edition drift, and 401-rejection patterns from the last assistant turn (enforced by .claude/hooks/setup-security-tools/).

Scoped install entrypoints

Four entrypoints share the umbrella installer library for operators who want partial installs:

  • .claude/hooks/setup-firewall/ — sfw only, --rotate honored.
  • .claude/hooks/setup-claude-scanners/ — AgentShield + zizmor.
  • .claude/hooks/setup-basics-tools/ — TruffleHog + Trivy + OpenGrep + uv.
  • .claude/hooks/setup-misc-tools/ — cdxgen + synp + janus.

Never call platform keychain CLIs from Bash

security find-generic-password (macOS), secret-tool lookup (Linux), Get-StoredCredential (Windows PowerShell), keyring get (cross-platform) all surface a UI auth prompt on the user's screen — and that prompt fires per call, so a hook chain that reads the keychain three times costs three prompts. The token is already cached in process memory after the first resolution (see api-token.mts module-scope cache); read it from findApiToken() or process.env.SOCKET_API_KEY / SOCKET_API_TOKEN instead.

Writes (security add-generic-password, secret-tool store, New-StoredCredential) and deletes are allowed — they happen during operator-driven setup / rotation, never on hot paths. Bypass: Allow blind-keychain-read bypass (enforced by .claude/hooks/no-blind-keychain-read-guard/).

Personal-path placeholders

When a doc / test / comment needs to show an example user-home path, use the canonical platform-specific placeholder so the personal-paths scanner recognizes it as documentation: /Users/<user>/... (macOS), /home/<user>/... (Linux), C:\Users\<USERNAME>\... (Windows). Don't drift to <name> / <me> / <USER> / <u> etc. — the scanner accepts anything in <...> but a fleet-wide audit relies on the canonical strings being grep-able. Env vars ($HOME, ${USER}, %USERNAME%) also satisfy the scanner.

Socket API token env var

Two layers, on purpose:

  1. Fleet-canonical name (forward-looking) — SOCKET_API_TOKEN. This is what new .env.example files, fleet docs, workflow inputs, action env: blocks, and CI secrets target. SOCKET_SECURITY_API_TOKEN and SOCKET_SECURITY_API_KEY remain accepted aliases for one cycle (deprecation grace period).

  2. Local-dev primary slot — SOCKET_API_KEY. Every Socket tool (CLI, SDK, sfw, fleet scripts) reads SOCKET_API_KEY without a fallback chain, so picking it as the one stored / exported slot means a single read covers the whole surface. The setup-security-tools install hook stores the token under keychain account SOCKET_API_KEY and exports SOCKET_API_KEY from the ~/.zshenv shell-rc-bridge block. Bootstrap hooks read both — SOCKET_API_KEY first, SOCKET_API_TOKEN as a forward-canonical fallback — so a consumer setting either works.

Don't confuse any of these with SOCKET_CLI_API_TOKEN (socket-cli's separate setting).

Cross-repo path references

../<fleet-repo>/... (relative escape) and /<abs-prefix>/projects/<fleet-repo>/... (absolute sibling-clone) are both forbidden. Either form hardcodes a clone-layout assumption that breaks in CI / fresh clones / non-standard checkouts. Import via the published npm package (@socketsecurity/lib/<subpath>, @socketsecurity/registry/<subpath>) — every fleet repo is a real workspace dep. The cross-repo-guard PreToolUse hook blocks both forms at edit time; the git-side scanCrossRepoPaths gate catches commits/pushes too.