[DOCS] Security vulnerability in Python SDK permission handler example (path traversal)

Documentation Type

other

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/python

Section/Topic

"Example - Advanced permission control" section

Current Documentation

if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
return PermissionResultDeny(...)

What's Wrong or Missing?

The example code demonstrates path validation using startswith("/system/") on a raw user-supplied path. This pattern is vulnerable to:

1. Directory traversal attacks: A path like ../../system/config won't match the check but could still target system files after path resolution
2. Non-normalized paths: Paths like /system/../system/config or /system/./config may bypass or inconsistently match the check
3. Symbolic link exploitation: The check doesn't verify if the path resolves through symlinks to protected areas

Developers copying this example for real security checks could inadvertently create exploitable permission handlers.

Suggested Improvement

Update the example to resolve and normalize paths before checking:

import os
# Normalize the path before checking
file_path = os.path.abspath(input_data.get("file_path", ""))
if tool_name == "Write" and file_path.startswith("/system/"):
return PermissionResultDeny(
message="Writing to /system/ is not allowed"
)

Or better, use os.path.realpath() to also resolve symlinks:

file_path = os.path.realpath(input_data.get("file_path", ""))

Impact

Medium - Makes feature difficult to understand

Additional Context

• This is a security-critical documentation issue as developers often copy permission handler patterns directly
• Consider adding a note about path normalization best practices in security-sensitive contexts