[DOCS] Bash permission pattern limitations need stronger guidance

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/en/iam (Tool-specific permission rules > Bash section)

Section/Topic

Tool-specific permission rules > Bash > Warning block about permission pattern limitations

Current Documentation

The IAM documentation contains a Warning block (lines 133-151) that documents Bash permission pattern limitations:

<Warning>
  Important limitations of Bash permission patterns:

  1. The `:*` wildcard only works at the end of a pattern for prefix matching
  2. The `*` wildcard can appear at any position and matches any sequence of characters
  3. Patterns like `Bash(curl http://github.com/:*)` can be bypassed in many ways:
     * Options before URL: `curl -X GET http://github.com/...` won't match
     * Different protocol: `curl https://github.com/...` won't match
     * Redirects: `curl -L http://bit.ly/xyz` (redirects to github)
     * Variables: `URL=http://github.com && curl $URL` won't match
     * Extra spaces: `curl  http://github.com` won't match

  For more reliable URL filtering, consider:

  * **Restrict Bash network tools**: Use deny rules to block `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains
  * **Use PreToolUse hooks**: Implement a hook that validates URLs in Bash commands and blocks disallowed domains
  * Instructing Claude Code about your allowed curl patterns via CLAUDE.md
</Warning>

What's Wrong or Missing?

The documentation accurately describes the limitations of Bash permission patterns, but the presentation and guidance have several issues:

1. Warning placement: The limitations Warning appears AFTER the Bash pattern examples, meaning users see the pattern syntax (Bash(curl http://github.com/:*)) as valid-looking before learning it's fundamentally unreliable for URL-based restrictions.

1. Soft language: The recommendations use "consider" which is weak given these are security controls. For security-sensitive guidance, stronger language is warranted.

1. Missing explicit anti-recommendation: The documentation shows URL-based Bash patterns as examples without explicitly stating they should NOT be used for security purposes.

1. No secure example: While the docs explain what NOT to do, there's no complete example showing the recommended secure pattern (deny curl + allow WebFetch domain).

Impact: Administrators may create permission rules believing they provide security when the string-matching approach is inherently bypassable. The Warning exists but may be overlooked due to its placement after the pattern examples.

Suggested Improvement

Restructure the Bash section to lead with limitations and provide a complete secure example:

**Bash**

Bash permission rules support both prefix matching with `:*` and wildcard matching with `*`:

* `Bash(npm run build)` Matches the exact Bash command `npm run build`
* `Bash(npm run test:*)` Matches Bash commands starting with `npm run test`
* `Bash(npm *)` Matches any command starting with `npm ` (e.g., `npm install`, `npm run build`)
* `Bash(* install)` Matches any command ending with ` install` (e.g., `npm install`, `yarn install`)
* `Bash(git * main)` Matches commands like `git checkout main`, `git merge main`

<Warning>
  **Do not use Bash patterns for URL or network access control.** String-based pattern matching cannot reliably restrict network destinations because command arguments can be reordered, variables expanded, or redirects used.

  For example, `Bash(curl http://github.com/:*)` does NOT reliably restrict curl to GitHub:
  * `curl -X GET http://github.com/...` — options before URL won't match
  * `curl https://github.com/...` — different protocol won't match
  * `curl -L http://bit.ly/xyz` — redirects bypass the pattern
  * `URL=http://github.com && curl $URL` — variable expansion won't match
</Warning>

**Recommended pattern for network access control:**

```json
{
  "permissions": {
    "deny": ["Bash(curl:*)", "Bash(wget:*)", "Bash(nc:*)", "Bash(netcat:*)"],
    "allow": ["WebFetch(domain:github.com)", "WebFetch(domain:api.example.com)"]
  }
}

This approach:

1. Blocks network tools in Bash entirely
2. Uses WebFetch with domain-level restrictions for allowed sites

For more granular URL validation, use PreToolUse hooks to inspect Bash commands before execution.

<Tip>
Claude Code is aware of shell operators (like &&) so a prefix match rule like Bash(safe-cmd:*) won't give it permission to run the command safe-cmd && other-cmd
</Tip>

## Impact

**Medium** - Makes feature difficult to understand

While the current documentation does warn about limitations, the presentation order and soft language may lead administrators to create ineffective security rules. The fix improves clarity without changing any functionality.

### Impact

High - Prevents users from using a feature

### Additional Context


**Affected files:**
- `code-claude/docs/en/iam.md` (primary - lines 116-151)

**Related documentation with similar security limitation patterns:**
- `code-claude/docs/en/sandboxing.md` (line 176) - Documents domain fronting bypass risk
- `code-claude/docs/en/jetbrains.md` (line 140) - Documents IDE configuration bypass risk
- `code-claude/docs/en/security.md` (line 41) - Links to permission pattern limitations

**Cross-references that would need updating:**
- `code-claude/docs/en/settings.md` (line 173) - Links to "Bash permission limitations"
- `code-claude/docs/en/security.md` (line 41) - Links to "permission pattern limitations"

**Note on security documentation philosophy:**
The current documentation's transparency about limitations is good practice. The suggested improvement maintains this transparency while providing clearer guidance to help users implement effective security controls.

**Mirror location:** `code-claude/docs/en/iam.md`