Разрешения и контроль безопасности навыков
Skills могут получать доступ к файловой системе, вызывать внешние API и выполнять скрипты. При злоупотреблении эти возможности могут создавать риски безопасности.
В этой статье объясняется, как установить границы безопасности на этапе проектирования, чтобы Skill не выполнял операции за пределами ожидаемого.
Область разрешений навыков по умолчанию
В среде выполнения Claude разрешения навыков определяются песочницей и не являются неограниченными.
| Тип операции | Статус разрешений | Описание |
|---|---|---|
| Чтение загруженных файлов | Разрешено | Ограничено /mnt/user-data/uploads/ |
| Запись выходных файлов | Разрешено | Ограничено /mnt/user-data/outputs/ и /home/claude/ |
| Чтение системных файлов | Restricted | Монтирование только для чтения, нельзя изменять системные файлы |
| Доступ к внешней сети | Restricted | Разрешены только домены из белого списка |
| Выполнение произвольных системных команд | Restricted | Нельзя использовать sudo, нельзя изменять системную конфигурацию |
| Доступ к данным других пользователей | Запрещено | Гарантируется изоляцией песочницы |
Навыки — это практическая реализация принципа «наименьших привилегий» при проектировании: навык может получать доступ только к тем ресурсам, которые ему явно необходимы. Если навыку требуются разрешения за пределами указанной области, следует пересмотреть подход к проектированию.
Чётко определите границы разрешений в SKILL.md
Чётко указывайте в документации навыка, к каким ресурсам он будет обращаться, чтобы пользователи могли понять сферу поведения навыка перед его использованием.
## 权限说明 本 Skill 会进行以下操作,请确认你已了解: **文件访问** - 读取:/mnt/user-data/uploads/ 下用户上传的文件 - 写入:/mnt/user-data/outputs/ 下的输出文件 **网络访问** - 无(本 Skill 不访问任何外部网络) **不会进行的操作** - 不读取系统文件 - 不修改已上传的原始文件 - 不访问任何外部服务
Предотвращение атак обхода пути
Когда скрипт принимает указанный пользователем путь к файлу, он должен проверить, находится ли этот путь в разрешённой области, не позволяя пользователям../получать доступ к каталогам, к которым у них не должно быть доступа.
Пример
import os
# Каталоги, разрешённые для чтения
ALLOWED_READ_DIRS = [
"/mnt/user-data/uploads",
"/mnt/skills/public",
]
# Каталоги, разрешённые для записи
ALLOWED_WRITE_DIRS = [
"/mnt/user-data/outputs",
"/home/claude",
]
def is_safe_path(path: str, allowed_dirs: list) -> bool:
"""
Проверить, находится ли путь в пределах разрешённой области каталогов
Предотвратить атаки обхода пути, подобные ../../../etc/passwd
"""
# Преобразовать в абсолютный путь (устранить .. и символические ссылки)
real_path = os.path.realpath(os.path.abspath(path))
for allowed in allowed_dirs:
real_allowed = os.path.realpath(allowed)
# Проверить, начинается ли real_path с разрешённого каталога
if real_path.startswith(real_allowed + os.sep) or real_path == real_allowed:
return True
return False
def safe_read_path(user_input: str) -> str:
"""Проверить путь чтения, вызвать исключение, если он недействителен"""
if not is_safe_path(user_input, ALLOWED_READ_DIRS):
raise PermissionError(
f"Доступ запрещён: {user_input}"\n"
f"Разрешены для чтения только следующие каталоги: {ALLOWED_READ_DIRS}"
)
return os.path.realpath(user_input)
def safe_write_path(user_input: str) -> str:
"""Проверьте путь записи, возбудите исключение, если он недействителен"""
if not is_safe_path(user_input, ALLOWED_WRITE_DIRS):
raise PermissionError(
f"Запись запрещена: {user_input}"\n"
f"Запись разрешена только в следующие каталоги: {ALLOWED_WRITE_DIRS}"
)
return os.path.realpath(user_input)
# Пример использования
if __name__ == "__main__":
# Обычный путь: проходит
ok_path = safe_read_path("/mnt/user-data/uploads/example.csv")
print(f"Пройдено: {ok_path}")
# Путь обхода: отклонён
try:
bad_path = safe_read_path("/mnt/user-data/uploads/../../etc/passwd")
except PermissionError as e:
print(f"Заблокировано: {e}")
通过:/mnt/user-data/uploads/example.csv 已拦截:拒绝访问:/mnt/user-data/uploads/../../etc/passwd 只允许读取以下目录:['/mnt/user-data/uploads', '/mnt/skills/public']
Безопасное хранение API-ключей
Разные методы управления ключами значительно различаются по уровню безопасности.
| Метод | Безопасность | Уровень рекомендации |
|---|---|---|
| Жёстко закодированы в скриптах | Крайне низкий, будет закоммичен в Git | Запрещено |
| Переменные среды | Средний, изоляция процессов | Рекомендуется (этап разработки) |
| Файл .env (добавлен в .gitignore) | Средний, локальное файловое хранилище | Рекомендуется (локальное использование) |
| Системный менеджер ключей (например, Vault) | Высокий, централизованное управление | Рекомендуется (продакшен-среда) |
Пример
# Безопасно считывать конфигурацию из нескольких источников, выполняя поиск в порядке убывания приоритета
import os
def get_secret(key: str, required: bool = True) -> str:
"""
Считывать ключи из следующих источников в порядке приоритета:
1. Переменные среды (наивысший приоритет)
2. Файл /home/claude/.skill_secrets (локальный файл ключей)
3. Если required=True и значение не найдено, вызвать исключение
"""
# 1. Переменные среды
value = os.environ.get(key)
if value:
return value
# 2. Локальный файл ключей (формат каждой строки: KEY=VALUE)
secrets_file = "/home/claude/.skill_secrets"
if os.path.exists(secrets_file):
with open(secrets_file) as f:
for line in f:
line = line.strip()
if line.startswith(f"{key}="):
return line[len(key)+1:]
# 3. Не найдено
if required:
raise EnvironmentError(
f"Отсутствует обязательный ключ: {key}\n"
f"Пожалуйста, установите переменную окружения: export {key}='your key'"
)
return ""
Безопасная фильтрация входного содержимого
Когда Skill передаёт пользовательский ввод в команды Shell, ввод должен быть экранирован, чтобы предотвратить инъекцию команд.
Пример
import subprocess
import shlex
def safe_shell_exec(template: str, user_input: str) -> str:
"""
Безопасно встраивайте пользовательский ввод в команды Shell
Неправильный подход: os.system(f"process {user_input}") # Риск инъекции команд!
Правильный подход: используйте список аргументов, позвольте subprocess выполнить экранирование
"""
# Используйте список вместо строки; subprocess автоматически обработает экранирование
cmd = ["python", "scripts/process.py", user_input]
result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
return result.stdout
# Если вам нужно собрать строковую команду, используйте shlex.quote для экранирования пользовательского ввода
def safe_string_exec(user_filename: str) -> str:
safe_name = shlex.quote(user_filename) # Автоматически добавляет кавычки и экранирует специальные символы
cmd = f"wc -l {safe_name}"
result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
return result.stdout
Другие расширенияНикогда не используйте
os.system(f"cmd {user_input}")этот способ выполнения команд. Если пользовательский ввод содержит; rm -rf /или похожее содержимое, это приведёт к катастрофическим последствиям. Всегда используйте форму списка аргументов subprocess.