Command Whitelist

​

What’s in the Box

• Hooks (hooks/hooks.json) - PreToolUse hook that validates commands against a whitelist
• Skill (skills/strict-mode/SKILL.md) - Documentation about what’s allowed
• Plugin manifest (.claude-plugin/plugin.json) - Standard Claude Code plugin format

​

How It Works

​

Whitelisted Commands

​

Run It

• Option 1: Load via API
• Option 2: Launch via Badge

Use the companion load-plugin example:

cd ../load-plugin

# This will be blocked (pip not whitelisted)
python load_plugin.py \
  --repo-path command-whitelist/strict-mode \
  --message "Install the requests package"

# This will be allowed (ls is whitelisted)
python load_plugin.py \
  --repo-path command-whitelist/strict-mode \
  --message "List all Python files in the current directory"

Click to test strict mode:

​

The Hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "terminal",
        "hooks": [
          {
            "type": "command",
            "command": "input=$(cat)\n# ... POSIX-sh whitelist check ...\nexit 0",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

1. PreToolUse - Runs before the terminal tool executes
2. matcher: "terminal" - Only applies to shell commands
3. Inline POSIX-sh script (run via /bin/sh -c; kept inline rather than a bash -c '...' wrapper or an external .sh file — see the note in the command-blacklist README for why):
   • Extracts the command name from the JSON input
   • Checks if it’s in the hardcoded whitelist
   • Returns exit 0 (allow) or exit 2 (block, with a {"decision":"deny",...} reason)

allowed="ls cat grep find head tail wc echo pwd whoami date uname df du tree file which env printenv history stat"

​

Whitelist vs. Blacklist

​

When to Use Each Approach

​

Use Whitelist (Strict Mode) When:

• 🎓 Educational - Teaching safe command usage
• 🔍 Analysis only - Reading/inspecting systems
• 🛡️ Maximum security - Untrusted users or agents
• 📊 Auditing - Examining existing systems
• 🧪 Sandboxes - Limiting experimental environments

​

Use Blacklist (Safety Guardian) When:

• 🚀 Development - Need full tooling access
• 🔧 General protection - Block obvious dangers
• ⚡ Productivity - Don’t want to pre-approve everything
• 🏗️ Building - Need to install, compile, deploy
• 🎯 Specific risks - Known dangerous patterns to block

​

Extending the Whitelist

allowed="ls cat grep find ... git python npm"

​

Security Considerations

• Completely locks down command execution
• Easy to audit (small whitelist)
• Can’t be bypassed by clever command variations
• Works well for truly untrusted agents

• Very restrictive (might frustrate users)
• Requires updating the list as needs evolve
• Doesn’t prevent reading sensitive files (allows cat /etc/passwd)
• Simple command extraction (not full shell parsing)

1. Combining with file path restrictions
2. Adding argument validation (not just command name)
3. Logging all blocked attempts
4. Using a proper JSON parser instead of grep

​

Plugin Structure

strict-mode/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── hooks/
│   └── hooks.json           # PreToolUse hook definition
└── skills/
    └── strict-mode/
        └── SKILL.md         # Documentation (auto-loaded)

• OpenHands Cloud plugin launcher
• Claude Desktop plugin marketplace
• Any system supporting the .claude-plugin spec

​

Real-World Use Cases

• Code review agents - Only allow read operations on source code
• Security auditing - Inspect systems without modification
• Student environments - Safe learning sandbox
• Public demos - Allow exploration without damage
• CI/CD read-only steps - Verify without changing artifacts

​

Progressive Enhancement

1. Day 1: Only allow ls, cat, grep (ultra-strict)
2. Week 1: Add find, wc, head, tail (more inspection tools)
3. Month 1: Add git for version control (read-only)
4. As needed: Carefully evaluate and add new commands

​

Related