Skip to content

Hardening Guide — V025-claude-toolkit

Step-by-step checklist for securing a new toolkit deployment. Follow these steps after initial setup to minimize the attack surface.

Prerequisites

  • macOS with Claude Code CLI installed
  • Node.js (v20+) and npm
  • Git with SSH key configured
  • Access to the V025-claude-toolkit repository

Step 1: Run Full Setup

cd ~/01-repositories/V025-claude-toolkit
./scripts/setup.sh --safe

This installs: - Plugin symlinks for all registered plugins - Skill, hook, agent, and command symlinks - CLAUDE.md, settings.json, and settings.local.json

Step 2: Verify MCP Package Integrity

./scripts/setup.sh --verify

Check the output for: - github — no npm package to verify; any future npm-distributed server must report "integrity verified" - No "INTEGRITY MISMATCH" errors - All hook symlinks valid

If any integrity check fails, do NOT proceed. See incident-response.md Section 1 (Compromised npm Package).

Step 3: Configure GitHub Branch Protection

For each repository using the toolkit, configure these GitHub branch protection rules:

Setting Value Reason
Require pull request before merging Enabled Prevents direct pushes to main
Require approvals 1+ Human review before merge
Require status checks to pass Enabled CI must pass
Require branches to be up to date Enabled Prevents merge of stale branches
Include administrators Enabled No exceptions for admins

To check via CLI (when gh is available): 

gh api repos/{owner}/{repo}/branches/main/protection

Step 3b: Apply the Security Baseline (SPEC-114)

The toolkit ships a security baseline at configs/security/baseline-settings.json. After SPEC-114, the baseline contains 11 categories and ~128 deny rules:

  1. Network exfiltration — curl/wget/nc/WebFetch
  2. Credential file access — SSH keys, cloud creds, .env variants (.env.local, .env.*.local, .env.production, .env.staging, .env.development, .env.test), secrets/, credentials.*, plus Grep/Glob/Edit/Write mirrors
  3. Destructive commands — rm -rf, sudo, mkfs, dd, chmod 777
  4. Shell config modification — ~/.bashrc, ~/.zshrc, etc.
  5. Untrusted package execution — npx -y, npm publish, .npmrc / .pypirc tampering
  6. Git safety — force push, reset --hard, clean -f
  7. Code execution — python -c, node -e, perl -e, ruby -e (inline interpreter code)
  8. Database destructive — DROP DATABASE, ORM destructive ops (constructive ops like rails db:migrate remain allowed per EC-05)
  9. Infrastructure — terraform destroy, kubectl delete namespace, docker rm -f
  10. Self-modification protection — global ~/.claude/settings.json, ~/.claude/CLAUDE.md, .git/**, mcp.json
  11. Agent governance — --dangerously-skip-permissions, crontab, audit-log removal

See SECURITY-CONFIG.md for full threat model, impact, and override guidance per category.

Apply the baseline by running: 

/vt-c-repo-health --update-baseline     # seeds config-snapshot.yaml
/vt-d-security-scan                     # verifies 11/11 coverage

Step 4: Set Enterprise Claude Code Settings

Configure these settings in the appropriate file for your deployment:

File Scope When to Use
~/.claude/settings.json User-level Personal machine, all projects
.claude/settings.json Project-level Specific repository
Managed settings (enterprise) Organization Centrally deployed via MDM

Add these entries to the chosen settings file:

{
  "permissions": {
    "allowManagedHooksOnly": true
  },
  "env": {
    "enableAllProjectMcpServers": false
  }
}
Setting Purpose
allowManagedHooksOnly: true Only hooks from managed configurations can execute
enableAllProjectMcpServers: false Project-level MCP servers require explicit approval

Step 5: MCP Server Whitelisting

Review configured MCP servers: 

claude mcp list

Governed servers (managed by setup.sh): - github — GitHub Copilot MCP (HTTP, OAuth)

Plugin-provided servers (managed by compound-engineering plugin): - plugin:compound-engineering:pw — Playwright browser automation - plugin:compound-engineering:context7 — Documentation lookup

A server you deliberately keep outside these lists, such as a local-scope azure-devops entry (see MCP Server Reference), is your own exception and your own supply-chain risk: the toolkit neither pins nor hash-checks it, and no toolkit hook vets npx, which fetches the package and its dependencies from npm and runs their install scripts when they are not cached. Review the package before adding it, and give it a token with the narrowest scopes you need.

Remove any other server not in these lists: 

claude mcp remove <unexpected-server-name>

Step 6: Verify Secret Scanning

Run a repository audit to verify hook integrity: 

# Quick check
/vt-c-repo-health

# Full audit
/vt-c-repo-audit

Verify these hooks are active: - secret-scanner (PreToolUse) — blocks writes containing credential patterns - security-lint (PostToolUse) — scans file modifications

Check trusted hook checksums: 

cat configs/security/trusted-hooks.yaml

Step 7: Set Up Ongoing Maintenance

Frequency Action Command
Every session Capture decisions /vt-c-journal
Weekly Quick health check /vt-c-repo-health
Monthly Full integrity audit /vt-c-repo-audit
Monthly Dependency audit npm audit --audit-level=high
After MCP update Verify package integrity setup.sh --verify
After hook change Re-verify checksums /vt-c-repo-audit

Step 8: Verify npm Security Defaults

For all new projects scaffolded with /vt-d-bootstrap:

  1. Dependencies are installed with npm ci --ignore-scripts
  2. Post-install audit runs npm audit --audit-level=high
  3. Only explicitly trusted packages run post-install scripts via npm rebuild <package>

Verify the convention is documented: 

grep "ignore-scripts" plugins/vt-product-dev/skills/npm-security/SKILL.md

Verification Checklist

After completing all steps, verify your deployment:

[ ] setup.sh --safe completed without errors
[ ] setup.sh --verify reports all checks passed
[ ] setup.sh --verify prints "github — no npm package to verify" and no "INTEGRITY MISMATCH"
[ ] GitHub branch protection configured (if using GitHub)
[ ] allowManagedHooksOnly set to true
[ ] enableAllProjectMcpServers set to false
[ ] No unexpected MCP servers in claude mcp list
[ ] Secret scanner hook active
[ ] Security lint hook active
[ ] /vt-c-repo-health passes
[ ] Weekly/monthly audit schedule planned