[DOCS] Inconsistent security guidance for Bash permission rules and network access

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/iam#tool-specific-permission-rules - https://code.claude.com/docs/en/settings#permission-settings

Section/Topic

The Tool-specific permission rules section in the IAM documentation and the Permission settings configuration table/examples in the Settings documentation.

Current Documentation

In Identity and Access Management, the documentation correctly warns about the fragility of Bash permissions:

"Patterns like Bash(curl http://github.com/:) can be bypassed in many ways... Options before URL... Redirects... Variables..."

However, in Settings, the example for the allow configuration uses simple prefix matching without immediately contextuaizing the security risk:

allow: Array of permission rules to allow tool use. Note: Bash rules use prefix matching, not regex. Example: [ "Bash(git diff:*)" ]

What's Wrong or Missing?

There is a disconnect between the security warning in the IAM section and the configuration examples in the Settings section.

While Bash(git diff:*) or Bash(npm run lint) are generally safe examples, presenting them as the primary method for allowing commands might lead users to believe that prefix matching is a secure boundary for all commands, including sensitive ones like curl or wget.

A user reading only the settings page might implement Bash(curl...) thinking they have secured their network access, unknowingly leaving themselves open to the bypasses mentioned in the iam section (e.g., using flags before the URL or using variables). The documentation needs to be much stronger in diverting users away from attempting to secure network calls via Bash rules.

Suggested Improvement

1. In docs/en/settings: Add a specific warning note next to the allow and deny examples for Bash tools.

• Suggested text: "⚠️ Security Warning: Bash permission rules rely on simple prefix matching and can often be bypassed using shell tricks (variables, flags, redirects). Do not rely on Bash rules for network security. Use WebFetch permissions for controlling network access."

1. In docs/en/iam: Strengthen the recommendation to use WebFetch instead of Bash for network operations.

• Suggested text: "Instead of attempting to secure curl or wget commands via Bash rules (which is fragile), strictly deny these commands and use the WebFetch tool with domain allowlists for secure network operations."

Impact

High - Prevents users from using a feature

Additional Context

The current documentation implies that prefix matching is a valid security control, whereas it is actually a convenience feature that is easily circumvented. For enterprise and security-conscious users, the documentation should explicitly funnel network operations toward the WebFetch tool, which offers actual domain enforcement, rather than leaving the door open for fragile Bash regex/prefix attempts.