Skip to content

Claude Code Security — Developer Guide

This is a developer guide for working safely with Claude Code in this toolkit. It does not define organizational policy — for that see SPEC-143 (KI-Richtlinie) when it ships. It also does not cover Anthropic Teams-account management (SPEC-144, parked). What this guide does cover: the permission modes you'll meet day-to-day, the hooks the toolkit installs on your behalf, the templates you can copy, the dangerous-flag rules, and what to do when something feels off.

Everything below is an index into mechanisms implemented by SPEC-114 (Security Baseline Hardening). Each subsection ends in a link to the file that does the actual work — drift between this page and the implementation is therefore visible, not hidden.

1. Permission Modes

Claude Code runs every tool call through one of three permission modes; the toolkit's baseline deny rules live at configs/security/baseline-settings.json and apply across all three. Per-category threat model: configs/security/SECURITY-CONFIG.md.

auto — the recommended default. An AI classifier approves safe actions (file edits, test runs) and blocks dangerous ones (rm -rf, credential reads). See: Claude Code Auto-mode docs.

normal — every tool call you haven't pre-allowed prompts you. Use this for unfamiliar codebases or when you want a complete audit trail of approvals.

bypassPermissions — interactive override that approves all tools for the session. Different from the --dangerously-skip-permissions flag (see Section 4); use only in disposable environments.

2. Toolkit Hooks (Inventory)

The toolkit ships four hooks that run as part of your day-to-day workflow. Each runs at a specific Claude Code or git lifecycle point and is wired up by setup.sh. To see what a hook does internally, follow its link.

Hook Lifecycle point Purpose
secret-scanner.sh PreToolUse + pre-commit Blocks tool calls and commits that would write credential patterns to disk
security-lint.sh PostToolUse Flags risky patterns after a file edit lands (informational, non-blocking)
pre-commit git pre-commit Composes secret-scanner with branch-protection (no direct commits to main)
claudeignore-guard.sh PreToolUse Enforces .claudeignore for Read/Grep/Glob so the agent cannot see hidden files

Hooks are deployed by setup.sh and pinned via SHA-256 in configs/security/trusted-hooks.yaml. Drift detection: setup.sh --verify.

3. Example Settings

Two templates ship with the toolkit. Pick the one that matches your workflow and let setup.sh deploy it — see installation.md for the first-time deploy and verify-setup.md for the post-install integrity check.

The choice persists in ~/.claude/settings.local.json (vt_profile key) and is re-applied automatically on setup.sh --update. To switch back to the conservative default, run setup.sh --profile=regular. Project-local additions belong in .claudeignore (template) and .gitignore (template).

4. The --dangerously-skip-permissions Flag

Warning. claude --dangerously-skip-permissions disables every permission check for the entire session — no deny rules, no classifier, no prompts. If something goes wrong, the agent can read secrets, write outside the project, or call destructive commands without you noticing. Do not use this on your main workstation. Full policy: CLAUDE.md Rule 10b.

Acceptable scenarios (where the lowered gate is reasonable):

  1. Disposable VM — a throwaway sandbox you'll destroy after the demo, with no access to credentials or shared infrastructure.
  2. CI sandbox without secrets — an ephemeral CI runner running on test fixtures only, where no .env, no production tokens, and no SSH keys are mounted.
  3. Throwaway demo container — a Docker container brought up for a single recorded demo, then thrown away.

Note: the CLI flag is different from the interactive bypassPermissions mode (Section 1). Both lower the gate, but bypassPermissions is per-session and reversible; the CLI flag affects the whole process.

5. What to Do When Something Seems Off

If Claude does something unexpected, work through this 5-step playbook in order — and run /vt-c-security-scan for the canonical 11-category audit at step 3. Don't ad-lib; small detours hide evidence.

  1. Pause. Cancel the running tool call (Ctrl-C if streaming) or close the session. Do not approve further actions.
  2. Snapshot. Run git status and git diff to see what changed on disk. Save the session transcript if your interface supports it. Don't git add or git commit yet.
  3. Investigate. Run /vt-c-security-scan for the 11-category audit, then read the changed files and check the diff against your intent.
  4. Escalate. If the change touches secrets, deletes data, or hits an external service in a way you didn't authorize, tell your team lead now. Don't try to "fix it" alone.
  5. Report. Capture what you saw in an issue or incident note, including the prompt that triggered the behaviour. Future-you (and future-toolkit) will use this.

Longer-form security docs: docs/security/hardening-guide.md.

6. SPEC-114 Cross-Reference Index

For auditors and advanced users who want to read the security baseline directly, these are the Tier 2 deliverables of SPEC-114:

For the human-readable per-category threat model see configs/security/SECURITY-CONFIG.md. For the version-1.1.0 baseline see configs/security/baseline-settings.json.