Seguridad de Codex en la práctica: permisos, sandbox y protección contra fugas de secretos

En la raíz de tu proyecto hay un archivo .env con la contraseña de la base de datos y claves API de terceros. Abres Codex para que te ayude a refactorizar código de tests. En el menú aparecen read-only, workspace-write y danger-full-access. ¿Cuál eliges?

Después de elegir workspace-write, Codex te pide aprobar npm install. Haces clic en aprobar. ¿Te has preguntado si ese script postinstall medio olvidado en package.json podría leer tus variables de entorno o enviar una solicitud a un servicio que no conoces?

Pones Codex en GitHub Actions para automatizar PR review. En el workflow escribes OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}. Piensas que secrets es seguro. Pero ¿has pensado que los scripts de prueba, las third-party actions y los install hooks de dependencias en el mismo job también podrían leer esa clave?

Tres límites responden directamente a estas preguntas: las instrucciones no son permisos, la aprobación no es aislamiento y sandbox no es auditoría. A continuación tienes una checklist de permisos mínimos para escenarios local, Cloud y CI.

Los permisos no se sostienen con reglas verbales: entiende las tres capas sandbox, approval y permission profile

Mucha gente cree que escribir una línea en AGENTS.md como “no leas el archivo .env” impide que Codex acceda a información sensible. Eso no es control de permisos, sino una regla de proyecto. El límite de seguridad real viene de tres capas: sandbox restringe el alcance de los spawned commands, approval policy decide cuándo detenerse y preguntar, y permission profile es el control de acceso forzado.

La seguridad de Codex no se resuelve con una sola capa. sandbox decide a qué pueden acceder git, los gestores de paquetes y los test runners como spawned commands. approval policy decide si Codex necesita tu aprobación antes de operaciones clave. permission profile es la capa de configuración donde realmente puedes escribir "**/*.env" = "deny". Las tres capas juntas forman los permisos efectivos.

Comparación de modos sandbox: read-only, workspace-write, danger-full-access

modo sandbox	Definición	Casos adecuados	Riesgo
read-only	Solo permite leer archivos; no permite escribir ni ejecutar comandos	Revisión de código, análisis de arquitectura, generación de documentación, controles CI de solo lectura	No protege todos los secrets del runner; el proceso sigue corriendo en el runner
workspace-write	Permite escribir en el active workspace; la red está cerrada por defecto	Desarrollo local diario, cambios de código, ejecución de tests	Puede leer por defecto todos los archivos del workspace, incluido .env; hace falta un deny glob
danger-full-access	Elimina límites de filesystem y red	isolated CI runner/container, entorno de pruebas completamente controlado	Puede acceder a ~/.ssh, /tmp, variables de entorno y servicios locales; no debe ser el valor por defecto diario

sandbox restringe spawned commands, no solo operaciones de archivo integradas de Codex. git, gestores de paquetes y test runners heredan ese límite. La plataforma también importa: Linux/WSL2 depende de bubblewrap o user namespace, macOS de la sandbox del sistema y Windows de las capacidades de sandbox disponibles.

approval policy decide cuándo detenerse y preguntar:

approval policy	Definición	Combinación común	Permisos efectivos
on-request	Pausa antes de ejecutar y solicita aprobación	workspace-write + on-request para automatización local	Menor riesgo; un humano confirma escritura, comandos y solicitudes de red
never	No muestra aprobación interactiva; ejecuta directamente	read-only + never para CI de solo lectura; danger-full-access + never en entorno controlado	Alto riesgo; workspace-write + never sin permission profile es peligroso

Combinaciones de bajo riesgo: read-only + never para CI de solo lectura y workspace-write + on-request para desarrollo local. Combinación de alto riesgo: danger-full-access + never, solo en entornos controlados.

Configuración de permission profile: filesystem deny, network rules

permission profile es control de acceso forzado, no una instrucción verbal. Los permisos filesystem admiten read/write/deny; las reglas más específicas sobrescriben las más amplias y deny tiene prioridad.

Ejemplo de deny glob para .env:

{
  "filesystem": {
    "rules": {
      "**/*.env": "deny",
      "**/.env.local": "deny",
      "**/secrets/**": "deny",
      "workspace/**": "write"
    }
  }
}

