Permisos y seguridad

Módulo: 9. Funciones avanzadas | Tiempo: ~25 min de teoría + 20 min de práctica

Lo esencial

Un agente (un ejecutor autónomo) con las llaves de todas las puertas es una catástrofe en potencia. La seguridad en el desarrollo con IA no es burocracia, es arquitectura: unos límites bien puestos te protegen a ti, a tu cliente y tu reputación.

Términos de la lección: permission (permiso, el derecho a realizar una acción), API (interfaz para que los programas se comuniquen), agent (agente, un ejecutor autónomo), MCP (Model Context Protocol, el protocolo para conectar herramientas externas), bash (el lenguaje de comandos de la terminal), git (sistema de control de versiones), hook (un script que reacciona a un evento), sandbox (un entorno de prueba aislado), token (unidad de texto para la IA), settings.json (archivo de configuración del proyecto), workflow (flujo de trabajo).

Conceptos clave

.env es el único lugar para los secretos
Los modos de permisos (permissions) de Claude Code y cuándo usar cada uno
Cómo guardar secretos en producción (production, el entorno real del servicio)
Limitar el acceso de los subagentes como protección contra daños accidentales

Teoría

.env: la caja fuerte de los secretos

🎨 Imagínalo así: .env es la caja fuerte de la trastienda. El código es el aparador de la tienda. El dinero no se guarda en el aparador. Los secretos van en la caja fuerte, tras una puerta de acero.

El archivo .env es un almacén aislado para los datos sensibles: claves de API, tokens de acceso, contraseñas. Vive en la raíz del proyecto y nunca llega al repositorio (el almacén del código).

Ejemplo de estructura de .env:

Código

OPENAI_API_KEY=sk-proj-abc123...
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
TELEGRAM_BOT_TOKEN=7123456789:AAF...
STRIPE_SECRET_KEY=sk_live_...

En el código accedes a esos valores mediante variables de entorno:

python

import os
api_key = os.environ.get("OPENAI_API_KEY")

o en Node.js:

javascript

const apiKey = process.env.OPENAI_API_KEY;

Por qué NUNCA hay que escribir las claves directamente en el código:

GitHub y otras plataformas escanean activamente los repositorios públicos en busca de patrones como sk-ant-, sk-proj-, AIza, Bearer . Si una clave llegó a un commit, se considera comprometida. Los atacantes usan escáneres automáticos y pueden empezar a gastar tu dinero a los pocos minutos del push.

Aunque el repositorio sea privado, las fugas pasan: un cambio accidental de visibilidad, un colaborador nuevo, un fork. La regla es una: un secreto que llegó aunque sea una vez al historial de Git se considera público.

.gitignore: la primera línea de defensa

🎨 Imagínalo así: .gitignore es la lista de "esto no se empaca" en una mudanza. Las cajas se van en el camión (el repositorio público), pero la caja fuerte con los documentos no. Si se te olvida, la caja fuerte se va con todas las cajas y en el lugar nuevo todos verán lo que hay dentro.

Antes del primer git commit, agrega .env a .gitignore sin falta:

Código

# .gitignore
.env
.env.local
.env.*.local
*.pem
*.key
node_modules/

Verificación: corre git status antes de hacer commit. El archivo .env no debe aparecer en la lista de cambios. Si aparece, detente.

Los modos de permisos de Claude Code

🎨 Imagínalo así: los modos de permisos son como niveles de confianza con un contratista. Plan mode: solo mira y dibuja el plano. Manual: te consulta cada clavo. Accept edits: hace las modificaciones por su cuenta y para lo demás viene a preguntarte. Auto: trabaja solo y un supervisor aparte lo vigila. Bypass: tiene las llaves de todo el edificio, sótano incluido.

Claude Code ofrece un sistema flexible para controlar lo que el agente puede hacer. El modo que elijas depende de cuánto confías en la tarea. Los modos se cambian con la tecla Shift+Tab dentro de la sesión o con la opción --permission-mode al iniciar. A octubre de 2026 hay seis modos; la lista cambia, así que revisa la documentación y la página Lo vigente.

Plan mode (modo de plan, solo planear) El agente analiza la tarea y arma un plan, pero no realiza ninguna acción. Ideal para conocer un código nuevo o antes de una operación compleja: primero revisas el plan y después lo apruebas.

Código

claude --permission-mode plan "Agrega un sistema de autenticación"

