convez.ai
AgenteSegurançaAvançado
rashedInt32

Claude Code Permission Setup com Safety Hooks

rashedInt32/claude-config

Permissões seguras para Claude Code: leitura livre, escrita controlada

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que implementa um modelo de permissões granulares para Claude Code seguindo o princípio "lê livremente, grava com confirmação". Inclui seis hooks de segurança que bloqueiam acesso a secrets, validam instalações de pacotes, fecham brechas em flags git, autorizam operações localhost e filtram operações destrutivas em find/pipelines.

Instalação

$npx convez-ai rashedInt32/claude-config

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Configurar Claude Code para trabalhar em repositórios sensíveis sem risco de exposição de secrets
  • Automatizar bloqueio de operações destrutivas (installs, deletes, history rewrites) com confirmação
  • Implementar modelo de segurança baseado em regras estáticas + hooks dinâmicos para gaps

Veredito

Solução técnica bem arquitetada para quem precisa de controle fino sobre permissões do Claude Code em ambientes compartilhados ou sensíveis. Exige conhecimento de Bash, jq e configuração manual, mas oferece proteção robusta contra operações perigosas via padrões dinâmicos.

README

A tradução para o português deste README ainda está na fila.

claude-config

A curated Claude Code permission setup plus six safety hooks. The guiding principle:

Read freely, gate on write. Investigation/read commands run without prompting; anything that changes state (writes, pushes, history rewrites, installs, deletes) still asks.

The real value is settings.example.json (the permission model) and the six hooks in hooks/ that close gaps a static allowlist can't.

What's inside

hooks/
  deny-secret-access.sh       # block Bash access to .env / keys / credential stores
  ask-on-package-install.sh   # always confirm npm/pnpm/yarn/bun installs
  git-flag-guard.sh           # close the `git -C` / global-flag bypass
  allow-localhost-curl.sh     # auto-allow localhost curl/wget, ask otherwise
  find-guard.sh               # auto-allow read-only find, ask on -delete/-exec/...
  allow-readonly-pipeline.sh  # auto-allow all-read-only pipelines (incl. read-only git + sed/awk) the built-in matcher balks at
settings.example.json         # permissions (allow/deny/ask) + hook wiring

Requirements

  • Claude Code
  • jq, bash, grep, sed (preinstalled on macOS; standard on Linux)