Con esta configuración, los archivos .env siguen siendo ilegibles bajo workspace-write, aunque el workspace sea escribible por defecto. deny gana, y las reglas concretas sobrescriben las amplias.

network profile permite configurar enabled = true y reglas allow/deny por dominio; deny también tiene prioridad. local/private network tiene protección por defecto; permitir localhost o Docker socket es una excepción explícita. Docker socket es un escape hatch local: puede alcanzar servicios locales, contenedores y redes, así que conviene abrirlo con cuidado.

network proxy restringe el acceso de red de comandos que ya están habilitados; no concede red por sí solo. Un allow global * es acceso de red amplio y debe tratarse con cautela.

Checklist local de permisos mínimos: de una revisión read-only a full access

En desarrollo local, más permisos no siempre ahorran problemas. La aprobación detiene algunas operaciones, pero el aislamiento real lo dan sandbox y permission profile. Empieza por los permisos más estrechos y amplía según la tarea.

Tabla de decisión: cuándo usar read-only y cuándo workspace-write

Escenario	modo sandbox	approval policy	permission profile	Riesgo
Revisión de código / análisis de arquitectura	read-only	never	No necesario	Bajo
Desarrollo diario / cambios de código	workspace-write	on-request	Configurar deny .env	Medio-bajo
Ejecutar tests / instalar dependencias	workspace-write	on-request	deny .env, auditar scripts	Medio
CI de solo lectura	read-only	never	No necesario	Bajo
CI necesita escribir archivos	workspace-write	never	deny, isolated runner	Medio-alto
Necesita full access	danger-full-access	never	Solo entorno controlado	Alto

Pasos para proteger .env y archivos de secretos:

1. Identifica la ruta del archivo de configuración de permission profile que usas, según la documentación de Codex Permissions.
2. Añade "**/*.env" = "deny" a los permisos filesystem.
3. Confirma que las reglas más específicas sobrescriben las más amplias y que deny tiene prioridad.
4. Prueba: en modo workspace-write, intentar leer .env debería ser denegado.
5. Amplía si hace falta con "**/.env.local" = "deny" y "**/secrets/**" = "deny".

No dependas de reglas verbales. AGENTS.md guía, pero no aplica control de acceso forzado. Codex puede seguir la guía, pero también puede leer por otros motivos. Solo el deny de permission profile es obligatorio.

Riesgo de instalación de dependencias: npm postinstall, pip hooks, Docker socket

Instalar dependencias no es solo descargar archivos. postinstall y prepare de npm/pnpm, y los hooks de pip install, se ejecutan automáticamente durante la instalación. Estos scripts pueden leer variables de entorno, enviar solicitudes de red o modificar archivos del sistema.

Checklist de riesgos:

• Un postinstall desconocido puede leer variables de entorno: aunque tengas deny para .env, postinstall se ejecuta dentro del entorno de spawned commands y puede ver environment variables.
• Puede enviar solicitudes de red: descargar binarios adicionales, enviar telemetría, conectar a repositorios privados.
• Puede modificar archivos del sistema: escribir configuración global, cambiar PATH.

Recomendaciones de auditoría:

1. Revisa primero scripts y origen: campo scripts de package.json, setup.py de paquetes pip.
2. Usa fuentes confiables: fija versiones y evita upgrades automáticos a versiones desconocidas.
3. Aprueba en un entorno controlado: en local usa workspace-write + on-request y lee qué quiere instalar Codex antes de aprobar.

Docker socket es un escape hatch local. Permitir Docker socket puede dar acceso a servicios locales, contenedores y redes. Configúralo solo cuando sea claramente necesario, no por defecto.

Límites en Cloud: setup vs agent phase, ciclo de vida de secrets

Una Cloud task no corre en local, sino en un contenedor aislado hospedado por OpenAI. sandbox puede restringir spawned commands, pero la seguridad real de las claves viene del ciclo de vida de Cloud secrets: disponibles en setup, eliminados antes de agent phase. sandbox no es auditoría; la seguridad viene de separar capas.

Ciclo de vida del Cloud container:

1. Crear container
2. Hacer checkout del repo
3. Ejecutar setup script
4. Aplicar configuración de red
5. El agent ejecuta el bucle de comandos
6. Emitir answer/diff

Límite entre setup y agent phase: secrets solo en setup