Manual (en la configuración se llama default): preguntar antes de actuar Sin preguntar solo se permite leer. Las modificaciones de archivos, los comandos y el acceso a internet requieren confirmación. Úsalo cuando trabajes con código ajeno, con la configuración de producción o cuando la tarea sea poco común. Más lento, pero más seguro.

Accept edits (acceptEdits): modificaciones automáticas El agente modifica archivos por su cuenta y ejecuta comandos simples con archivos (crear una carpeta, mover, copiar); lo demás lo pregunta. Sirve para tareas bien descritas en tu propio proyecto, donde entiendes las consecuencias.

Auto (auto): un modelo supervisor En lugar de ti, cada acción la revisa un modelo clasificador aparte: bloquea lo que se sale de lo que pediste o lo que parece una orden salida de un texto no confiable. Desde la versión 2.1.283 de Claude Code es el modo inicial por defecto en la terminal y en VS Code (si el modo no está disponible en tu plan o tu modelo, la sesión arranca en Manual). Recuerda: auto reduce las preguntas, pero no garantiza la seguridad. En operaciones sensibles, revisa tú.

Don't ask (dontAsk) Solo se permite leer y usar herramientas aprobadas de antemano; todo lo demás se rechaza sin preguntar. Sirve para CI y scripts donde no hay una persona presente.

Bypass permissions (bypassPermissions, saltarse los permisos, confianza total) El agente puede hacer cualquier cosa, incluso ejecutar comandos arbitrarios (se activa con --dangerously-skip-permissions). Nunca lo uses en un entorno de producción ni en tu computadora principal. Solo en contenedores y máquinas virtuales aislados, donde perder datos no sea grave. Las reglas de prohibición (deny) funcionan incluso aquí.

Limitar el acceso de los subagentes

🎨 Imagínalo así: un subagente con acceso limitado es como un practicante al que le dieron permiso de leer pero no de firmar. Estudia los documentos, encuentra problemas, pero no puede cambiar nada. Seguro por definición.

Los subagentes son agentes auxiliares que el agente principal "contrata" para subtareas (ver la lección Subagentes). Puedes controlar qué puede hacer cada uno: en el archivo del subagente, el campo tools permite solo las herramientas listadas y disallowedTools prohíbe herramientas concretas.

Readonly (solo lectura) El subagente puede leer archivos, pero no modificarlos. Útil para agentes analistas: "revisa el código y encuentra problemas", "lee los logs y resúmelos".

Solo MCPs (Model Context Protocol, herramientas externas) El subagente trabaja solo a través de integraciones externas (Notion, Slack, Google Docs) y no toca los archivos locales. Útil para agentes que envían notificaciones o actualizan sistemas externos.

Solo bash (el lenguaje de comandos de la terminal) El subagente puede ejecutar comandos, pero no editar archivos directamente. Para despliegues, compilación y pruebas.

Un agente limitado no romperá lo que no debe tocar: es el principio de mínimo privilegio (least privilege), una base de la seguridad informática.

Guardar secretos en producción

En el desarrollo local usas .env. En producción (el entorno donde el servicio funciona de verdad) necesitas almacenes especializados:

Cloudflare Workers Secrets

bash

wrangler secret put ANTHROPIC_API_KEY
# Escribes el valor: se cifra y se guarda en Cloudflare

Una vez guardado, el secreto no se puede ver: solo el Worker puede usarlo.

Vercel Environment Variables Desde el panel de Vercel o con la CLI:

bash

vercel env add ANTHROPIC_API_KEY production

Separación en development, preview y production: claves distintas para entornos distintos.

Principio: entornos distintos, claves distintas. La clave de prueba no debe coincidir con la de producción.

Rate limiting y control de costos

🎨 Imagínalo así: el rate limiting (límite de frecuencia de solicitudes) es como el medidor de agua de tu casa. Sin él, la llave puede gotear toda la noche y no te enteras. Con un límite: gastaste $20 en el día y la llave se cierra sola hasta que la abras tú.

Las solicitudes a la API cuestan dinero. Sin rate limiting, un solo bug en el código puede acabarse el presupuesto en una noche.

Estrategias de protección:

Límite a nivel de agente: máximo N solicitudes por minuto u hora
Hard cap (tope fijo): si se gastaron más de $X en el día, el agente se detiene y avisa
Monitoreo: un reporte diario de los tokens y el dinero gastados
Pruebas con modelos baratos: desarrolla con Haiku y despliega con el modelo que la calidad requiera (precios y versiones vigentes: Lo vigente)

