Разрешения и контроль безопасности навыков

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 不访问任何外部网络)

**不会进行的操作**
- 不读取系统文件
- 不修改已上传的原始文件
- 不访问任何外部服务

Предотвращение атак обхода пути

Когда скрипт принимает указанный пользователем путь к файлу, он должен проверить, находится ли этот путь в разрешённой области, не позволяя пользователям../получать доступ к каталогам, к которым у них не должно быть доступа.

Пример

# Путь к файлу: scripts/safe_path.py
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)Высокий, централизованное управлениеРекомендуется (продакшен-среда)

Пример

# Путь к файлу: scripts/config.py
# Безопасно считывать конфигурацию из нескольких источников, выполняя поиск в порядке убывания приоритета

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, ввод должен быть экранирован, чтобы предотвратить инъекцию команд.

Пример

# Путь к файлу: scripts/safe_exec.py
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.

Другие расширения