fase	Acceso de red	secrets disponibles	environment variables	Instalación de dependencias
setup scripts	Con red	Disponibles	Presentes todo el tiempo	Permitida
agent phase	Sin red por defecto	Eliminados	Presentes todo el tiempo	Sin red por defecto

En setup hay red, instalación de dependencias y secrets. En agent phase, el entorno está offline por defecto, los secrets ya fueron eliminados y solo quedan environment variables.

setup scripts corren en una sesión Bash separada; un export no pasa automáticamente a agent phase. Si haces export MY_KEY=xxx en setup, agent phase no hereda esa variable. Entre fases solo se transmiten Cloud secrets y environment variables según sus reglas.

secrets vs environment variables: diferencia clave

Tipo	Cifrado	Fases disponibles	Uso	Ciclo de vida
environment variables	Sin cifrado adicional	setup + agent todo el tiempo	Configuración no sensible, rutas, switches	Siempre presentes durante la vida del container
secrets	Cifrado adicional	Solo setup scripts	Acceso a repositorios privados, autenticación para dependencias	Eliminados antes de agent phase

secrets solo están disponibles en setup scripts. Sirven para instalar dependencias o conectar repositorios privados. agent phase no debería tener secretos de producción. environment variables permanecen todo el tiempo y sirven para configuración no sensible.

Límites de instalación de dependencias:

• setup phase puede instalar dependencias con red.
• agent phase está offline por defecto.
• setup scripts puede acceder a secrets; un script desconocido puede filtrarlos.
• Recomendación: revisa scripts y origen, usa fuentes confiables y evita ejecutar scripts desconocidos en setup.

El container cache dura como máximo 12 horas. Cambios en setup, maintenance, env o secrets provocan cache invalidation.

CI y GitHub Action: codex exec, prohibiciones con API key y estrategia de seguridad de la official Action

codex exec usa por defecto read-only sandbox, pero muchas personas colocan OPENAI_API_KEY como job-level environment variable en el workflow. Los scripts de prueba, third-party actions y dependency lifecycle scripts del mismo job pueden leer esa clave. sandbox no es auditoría; la seguridad viene de permisos mínimos y protección de la clave.

Prohibición de API key: no usar job-level env

No definas OPENAI_API_KEY o CODEX_API_KEY como job-level environment variable en un workflow que hace checkout o ejecuta código del repositorio. El código del repositorio, tests, dependency lifecycle scripts y third-party actions pueden acceder a variables de entorno dentro del mismo job.

Checklist de prohibiciones:

• No pongas OPENAI_API_KEY como job-level env.
• No configures una job-level key en workflows que hacen checkout o ejecutan código del repositorio.
• auth.json / ChatGPT-managed auth no encaja en workflows de repositorios public/open-source.
• No ejecutes código no confiable en el mismo process environment que la clave.

Formas correctas:

1. Invocation inline única: configura CODEX_API_KEY solo para una invocation de codex exec.

- name: Run Codex
  run: CODEX_API_KEY=${{ secrets.CODEX_API_KEY }} codex exec "review PR #${{ github.event.number }}"

2. Proxy de official Action: usa el proxy de openai/codex-action@v1.

- uses: openai/codex-action@v1
  with:
    prompt: "review PR #${{ github.event.number }}"
    sandbox: read-only
    safety-strategy: drop-sudo

danger-full-access en CI solo encaja en isolated CI runner/container. No debería ser la opción por defecto, porque puede acceder a todos los recursos del runner.

Checklist de seguridad en GitHub Action: limitar disparadores, proteger claves, rotar claves

Parámetros de la official Action:

parámetro	valor por defecto	descripción
safety-strategy	drop-sudo	Elimina permisos sudo
sandbox	-	Elige read-only/workspace-write/danger-full-access
allow-users	usuarios con write access	Solo usuarios concretos pueden disparar
allow-bots	-	Si se permite que bots disparen

read-only no significa que todos los secrets del runner estén protegidos. La Action sigue corriendo en el runner; solo restringe el filesystem a lectura. drop-sudo elimina sudo. sandbox debería ser el modo más estrecho que permita completar la tarea.

Checklist de seguridad de GitHub Action:

• Limitar disparadores: allow-users solo para usuarios concretos, allow-bots con cuidado.
• Limpiar entradas PR/issue/prompt: evitar prompt injection y no pasar input no confiable directamente a Codex.
• Proteger API key: no usar job-level env, usar invocation inline única o proxy.
• Ejecutar Codex como último paso: reducir el tiempo de exposición de la clave.
• Si sospechas fuga, rotar la clave: no investigar primero; primero cortar el daño.

