Permisos y control de seguridad de Skills

Skills pueden acceder al sistema de archivos, llamar a APIs externas y ejecutar scripts; si se abusa de estas capacidades, pueden conllevar riesgos de seguridad.

Este artículo explica cómo establecer límites de seguridad en la fase de diseño para evitar que un Skill realice operaciones más allá de lo esperado.


Alcance de permisos predeterminado de Skills

En el entorno de ejecución de Claude, los permisos de Skills están determinados por el entorno de sandbox, no son ilimitados.

Tipo de operaciónEstado del permisoDescripción
Leer archivos subidosPermitidoSolo en /mnt/user-data/uploads/
Escribir archivos de salidaPermitidoSolo en /mnt/user-data/outputs/ y /home/claude/
Leer archivos del sistemaRestringidoMontaje de solo lectura, no se pueden modificar archivos del sistema
Acceso a redes externasRestringidoSolo se permite acceder a dominios de la lista blanca
Ejecutar comandos arbitrarios del sistemaRestringidoNo se puede usar sudo, no se puede modificar la configuración del sistema
Acceder a datos de otros usuariosProhibidoGarantía de aislamiento del sandbox

Skills son, por diseño, una práctica del principio de "privilegio mínimo": un Skill solo puede acceder a los recursos que necesita explícitamente. Si un Skill necesita permisos más allá del alcance anterior, se debe reconsiderar el diseño.


Definir claramente los límites de permisos en SKILL.md

Declarar claramente en el documento del Skill qué recursos accederá, para que los usuarios conozcan el alcance del comportamiento del Skill antes de usarlo.

## 权限说明

本 Skill 会进行以下操作,请确认你已了解:

**文件访问**
- 读取:/mnt/user-data/uploads/ 下用户上传的文件
- 写入:/mnt/user-data/outputs/ 下的输出文件

**网络访问**
- 无(本 Skill 不访问任何外部网络)

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

Prevenir ataques de path traversal

Cuando el script acepta rutas de archivo proporcionadas por el usuario, es necesario verificar si la ruta está dentro del rango permitido, para evitar que el usuario, mediante../acceda a directorios a los que no debería tener acceso.

Ejemplo

# Ruta del archivo: scripts/safe_path.py
import os

# Directorios permitidos para lectura
ALLOWED_READ_DIRS = [
    "/mnt/user-data/uploads",
    "/mnt/skills/public",
]

# Directorios permitidos para escritura
ALLOWED_WRITE_DIRS = [
    "/mnt/user-data/outputs",
    "/home/claude",
]

def is_safe_path(path: str, allowed_dirs: list) -> bool:
    """
Verificar si la ruta está dentro de los directorios permitidos

Prevenir ataques de path traversal del tipo ../../../etc/passwd
    """

    # Resolver a ruta absoluta (eliminar .. y enlaces simbólicos)
    real_path = os.path.realpath(os.path.abspath(path))

    for allowed in allowed_dirs:
        real_allowed = os.path.realpath(allowed)
        # Verificar si real_path comienza con el directorio allowed
        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:
    """Verificar la ruta de lectura, lanzar una excepción si no es válida"""
    if not is_safe_path(user_input, ALLOWED_READ_DIRS):
        raise PermissionError(
            f"Acceso denegado: {user_input}\n"
            f"Solo se permite leer los siguientes directorios: {ALLOWED_READ_DIRS}"
        )
    return os.path.realpath(user_input)

def safe_write_path(user_input: str) -> str:
    """Verificar la ruta de escritura, lanzar una excepción si no es válida"""
    if not is_safe_path(user_input, ALLOWED_WRITE_DIRS):
        raise PermissionError(
            f"Escritura denegada: {user_input}\n"
            f"Solo se permite escribir en los siguientes directorios: {ALLOWED_WRITE_DIRS}"
        )
    return os.path.realpath(user_input)

# Ejemplo de uso
if __name__ == "__main__":
    # Ruta normal: válida
    ok_path = safe_read_path("/mnt/user-data/uploads/ejemplo.csv")
    print(f"Válido: {ok_path}")

    # Ruta de traversal: rechazada
    try:
        bad_path = safe_read_path("/mnt/user-data/uploads/../../etc/passwd")
    except PermissionError as e:
        print(f"Bloqueado: {e}")
通过:/mnt/user-data/uploads/ejemplo.csv
已拦截:拒绝访问:/mnt/user-data/uploads/../../etc/passwd
只允许读取以下目录:['/mnt/user-data/uploads', '/mnt/skills/public']

Almacenamiento seguro de claves API

Los diferentes métodos de gestión de claves tienen diferencias significativas en el nivel de seguridad.

MétodoSeguridadRecomendación
Hardcodeado en el scriptExtremadamente bajo, se enviará a GitProhibido
Variables de entornoMedio, aislamiento de procesosRecomendado (etapa de desarrollo)
Archivo .env (añadido a .gitignore)Medio, almacenamiento local de archivosRecomendado (uso local)
Gestor de claves del sistema (como Vault)Alto, gestión centralizadaRecomendado (entorno de producción)

Ejemplo

# Ruta del archivo: scripts/config.py
# Leer la configuración de forma segura desde múltiples fuentes, buscando en orden descendente de prioridad

import os

def get_secret(key: str, required: bool = True) -> str:
    """
Leer las claves de las siguientes fuentes según su prioridad:
1. Variables de entorno (máxima prioridad)
2. Archivo /home/claude/.skill_secrets (archivo de claves local)
3. Si required=True y no se encuentra, lanzar una excepción
    """

    # 1. Variables de entorno
    value = os.environ.get(key)
    if value:
        return value

    # 2. Archivo de claves local (formato de cada línea: 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. No encontrado
    if required:
        raise EnvironmentError(
            f"Falta la clave requerida: {key}\n"
            f"Por favor, configura la variable de entorno: export {key}='tu clave'"
        )
    return ""

Filtrado seguro del contenido de entrada

Cuando un Skill pasa la entrada del usuario a comandos de Shell, las entradas deben escaparse para prevenir la inyección de comandos.

Ejemplo

# Ruta del archivo: scripts/safe_exec.py
import subprocess
import shlex

def safe_shell_exec(template: str, user_input: str) -> str:
    """
Incrustar de forma segura la entrada del usuario en comandos de Shell

Método incorrecto: os.system(f"process {user_input}") # ¡Riesgo de inyección de comandos!
Método correcto: usar lista de argumentos, dejar que subprocess maneje el escape
    """

    # Usar lista en lugar de cadena, subprocess manejará el escape automáticamente
    cmd = ["python", "scripts/process.py", user_input]
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
    return result.stdout

# Si es necesario construir el comando como cadena, usar shlex.quote para escapar la entrada del usuario
def safe_string_exec(user_filename: str) -> str:
    safe_name = shlex.quote(user_filename)   # Añade comillas automáticamente y escapa caracteres especiales
    cmd = f"wc -l {safe_name}"
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    return result.stdout

Nunca useos.system(f"cmd {user_input}")esta manera de ejecutar comandos. Si la entrada del usuario contiene; rm -rf /contenido como ese, las consecuencias serán catastróficas. Utilice siempre la forma de lista de argumentos de subprocess.

Otras extensiones