Install

  1. Copy the hooks into your Claude hooks directory and make them executable:

    mkdir -p ~/.claude/hooks
    cp hooks/*.sh ~/.claude/hooks/
    chmod +x ~/.claude/hooks/*.sh
    
  2. Merge settings.example.json into ~/.claude/settings.json. If you don't have one yet, copy it as a starting point. If you do, merge the permissions and hooks blocks (arrays are additive — don't drop your existing entries). The hook commands reference $HOME/.claude/hooks/..., so they work for any user.

  3. Edit the one machine-specific rule. In permissions.allow, replace

    "Bash(cd /CHANGE-ME/to/your/projects/root*)"
    

    with the absolute path to where your code lives, e.g. "Bash(cd /Users/you/code*)". (Permission rules match the literal command text, so use the real absolute path — ~ won't expand here.)

  4. Restart Claude Code. Hooks hot-reload, but permission rules are read at startup — changes to allow/deny/ask only take effect after a restart (or reopening via /hooks).

The six hooks

deny-secret-access.sh

The deny rules for secrets (Read(.env), Read(~/.ssh/**), Read(//**/*.pem), …) are scoped to the Read/Edit/Write tools — Bash bypasses them, and cat/grep/rg/cp are allowlisted with :*, so cat .env or cat ~/.ssh/id_rsa would read secrets straight to stdout. This hook extends the same protection to Bash. When a command references a secret path (.env, id_rsa/ id_ed25519, *.pem/*.key/*.p12, .aws/.ssh/.gnupg/.kube/gcloud dirs, .netrc, .git-credentials, .docker/config.json, service-account*.json, secrets/, *.secret) it is denied if it would expose the contents — a read/copy/transmit/interpret verb (cat, grep, rg, head, cp, tar, curl, base64, python, …) or a redirect that writes into a secret path (echo pwn >> ~/.ssh/authorized_keys). A deny beats every allow, including the other hooks.

Metadata-only ops are allowed, since they expose nothing: ls/stat/file/test/find and chmod/chown on a key, plus git (so commit messages mentioning .env don't trip it). It scans a quote-stripped copy so real paths are caught but prose isn't, and config templates (.env.example/.sample/.template/.dist/.defaults/.schema) are exempt. Fail-safe: it only ever denies or stays silent.

ask-on-package-install.sh

The package managers (npm, pnpm, yarn, bun) are allowlisted so build/run/test commands don't prompt — but installs always should. This hook detects install/add/ci/update/upgrade/i anywhere in the command (including npx pnpm@9 install, pnpm -C pkg add, corepack pnpm add) and forces a confirmation.

git-flag-guard.sh

Allow rules are prefix matches (Bash(git diff:*)). A leading global flag shifts the prefix: git -C /path push starts with git -C, not git push, so it slips past both your ask rule on git push and your deny rules. This hook resolves the real subcommand after skipping global flags (-C, -c, --git-dir, --work-tree, …) and:

  • allows read-only subcommands (diff, log, show, status, …),
  • denies everything else (push, reset, rebase, commit, …) — cd into the repo and use plain git for writes, where your normal rules apply.

It scans the whole command, so compound forms like ls && git -C /x push are caught too. Tokenizes without eval/command-substitution, so the guard itself can't be injected.

allow-localhost-curl.sh

curl/wget are deliberately not in the static ask list (an explicit ask rule overrides a hook's allow). This hook is their sole authority:

  • allow when every http(s) URL is localhost / 127.0.0.1 / ::1, there are no file writes or non-curl command substitutions, and every companion command is read-only (same allowlist as find-guard — so curl localhost && bash -c "…" asks),
  • ask for anything else.

So localhost health-checks and port probes run silently, while outbound curl, file writes (-o, -O, >), @host tricks, and curl localhost && rm -rf ~ all still prompt (and deny rules still hard-block the dangerous ones).

find-guard.sh

find is dual-use — -delete and -exec rm {} \; are destructive — so it's deliberately not allowlisted. But that means every read-only search prompts, which is noise. This hook makes find usable without opening the destructive door:

  • allow read-only find (-type, -name, -ipath, -print, -prune, …),
  • ask when it sees -delete, -exec, -execdir, -ok, -fprint*, -fls, a file redirect, a backtick, or any companion command that isn't provably read-only.

A $(…) is deferred to allow-readonly-pipeline (which vouches the read-only VAR=$(find …) form), so f=$(find . -name X | head -1); grep -n foo "$f" no longer prompts. A destructive find inside $() is still caught here by the -delete/-exec check above.

The companion check is an allowlist, not a denylist — every command-position program must be find, a read-only tool (cat/grep/head/…), or a read-only git/xargs invocation. So find … && git log and find … | xargs grep run without a prompt, while find … && git push, find … | xargs rm, and find … && bash -c "…" / … && ./script.sh all ask — an interpreter or arbitrary executable can hide a destructive payload a word-scan can't see, so it never rides along inside an "allowed" find. Dangerous words inside quotes (-name '*git*', echo "rm -rf") and inside paths don't trip it — only real command-position programs do.

Why a hook instead of "just use fd"? Because a preference to use fd can't be relied on — it doesn't propagate across projects or sessions, and pasted find one-liners ignore it. A hook in settings.json is global and deterministic: read-only find works everywhere, destructive find is gated everywhere. (fd is still allowlisted and is a fine, faster choice when you reach for it.)

allow-readonly-pipeline.sh

Claude Code's built-in matcher auto-approves a compound command only when it can statically decompose it and match every leaf — it gives up on gnarly shells (mixed &&/|/;, 2>/dev/null redirects, !-prefixed glob args), so a read-only search like rg -n foo src --glob '!**/node_modules/**' 2>/dev/null | head prompts even though rg, head, cd are each allowlisted. This hook closes that gap:

  • allow when every segment is a known read-only program (rg, grep, cat, ls, head, tail, wc, sort, uniq, cut, jq, diff, cd, echo, …) and there's no output redirect to a real file,
  • silent (no opinion) otherwise — the other hooks and normal rules still apply.

Command substitution is vouched in one narrow, safe shape: an assignment value, VAR=$(…) (or VAR="$(…)"), where the inner command is itself fully read-only — so f=$(find . -name X | head -1); grep -n foo "$f" auto-allows. The output lands in a variable, never at command position, and a later $var used as a command isn't read-only so it bails. Any other $(…) — at command position ($(printf rm) file), as a bare argument (echo $(date)), nested, or arithmetic — keeps the hook silent. Backticks and process substitution always bail. (find-guard defers its $(…) ask to this hook, so a read-only VAR=$(find …) no longer prompts; a destructive find inside $() is still caught by find-guard's -delete/-exec check.)

It also vouches read-only git (status, log, diff, show, branch, blame, stash list, …), which is what defeats Claude Code's built-in "changes directory before running git, can execute untrusted hooks" prompt on a cd <repo> && git log sweep — that built-in heuristic ignores allowlist rules and can only be overridden by a hook allow. Read-only git is gated tightly: it never includes a mutating subcommand (commit/push/reset/rebase/clean/stash save), bails on a global flag before the subcommand (that's git-flag-guard's job) or an exec/write flag after it (--output, -O, --upload-pack, --ext-diff, …) or a GIT_* env prefix, and — when a cd is present — requires every cd target to stay inside a trusted root (no climbing out via ..), so a malicious sibling repo's config can't ride along.

It also vouches read-only sed/awk as companions, so a sweep like cd repo && grep -n serve f.ts && sed -n '/A/,/B/p' f.ts | head runs without a prompt — honoring read freely. sed/awk can write (-i, the w command, print > file) or execute (sed e, awk system()), so the hook gates exactly those: it rejects the in-place / script-file flags (-i/--in-place/-f/--file, gawk -i inplace) per segment, and scans the quoted script for write/exec constructs — awk system()/getline/print … >/ … | cmd/>>, and sed w/W/r/R/e commands and s///w/s///e flags. Any of those, or a shell redirect, drops it back to a normal prompt. This is footgun-prevention, not a sandbox (the rest of the allowlist already runs arbitrary code via node/npm/make), and deny-secret-access — which runs first — still blocks sed/awk on secret paths.

Because a hook allow bypasses deny, the read-only set is otherwise strict: it excludes every remaining command-runner and writer (find, fd, xargs, tee, node, …), so a write or arbitrary-exec can never ride along inside an "allowed" pipeline.

sed/awk are deliberately not in the static allow list (like find), so this hook is their sole authority: read-only forms auto-allow here, while sed -i, redirects, and the other write/exec forms fall through to a prompt. Note this is footgun-prevention, not a sandbox — the script scan is heuristic and a crafted sed/awk write can evade it; that's acceptable because node/npm/make already run arbitrary code, and deny-secret-access still blocks secret paths. If you want a hard wall, deny sed/awk outright (you lose in-place edits).

Permission model at a glance

  • allow — read-only git (incl. plumbing), coreutils, search tools, and JS runtimes (node/npm/pnpm/bun for build/run — installs are gated by the hook above).
  • ask — git push/--force, git reset --hard, rebase, filter-branch, clean -f/-fd. (curl/wget are handled by the hook, not listed here.)
  • deny — secrets (.env, SSH/GPG/cloud creds) via the Read/Edit/Write tools and via Bash (the deny-secret-access.sh hook), sudo/su, --no-verify commits, push --mirror, and catastrophic rm -rf / mkfs / dd / shutdown forms.

Caveats

  • These are guardrails, not a sandbox. They reduce footguns and prompt fatigue; they don't contain a determined adversary. Review before adopting.
  • Tested on macOS (BSD userland). The hooks use portable constructs but if you hit a GNU/BSD sed/grep quirk, open an issue.
  • Don't commit your real ~/.claude/settings.json — it may contain machine paths, tokens, or org IDs. .gitignore here already excludes settings.json.
Ver o original no GitHub

Bom para

Relacionados