Las entradas PR/issue/prompt deben tratarse como no confiables. No pases directamente un PR comment o issue body al prompt de Codex.

Manejo de fugas de secretos: el primer paso tras una sospecha

Si sospechas una fuga, el primer paso no es investigar, sino rotar la clave. Primero corta el daño, luego audita. sandbox puede restringir spawned commands, pero no puede impedir que Codex escriba una clave en logs, PR comments o answer.

Pasos ante una fuga: rotación de clave, auditoría, revocación

Primer paso: rotar la clave. No busques primero el origen; invalida la clave antigua.

Pasos posteriores:

1. Auditar logs: revisar el historial de uso de la clave y buscar llamadas anómalas.
2. Revocar token: confirmar que la clave antigua ya no funciona y que no queda una session activa.
3. Buscar origen: revisar Codex log, salidas de GitHub Action, scripts de instalación de dependencias y third-party actions.

Medidas preventivas:

• No pongas API key en código frontend ni en el repositorio.
• No pongas API key como job-level env (CI).
• Usa permission profile deny para .env.
• Rota claves con regularidad, como recomienda OWASP Secrets Management Cheat Sheet.

Límite de Codex Security: no sustituye SAST ni aplica patches automáticamente

Codex Security es un LLM-driven security analysis toolkit que corre en un ephemeral isolated container y produce findings estructurados y propuestas de patch. Puede ayudar a encontrar y verificar vulnerabilidades, pero no sustituye SAST ni revisión manual de seguridad.

Checklist de límites:

• No sustituye SAST.
• No sustituye manual security review.
• Un proposed patch necesita review del usuario y no se aplica automáticamente.
• Su uso es ayudar a descubrir, verificar y sugerir, no reparar de forma automática.

No trates Codex Security como un escáner de seguridad universal. El AI-driven analysis puede encontrar algunos problemas, pero la seguridad real viene de capas: alcance legible, alcance escribible, red, secrets, approval, review y revocación.

Conclusión

El límite de seguridad de Codex viene de tres capas: sandbox restringe el alcance de spawned commands, approval policy decide cuándo detenerse y preguntar, y permission profile aplica control de acceso forzado. Las tres juntas forman los permisos reales.

Tres límites para recordar:

• Las instrucciones no son permisos: AGENTS.md es una guía, no control de acceso forzado. No protejas .env ni API key solo con reglas verbales.
• La aprobación no es aislamiento: approval policy puede detener algunas operaciones, pero el aislamiento real viene de sandbox y permission profile.
• sandbox no es auditoría: sandbox puede restringir spawned commands, pero no puede impedir que Codex escriba una clave en logs, PR comments o answer. La seguridad viene de capas.

Checklist rápida:

• ¿Configuraste un deny glob para .env?
• ¿Evitas job-level API key en CI?
• ¿Limitas quién puede disparar la GitHub Action?
• ¿Auditaste los scripts de instalación de dependencias?
• ¿Tienes un plan de rotación de claves?

Los límites de seguridad no bloquean errores lógicos. Codex puede respetar todas las reglas de permisos y aun así generar código con bug, los tests pueden fallar y puede hacer falta rollback. Revisar el diff, ejecutar tests y preparar un plan de rollback es la segunda línea de defensa fuera del límite de seguridad.

Siguientes pasos:

• Retrospectiva de fallos y flujo de validación: entender cómo manejar errores de Codex, validar diffs y preparar rollback.
• Automatización con codex exec y CI: profundizar en modo no interactivo, diseño de workflows y manejo de errores en CI.
• Reglas de proyecto AGENTS.md: aprender a escribir reglas de proyecto, recordando que son guía y no sistema de permisos.

Lecturas relacionadas:

• Panorama de herramientas de AI coding 2026: entender el ecosistema general de herramientas de AI coding.
• Fundamentos de CI con GitHub Actions: repasar conceptos básicos de CI workflow.
• Estrategia de despliegue con GitHub Actions: entender los límites de uso de secrets en despliegues.
• Riesgo de fuga de API key en frontend: entender por qué las claves no deben entrar en el frontend ni en el repositorio.