Práctica

Tarea: configurar un entorno seguro para un proyecto de práctica

Crea una carpeta nueva my-agent-project
Inicializa Git: git init
Crea .gitignore con las líneas .env y node_modules/

Crea .env con variables de prueba (ficticias):

Código

ANTHROPIC_API_KEY=sk-ant-test-placeholder
APP_SECRET=my-super-secret-value

Crea main.py que lea la clave del entorno (sin escribirla en el código)
Ejecuta git add . y git status: asegúrate de que .env NO aparece en la lista
Haz el primer commit: git commit -m "Initial setup with secure .env"
Verifica que git show HEAD no contiene los valores de los secretos

Bonus: prueba Claude Code con distintos modos de permisos (claude --permission-mode plan, claude --permission-mode default) y nota la diferencia en el comportamiento del agente. Y agrega una regla que prohíba leer los secretos: en .claude/settings.json, en la sección permissions → deny, escribe Read(./.env).

Niveles de permisos de Claude Code: referencia rápida

Nivel	Qué puede	Qué NO puede	Cuándo usarlo
Yes (una vez)	Una acción concreta	Repetirla sin preguntar	Una operación desconocida, la primera vez
Yes, and don't ask again	Acciones de ese tipo sin volver a preguntar: para modificar archivos, hasta el final de la sesión; para comandos de Bash y dominios, de forma permanente en ese repositorio	Salirse de lo que aprobaste	Trabajo rutinario en un proyecto de confianza (git commit, npm test)
Plan	Analizar y planear	Modificar archivos, ejecutar código	Primer vistazo a un código nuevo
Auto	Trabajar sin preguntas bajo la vigilancia del modelo supervisor	Garantizar la seguridad	Tareas largas en un proyecto en el que confías
Bypass	Absolutamente todo	—	Solo en un contenedor o VM aislados, NUNCA en producción

Errores comunes

1. La clave de API llegó a un git commit (un cambio guardado) Aunque borres la clave en el siguiente commit, queda para siempre en el historial. Solución: git-secrets + un pre-commit hook (un script que reacciona a un evento, en este caso antes del commit).

bash

# Instala git-secrets y agrega la verificación
brew install git-secrets
git secrets --install
git secrets --register-aws  # para claves de AWS

2. No hay .gitignore antes del primer commit .gitignore se crea ANTES de git init o justo después. Si .env ya está en un commit, borrarlo del historial es más difícil que prevenirlo.

3. Una sola clave para todos los entornos La clave de prueba y la de producción DEBEN ser distintas. Un bug en el código de desarrollo no debe gastar el presupuesto de producción.

4. Olvidar el .env.example Crea un .env.example con los valores vacíos: así otros desarrolladores (o tú dentro de seis meses) sabrán qué variables se necesitan:

Código

OPENAI_API_KEY=
DATABASE_URL=
TELEGRAM_BOT_TOKEN=

5. Bypass permissions en un proyecto de producción Confianza total (--dangerously-skip-permissions, saltarse los permisos de forma peligrosa) = ninguna protección. Un rm -rf equivocado y el proyecto se pierde.

Herramientas y recursos

Claude Code Permissions: documentación oficial, code.claude.com/docs/en/permissions
Claude Code Security: el modelo de seguridad, code.claude.com/docs/en/security
python-dotenv / dotenv (Node.js): cargan .env en las variables de entorno
git-secrets: herramienta de línea de comandos que busca secretos en los commits
Cloudflare Workers Secrets: almacén de producción para Workers
Vercel Environment Variables: almacén de producción para despliegues en Vercel
GitHub Secret Scanning: detección automática de claves filtradas (en repositorios públicos funciona automáticamente; en privados depende del plan y la configuración)

Conclusiones clave

Un secreto que llegó al historial de Git se considera público, aunque el repositorio sea privado. Mejor un agente limitado que una producción rota: el mínimo privilegio es la base de una arquitectura segura. .gitignore se agrega antes del primer commit, no después. Después ya es tarde.

Lecciones relacionadas

Claves de API y .env: cómo obtener y administrar claves de API para distintos servicios
Hooks y Hooks LIVE: verificaciones de seguridad automáticas con hooks pre-commit y pre-tool-use (puedes bloquear un commit accidental de un secreto)

Qué sigue

→ Gestión del contexto: técnicas avanzadas