[DOCS] Inconsistent Security Guidance Regarding Bash Permission Prefix Matching

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/iam - https://code.claude.com/docs/en/settings

Section/Topic

The "Tool-specific permission rules" section (Bash) and the "Permission rule syntax" section.

Current Documentation

• On the IAM page (https://code.claude.com/docs/en/iam): "Claude Code is aware of shell operators (like &&) so a prefix match rule like Bash(safe-cmd:*) won't give it permission to run safe-cmd && other-cmd."
• On the Settings page (https://code.claude.com/docs/en/settings): A warning block states: "Bash permission rules use pattern matching and can be bypassed... For example, Bash(curl:*) can be bypassed with curl -X GET reordered to curl http://example.com -X GET."

What's Wrong or Missing?

There is a significant discrepancy in the "tone" of security between these two pages. The documentation at https://code.claude.com/docs/en/iam frames prefix matching as a robust feature that is "aware" of shell operators, which might lead a developer to believe the system is highly resistant to command injection or bypasses.

However, the documentation at https://code.claude.com/docs/en/settings correctly identifies that simple pattern matching is easily bypassed by reordering flags (e.g., putting a flag before the URL in a curl command). If a user only reads the IAM documentation, they might implement "safe" rules that are actually trivial to circumvent.

Suggested Improvement

The security warnings should be synchronized and centralized. Both pages should feature a consistent "Security Limitations" block for the Bash tool.

Suggested Text:

Security Limitations of Bash Prefix Matching While Claude Code is aware of shell operators (like && or |) and will prevent them from being appended to an allowed prefix, simple pattern matching can still be bypassed. For example, a rule like Bash(curl http://api.example.com/*) can be bypassed if flags are reordered (e.g., curl -v http://api.example.com/...) or if shell variables are used. For sensitive operations, we recommend using PreToolUse hooks for robust validation or restricting network access at the OS/Container level.

Impact

High - Prevents users from using a feature

Additional Context

In many enterprise environments, developers rely on the Identity and Access Management (IAM) documentation to set up their internal "Golden Path" for agent permissions. If the primary IAM page minimizes the risks of prefix matching, it increases the likelihood of insecure configurations being deployed. Consistent warnings across https://code.claude.com/docs/en/iam and https://code.claude.com/docs/en/settings ensure that the shared responsibility model is clear regardless of which entry point a developer uses.