Skip to content

Security: zsz13/claude-code-config

Security

docs/security.md

Security, privacy, and failure modes

Three separate topics: what was deliberately left out of this repository, the security properties of the configuration itself, and how each component fails.


Part 1 — What was excluded from this repository, and why

This repository was assembled by auditing a live installation and classifying every item. It is not a copy of ~/.claude.

Never published — private or stateful

Source Why
~/.claude/projects/** Conversation transcripts (JSONL). Contain full source code, credentials that appeared in output, and private project detail.
~/.claude/projects/**/memory/*.md Per-project memory notes — private architecture, vendor details, business logic. Used as a source for the reasoning in these docs; never copied.
~/.claude/history.jsonl Prompt history.
~/.claude/sessions/, session-env/, shell-snapshots/, paste-cache/, file-history/ Live session state, pasted content, file snapshots.
~/.claude/telemetry/, cache/, downloads/ Generated, machine-local.
~/.claude/backups/, *.backup-*, .last-* Point-in-time copies of the above.
~/.claude.json Per-project harness state, including project paths, and user- and local-scope MCP servers, with any API key in their headers.
~/.claude/.ponytail-active Live mode flag. Publishing it would ship a mode.
~/.claude/plugins/ (caches, installed_plugins.json, known_marketplaces.json) Third-party plugin code plus absolute install paths and commit SHAs. Plugins are named in config/settings.example.json and installed by their own marketplace.
~/.codex/auth.json Credentials. Never read, never copied.
~/.codex/*.sqlite* (logs_, state_, thread_history_, memories_, goals_, queue_) Databases containing conversation history, memories and logs.
~/.codex/.codex-global-state.json, installation_id, session_index.jsonl, sessions/, attachments/, cache/, models_cache.json Machine identifiers and live state.
~/.codex/rules/default.rules A machine-specific command allowlist referencing absolute bootstrap paths under /private/tmp. Useless elsewhere and a bad pattern to copy.
SSH keys, GitHub tokens, .env files Never read. gh auth status output was redacted before it was ever displayed.

Never published — third-party code under a restrictive licence

Source Why
~/.claude/hooks/gitnexus/** (5 files) Vendored hook code from a tool licensed PolyForm Noncommercial 1.0.0. Redistributing it from an MIT repository would be a licence violation. It also contained the only hard-coded absolute machine path found in the whole audit.
~/.claude/skills/gitnexus-* (8 skills) Same tool, same licence. Installed by the tool's own setup command; not ours to redistribute.
~/.codex/hooks.json + ~/.codex/hooks/ Contained only that tool's hooks. Excluded for the same reason.
~/.claude/plugins/cache/** Third-party plugin source (Superpowers, Ponytail, official plugins). Install them from their own marketplaces.

The corresponding settings entries were removed from config/settings.example.json too, so the published configuration does not reference files it does not ship.

Published as sanitized templates

Source Published as What changed
~/.claude/settings.json config/settings.example.json Absolute /Users/<name>/ paths → $HOME; third-party hook entries and the associated env var removed.
~/.config/ponytail/config.json config/ponytail-config.example.json Unchanged (it is one key), published as a template because the value is the policy.
~/.codex/config.toml config/codex/config.example.toml Heavily reduced. Removed: bundled-plugin registrations, MCP server commands with absolute app paths, desktop UI preferences, a local marketplace path, and a per-project trust entry naming a private repository. Kept: model, reasoning effort, approval policy, sandbox mode, output token limit, agent concurrency, network policy.
~/.claude/CLAUDE.md examples/CLAUDE.example.md Unchanged — audited and found to contain only ~-relative paths.
<code-dir>/CLAUDE.md examples/CLAUDE.directory.example.md Unchanged — same audit result. ~/github remains as the directory name; it is a placeholder for wherever you keep code.
~/.codex/AGENTS.md examples/codex-AGENTS.example.md Unchanged — audited, no machine-specific content.

Published as-is

All seven hooks, bin/run-captured, seven judge agents, seven path-scoped rules, ten skills, and seven Codex agent definitions. Every one was scanned for absolute paths, usernames, email addresses, hostnames, tokens and project names. They use ~-relative paths throughout and contain none of those.

Placeholders used

$HOME, ~/github, YOUR_USERNAME, YOUR_REPOSITORY, YOUR_API_KEY.


Part 2 — Security properties of the configuration

The deny-hooks

block-destructive-iac.sh, block-git-no-verify.sh/.py and local-ci-gate.sh/.py are the only hooks that block anything. (The one other block is permissions.deny in settings.json, covered under trust boundaries below.) All three are narrow by design:

  • IaC guard denies terraform/tofu apply, destroy, import, taint, untaint, force-unlock, and state mv|rm|push|replace-provider — including path-qualified binaries, global flags like -chdir=, and occurrences anywhere in a compound command. Read-only operations (init, plan, validate, fmt, show, output, graph, state list|show|pull) are never blocked.
  • No-verify guard denies hook bypasses on commit/push/merge/rebase/ am/cherry-pick/revert, plus -c core.hooksPath= and setting core.hooksPath. --get/--unset/--list on that key are allowed.
  • Local-CI gate denies git push and the gh commands that open or update a PR or start a workflow until every required check of the validation plan recorded for the published content has passed. A trivial check recorded as the only evidence no longer passes it: the plan is derived by local-ci auto, not chosen, and a required check cannot be relabelled unsupported. A repository's .local-ci.json can add checks or exclude a discovered one with a reason, but only as committed on its base branch: the change under validation cannot edit what validates it. It decides from a file under ~/.cache/claude-hooks/local-ci/; a forged record there would pass it, and so would a plan recorded on a machine made to look as if the tools were missing. It stops a careless push, not a deliberate one. The opt-in pre-push hook enforces only while CLAUDECODE is set, so a command that unsets it is not stopped either. It reads the pushed commits from git's object store only, so no repository-configured filter runs before approval.

All three say, in the denial message, what they are and how to remove them. A guard you cannot identify or disable is a trap, not a safety feature.

Known limits, stated honestly:

  • They are not a sandbox. They match command text. A sufficiently indirect invocation (a shell function, a script file, a wrapper that reads the command from a variable) will not match. They exist to stop the obvious mistake, not a determined bypass.
  • The IaC guard does not know about pulumi, cdk deploy, kubectl delete, aws CLI mutations, or helm uninstall. Extend it if you use those.
  • The no-verify guard fails open on an unparseable command. The local-CI gate fails open when local-ci or the scanner it borrows is missing, or the gate times out, and says so in one line.

Running workflows locally with act

A workflow is code from the repository, and act runs it in containers on your Docker engine. local-ci act treats it as untrusted:

  • the act process gets an allowlisted environment: PATH, HOME, locale, Docker connection and proxy variables. GITHUB_TOKEN, GH_TOKEN, cloud and registry credentials are not passed;
  • an empty GITHUB_TOKEN secret, and a throwaway HOME, XDG_CONFIG_HOME and GH_CONFIG_DIR. Without a token act runs gh auth token and hands the workflow your own GitHub token. That was found in review and reproduced: with both token variables unset, a probe step saw a 40-character secrets.GITHUB_TOKEN; with the empty secret it sees none. (A dummy token was tried first: GitHub then rejected the clone of every public action.);
  • --secret-file, --env-file and --var-file point at an empty file, because act otherwise reads .secrets, .env and .vars from the repository;
  • no actrc: a repository .actrc or a user-level actrc with content makes it refuse. act applies them to every run, and a cloned repository's could run its steps directly on the host (-P label=-self-hosted), mount it (--bind) or serve files from it. Parsing them to allow "safe" flags was tried and rejected in review: act expands $VARS in actrc lines, so what a parser sees is not what act runs. A user-level actrc cannot be hidden with a throwaway HOME either: on macOS act 0.2.97 resolved its config directory under the real ~/Library/Application Support regardless;
  • a secret-looking file ignored only through global or .git/info excludes makes it refuse, because act copies the work tree by the repository's .gitignore alone;
  • --container-daemon-socket -: job containers do not get the Docker socket (which is root on the host). With --container-options-policy restrict (act 0.2.97 has it) act also refuses workflow-set host mounts and options; with an older act, jobs that set them, and jobs needing those, are skipped. --docker-socket is an explicit opt-in for trusted workflows, and even then it is refused unless the daemon holds no container or volume act did not create: a job with the socket can reuse or delete everything on the daemon, and a compose file with a pinned project name would adopt the developer's own containers and database volumes;
  • a job that uses Docker is recognised when a step names it and when a step reaches it through a Makefile target (prerequisites, $(MAKE) calls, variables) or a repository script, followed transitively. The match is broad on purpose: a false positive leaves one job to remote CI, a miss runs it;
  • jobs never run on act's default host network. Measured with act 0.2.97 and Docker Desktop on an arm64 Mac: on the host network a job opened the TCP port of the developer's published dev database at 127.0.0.1 and at host.docker.internal. Each run now creates its own bridge network (removed afterwards) and points host.docker.internal and gateway.docker.internal at the job container; there, the same probe found both closed and the internet reachable. Docker Desktop's host-gateway address (192.168.65.254) still answered: a workflow that names that internal address on purpose can reach host ports. So did host.docker.internal from a job with its own container: image, because act gives such a container only the workflow's options, not --container-options (measured the same way); localhost was closed there too. Neither name exists on GitHub's Linux runners, so only a workflow written to reach the developer's machine uses them. That is a deliberate act by the repository's own code, which auto already runs on the host as its local checks (below). Jobs with services: are not run, since they expect the host network;
  • the socket check covers every job, not only those recognised as Docker users: --docker-socket mounts it into all of them, so all are refused on a daemon that holds anything act did not create (its act-toolcache volume and hash-named job containers), and the check is repeated just before act starts;
  • deploy, release and publish jobs, jobs with a deployment environment or write permissions, steps that push, publish, sync files out or call a cloud CLI, and any job that needs one of those (act runs a job's needs: too) are never run;
  • act's default .gitignore handling keeps ignored files (such as .env) out of the copied workspace.

The classification reads names, steps and keys. A workflow can hide a deploy behind an innocent name and a script; local-ci act --list and local-ci auto --plan-only show what will run before anything does, but the automatic flow does not stop to ask. The isolation above is what limits the damage when it does: no credentials, no socket, no host mounts. Mounting the Docker socket gives a job root on the machine, so --docker-socket is the user's decision, never the agent's; the plan says so where it applies.

The repository's own commands run on the host

local-ci auto runs the check commands the repository defines — npm run scripts, Makefile targets, scripts/verify*, pre-commit run, uv run (which installs dependencies), terraform init (which fetches providers) — on the host, with the user's environment, and without act's isolation. A discovered command that starts Docker through a Makefile target or a script is the exception: on the developer's daemon a pinned compose project adopts their containers and down -v deletes their volumes, so it is reported unsupported unless the repository declares it in .local-ci.json. That is the same trust as running the repository's tests by hand, and it is now automatic: the Stop hook asks for it after any session that changed the repository. A repository you would not run make test in is one you should not have the agent edit with this hook installed (or set LOCAL_CI_AUTO=0); allowlisting local-ci auto in the permission settings approves every command it discovers. act jobs are the isolated part: workflow code runs only in containers, never on the host.

The skill-install guard

skill-install-guard.sh/.py blocks nothing outright. It returns ask, so a skill or plugin install, update or removal, or a write into a skill directory, waits for the user's answer in the permission prompt. A third-party skill is persistent instructions loaded into later sessions, and the skills CLI installs one without asking when an agent runs it: it detects Claude Code and goes non-interactive, -g links the skill into every detected agent's directory, and a blocked write still printed "Done!" with exit 0 (benchmarks §10).

Known limits:

  • The same as the deny-guards: it matches command text. A path built at run time (a variable, a glob, $(…)), a script file, an interpreter (python -c, node -e, or a here-doc fed to one), jq rewriting settings.json, or a download tool it does not know is not caught, and it fails open on a parse error.
  • Text is data, as it is to the shell. A here-doc body, a comment or a quoted string that mentions skills add (a PR body, a commit message, a document) is not asked about. A here-doc fed to a shell is asked about, and so are $(…) and backticks outside single quotes. The first version tokenized here-doc bodies as commands and asked before a gh pr create. That command is now a row in the decision table. An adversarial review found 20 shell forms it missed (line continuations, comments, loops, xargs, find -delete, cd then a relative path, cp -r skills ~/.claude/, and others) plus settings edits and letter case; all are now covered and in the decision table (benchmarks §10), which says how many forms were tried, not that none remain.
  • An approved prompt is an approval. The guard records nothing and cannot tell a considered yes from a reflexive one.
  • skills use installs nothing, but what it prints is still third-party instructions in context. The policy in CLAUDE.md asks for official sources and a read before following; nothing enforces that.

Secrets handling

  • Credentials never enter prompts, logs, indexes, or delegated packets.
  • Terraform state, state pull and show output contain secrets and must never be pasted into context, a review packet, or a subagent prompt (rules/infrastructure.md).
  • The graph bootstrap strips LLM API keys from the environment before invoking the graph tool, so a build cannot make a paid API call even if the tool would otherwise try.
  • Review packets are explicitly required to have secrets stripped from diffs, logs and config before dispatch (skills/adversarial-jury/packet-template.md).
  • The security judge is told never to retrieve a secret value as proof, and never to write a working exploit.

Tool output is data, not instructions

Repository text, web pages, package metadata and tool output are treated as evidence, never as instructions. Every judge agent is told this explicitly in its own prompt, because a judge reads attacker-influenceable content (diffs, logs) with an instruction-shaped mind.

The Ponytail flag leak

The one known defect in the upstream stack, reproduced directly.

What it is. The plugin's active mode lives in a single file under the Claude config directory. It is machine-global and shared by every concurrent session. Typing /ponytail-review writes review into it, and while set, the plugin's subagent hook injects the "delete code" persona into subagents — including reviewers whose purpose is the opposite lens, in that session and any other session running at the same time.

Why it matters. A simplification persona reaching a security or correctness reviewer inverts what that reviewer is for. Because the file is shared, a review started in one terminal can quietly alter a judge in another. Nothing fails loudly; the effect is a bias.

Three independent containment layers. Do not remove one assuming another covers it:

  1. PONYTAIL_SUBAGENT_MATCHER in settings — a never-matching sentinel (^ponytail-subagents-disabled$) that stops the ruleset reaching any subagent regardless of flag state. ⚠️ An invalid regex fails open and injects, so any replacement must be a valid regex that matches nothing.
  2. hooks/ponytail-guard.sh wired to Stop and SessionEnd, so an interrupted or failed review still cleans up. clear removes only a review flag and leaves a deliberately-set lite/full/ultra alone; force clears unconditionally.
  3. The plugin's own SessionStart hook, which clears the flag when the configured default is off.

The general lesson — prefer stateless mechanisms; where state is unavoidable, assume it leaks and contain it in layers — is why the dead-code audit was designed with no state at all.

Trust boundaries of the setup itself

  • Hooks execute arbitrary local code on every matching tool call. Read every hook in hooks/ before installing it. That is not a formality: a hook is the highest-privilege extension point here.
  • Plugins and marketplaces are third-party code that loads into every session. config/settings.example.json names six plugins from three marketplaces. Evaluate them yourself; being listed here is not an audit.
  • Remote MCP servers receive your queries. The screen-reference servers (Refero, Mobbin) and 21st.dev's component-research server are at user scope. Every query leaves the machine. With 21st.dev at user scope, substantial frontend work in any repository sends product and section descriptions to it unasked, because frontend-quality makes that research a step; disable the server for a project that must not send them. A keyed server's key sits in plain text in ~/.claude.json. permissions.deny in settings.json blocks 21st.dev's generation, publishing and account-write tools, including record_inspiration_feedback, which would send accept and reject signals under the key. It matches by server and tool name, so a server connected under another name, or a renamed tool, is not blocked.
  • Skills and agents are instructions, not code. They cannot execute anything on their own, but they do shape what the model does with tools it already has.
  • The installer writes only under $HOME/.claude (or $CLAUDE_CONFIG_DIR) and backs up anything it would overwrite.

Part 3 — Failure modes and risks

Component Fails how Consequence Mitigation
Deny-hooks Fail open on unparseable input A destructive command could pass Narrow patterns, fast-path guard, denial names itself
Deny-hooks False positive on an innocent command Legitimate work blocked shlex parsing; -n in a quoted message is not a flag; removal instructions in the message
Local-CI gate Misses a push in a script, or fails open Unvalidated work reaches remote CI Opt-in pre-push hook covers every agent git push; CLAUDE.md policy
Local-CI gate Stale or forged evidence A push passes without a real check Evidence keyed by content, so stale never matches; forging needs a deliberate write to the cache
local-ci act Misclassifies a deploy job as runnable A workflow step runs locally with no secrets and no Docker socket Name, step, environment and permission checks; --list first
local-ci act Environment failure looks like a test failure, or the reverse Wrong signal Unsupported only when no step failed; the log path is printed
local-ci auto Treats a job as covered by a local check when it is not A workflow-only behaviour is not run locally Equivalence only for a plain job whose every command is a required local command line; remote CI still runs it
Stop hook (local-ci-auto) Holds a stop the user did not want validated, or content changes on every run Extra turns At most once per content state and three times in a row per user turn; never for a turn that changed nothing; LOCAL_CI_AUTO=0
Skill-install guard Fails open, or misses an indirect write A skill is installed without a prompt The CLAUDE.md policy; the guard covers the CLI, the file tools and common shell writes
Skill-install guard Asks on a hand edit of an installed skill One extra prompt Intended: that is a persistent change too. Reads and skills find/use never ask
Advisory hooks Fail open, silently A hint is missed Nothing depends on the hint
Advisory hooks Fire too often Nagging, wasted tokens Once per session per class; state reset on compact/clear
read-budget-advisor State shared across agents Wrong "you already read this" hints Keyed by session and agent id
run-captured Capture file not writable Command runs uncaptured Explicit fail-open path, message on stderr
run-captured Summariser throws Result could be hidden Falls back to a raw tail plus exit code
run-captured One enormous single line Summarised in memory Documented limit
run-captured Used on a server or a prompt Hangs Documented: not for interactive or long-running commands
Graph bootstrap Build fails or times out No graph Fails open, deletes the partial output it created, caches the failure for 24 h
Graph bootstrap Recursion Infinite loop Env guard, command-name check, per-repo lock file
Graph bootstrap Repo too large Long stall Hard budget, skip above a file-count ceiling
Ponytail flag Leaks to subagents / other sessions Wrong persona in a reviewer Three containment layers (above)
Semantic triggers Model does not notice them Review silently skipped The reporting requirement — a missing report is visible
Reporting requirement Model claims a review it did not run Undetectable from the transcript alone Unmitigated. Findings must cite file and line, which makes fabrication checkable, but nothing enforces it
Judges All agree and are all wrong False confidence Evidence ladder; jury-arbiter never counts votes; "a clean jury is not proof" is written into the skill
Judges Hallucinate a finding Wasted fix effort Every finding needs a failure scenario and a location; unsupported claims are rejected
Path-scoped rules Glob does not match a project's layout Rule never loads Check the paths: frontmatter against your tree
Installer Overwrites a customised file Local changes lost Dry-run default, backup before every overwrite, refuses to merge settings

The largest residual risk

The semantic triggers and the reporting requirement are not enforced by anything. A model that does not evaluate the triggers, or that reports a review it did not perform, produces a transcript indistinguishable from a correct one apart from the content of the findings themselves.

This is accepted deliberately — see why-this-setup.md for why a hook cannot do this job — but it is a real limitation, not a solved problem. The partial mitigation is that findings must carry file and line, and rejections must carry reasons, both of which a human can check against the diff.

There aren't any published security advisories