Seguridad de AGENTS.md: cómo archivos ajenos controlan a los agentes de IA

En un caso, bastó un discreto archivo de texto en la carpeta Descargas para que un agente de programación con IA intentara instalar un paquete malicioso. Este artículo trata la seguridad de AGENTS.md: qué ocurrió, qué archivos de instrucciones cargan Codex, Claude Code y Cursor, y qué ajustes y medidas pueden evitar el daño.

Un hallazgo en el equipo de un cliente y sus consecuencias

El proveedor de seguridad Forever Security descubrió lo siguiente: en el ordenador de un cliente, la carpeta Descargas (Downloads) contenía un archivo de instrucciones llamado AGENTS.md que debía llevar a un agente de programación con IA a instalar un paquete npm. El archivo no es un programa, pero actúa como una instrucción.

Qué ocurrió: hallazgo en la carpeta Descargas, prueba de reproducción y tasas de éxito

El punto de partida fue un hallazgo real. El archivo estaba en la carpeta Descargas de un desarrollador. Esa carpeta era al mismo tiempo el directorio de trabajo del agente. El agente quería instalar el paquete npm function-color. Según su propia versión, Forever Security lo detuvo antes de que se ejecutara código. Los investigadores no pudieron aclarar cómo llegó el archivo a la carpeta.

El paquete function-color arrastra otro paquete llamado function-flag. Este descarga y ejecuta un malware para Windows. CloudSEK y Checkmarx denominan la campaña MALFEX.

Prueba de reproducción con Codex

Forever Security reprodujo el ataque en una máquina virtual aislada. El archivo real indicaba a Codex que registrara un servidor en el archivo ~/.codex/config.toml y ejecutara un comando que instala el paquete. Como esta configuración se aplica a todas las sesiones de Codex del equipo, el cambio es permanente y actúa en cualquier carpeta. La tasa de éxito fue de aproximadamente el 90 %.

Prueba de reproducción con Claude Code

Con Claude Code se usó otro archivo. Un CLAUDE.md manipulado se hacía pasar por la configuración de un gateway interno y debía llevar al agente a escribir una dirección ajena como destino de la API en un archivo de configuración del proyecto. Así, el tráfico de la API iría a un servidor de los investigadores. Eso expone el token de autenticación de la sesión, y el servidor puede devolver comandos que el agente ejecuta. Claude Code suele pedir confirmación para estas escrituras y a menudo rechaza las sospechosas. Solo una justificación larga, con un tono casi de documentación para desarrolladores, consiguió la aprobación en aproximadamente la mitad de los casos.

Las dos cifras no son directamente comparables. Se trata de agentes distintos, archivos distintos y objetivos distintos. El tamaño de la muestra y la configuración de la prueba (sandbox, modo de aprobación) no están claros.

Telemetría: ¿qué tan habitual es iniciar en la carpeta Descargas?

Aproximadamente la mitad de los clientes de Forever Security inicia un agente de programación en la carpeta Descargas, y alrededor de una cuarta parte de las sesiones abre un navegador. BleepingComputer cita más de 1300 sesiones de Claude Code desde esta carpeta. Ambos son datos del proveedor sobre su propia clientela; no existe una verificación independiente. No está demostrado que los atacantes depositen realmente estos archivos mediante descargas del navegador. La prueba de concepto solo descargó un archivo inofensivo.

Seguridad de AGENTS.md: por qué los archivos de instrucciones ajenos son un riesgo

Los agentes de programación leen al iniciarse los archivos de instrucciones del directorio de trabajo. En ellos hay instrucciones de compilación, reglas de estilo o comandos de prueba. El agente trata este contenido como indicaciones del usuario. No distingue de forma fiable si el archivo procede del equipo o de una fuente ajena. Este es el núcleo de una inyección de prompts indirecta contra un agente de programación: la instrucción no llega desde el campo de entrada, sino desde el contexto.

Dos propiedades inofensivas por separado forman juntas la cadena. Primero, los agentes confían en los archivos de la carpeta abierta. Segundo, las páginas web pueden colocar archivos en la carpeta Descargas sin preguntar si el navegador está configurado así. Chrome, Edge y Firefox guardan por defecto en esta carpeta sin preguntar por la ubicación y solo muestran una notificación. Brave preguntó antes en la prueba. El archivo lleva el nombre y el contenido que fija la página.

La documentación de Claude Code describe CLAUDE.md como contexto y no como configuración impuesta. Para los bloqueos recomienda hooks. De ahí se deriva la regla básica para todo lo demás: lo que solo figura en el texto de un archivo, un agente puede seguirlo o ignorarlo. Lo que figura en los permisos, el programa lo impone.

El navegador no es la única vía

La carpeta Descargas está en el centro del caso, pero no es la única vía. El NVIDIA Developer Blog describe una vía relacionada: un paquete de dependencias comprometido crea él mismo un AGENTS.md. También los repositorios clonados, los archivos comprimidos descomprimidos y los scripts de compilación pueden introducir archivos de instrucciones ajenos en una carpeta de proyecto. Por tanto, el lugar de inicio reduce la superficie de ataque, pero no la elimina.

Valoración: qué dicen los investigadores y los fabricantes

Los investigadores de Forever Security afirman que OpenAI y Anthropic no tienen nada que parchear. El agente sigue su archivo de instrucciones tal como está previsto, de forma comparable a un navegador que muestra una página de phishing. Esa es la valoración de los investigadores. Los dos informes no incluyen una declaración propia de los fabricantes sobre este ataque. BleepingComputer solo señala que ambos fabricantes recomiendan iniciar los agentes en el directorio del proyecto correspondiente. La responsabilidad recae así en los usuarios y en las organizaciones que emplean agentes.

Los riesgos de los agentes autónomos son un tema más amplio. Los artículos sobre el poder sin control de los agentes de IA y sobre la era de los agentes de IA explican por qué los agentes con capacidad propia de actuar necesitan medidas de protección distintas a las del software clásico.

Qué archivos de instrucciones cargan Codex, Claude Code y Cursor

Lo decisivo es qué cuenta como carpeta del proyecto: la carpeta en la que se inicia el agente. Quien inicia en la carpeta Descargas convierte cualquier archivo que haya allí en contexto del proyecto. El siguiente resumen recoge la documentación de los fabricantes (a 26/10/2026). La documentación cambia rápido; en caso de duda, prevalece la versión vigente.

Codex

Según su documentación, Codex lee primero un archivo global en el directorio de Codex (~/.codex, ajustable mediante CODEX_HOME), en concreto AGENTS.override.md o AGENTS.md. Después siguen los archivos desde la raíz del proyecto, normalmente el directorio raíz de Git, hasta la carpeta actual. Por carpeta se tiene en cuenta como máximo un archivo: AGENTS.override.md, AGENTS.md o un nombre alternativo configurado. El límite total es de 32 KiB. Si no se encuentra una raíz de proyecto, solo cuenta la carpeta actual. Eso es justo lo que ocurre en la carpeta Descargas, porque allí no suele haber un repositorio Git.

Claude Code y la seguridad de CLAUDE.md

Según la documentación sobre la memoria, Claude Code carga CLAUDE.md y CLAUDE.local.md del directorio de trabajo y de todos los directorios superiores y, si hace falta, también de las subcarpetas. A ello se suman ~/.claude/CLAUDE.md, la política gestionada del sistema y los archivos de .claude/rules/. Para la seguridad de CLAUDE.md esto significa que un punto de inicio demasiado alto, como el directorio personal, también amplía la superficie, porque se leen los archivos de encima y de al lado.

Claude Code lee AGENTS.md (según la documentación, desde la versión 2.1.277). Por defecto, solo lo hace si en el directorio de trabajo o por encima no hay un CLAUDE.md ni un CLAUDE.local.md. Esto se puede cambiar con el ajuste de las instrucciones del proyecto: claude-md-or-agents-md es el valor por defecto, claude-md-and-agents-md lee ambos y managed-only solo admite instrucciones gestionadas de forma centralizada.

Cursor

Según su documentación, Cursor admite reglas de proyecto en .cursor/rules/ (archivos en formato .mdc, también en subcarpetas) y AGENTS.md en la raíz del proyecto y en subdirectorios. Los archivos anidados se aplican a su ámbito y gana el más específico. A ello se suman las User Rules personales en los ajustes y las Team Rules a través del panel.

Los archivos de configuración como objetivo real

El caso muestra que el archivo de instrucciones a menudo es solo la herramienta. El objetivo son los archivos de configuración en los que un cambio tiene efecto duradero. En Codex es ~/.codex/config.toml, cuyo cambio afecta a todas las sesiones. En Claude Code es el archivo de ajustes .claude/settings.json, en el que se puede fijar el destino de la API mediante una variable de entorno. Por eso, ambos archivos deben figurar en la lista de archivos que un agente no puede modificar sin confirmación.

Proteger los agentes de programación con IA: permisos, hooks y sandbox de Codex

La pregunta obvia es si basta con evitar la carpeta Descargas.

Las medidas actúan en tres puntos: qué puede hacer el agente sin confirmación, qué bloquea un hook con independencia del modelo y qué limita técnicamente la sandbox.

Reglas de permisos en Claude Code

Claude Code admite reglas de los niveles allow, ask y deny por herramienta (documentación sobre permisos). Por defecto, el agente pregunta antes de ejecutar comandos de shell y modificar archivos. Una regla deny se aplica también cuando el agente quiere seguir un archivo de instrucciones. Un ejemplo para el archivo .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Bash(npm install *)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Edit(.claude/**)",
      "Edit(~/.codex/**)"
    ]
  }
}

La notación sigue los ejemplos de la documentación: las reglas de Bash comparan el texto del comando con * como comodín, las reglas de ruta para leer y editar usan la sintaxis de gitignore y ~/ representa el directorio personal. Las modificaciones de archivos se regulan con Edit(…); según la documentación, las reglas de Write no se comprueban contra rutas. Además, bloquear un comando no es una garantía, porque a menudo se puede alcanzar el mismo objetivo con otra llamada. Para lo inevitable están los hooks y la sandbox.

Dos funciones de comodidad exigen precaución. La aprobación con «no volver a preguntar» se aplica, según la herramienta, de forma permanente a un repositorio, y en los modos automáticos ya no es una persona quien decide sobre cada acción. Ninguna de las dos tiene cabida en entornos con código ajeno.

Hooks: bloqueos con independencia del modelo

Un hook PreToolUse se ejecuta antes de la llamada a la herramienta y puede bloquearla, aunque el modelo la considere correcta. La guía de hooks muestra el patrón: el script lee la entrada como JSON desde la entrada estándar y termina con un código de salida para bloquear. Se registra en el archivo de ajustes:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-installs.sh"
          }
        ]
      }
    ]
  }
}

El script block-installs.sh lee con jq el comando del campo tool_input.command, lo compara con una lista de bloqueo (por ejemplo npm install o la combinación de curl y shell) o, mejor, con una lista de permitidos, y en caso de coincidencia indica un motivo en la salida de errores con el código de salida 2. Una segunda palanca poco conocida es el hook InstructionsLoaded. Registra los archivos de instrucciones cargados. Sin embargo, según la documentación no se activa para un AGENTS.md cargado mediante el ajuste, sino solo cuando un CLAUDE.md lo importa. Por eso, un equipo no debería confiar solo en él.

Directrices centrales con Managed Settings

Para los equipos, los ajustes gestionados son la palanca más eficaz. Según la documentación sobre Managed Settings, permissions.deny, sandbox.enabled y env se pueden imponer de forma centralizada. Así sería mucho más difícil imponer un destino de API colado mediante un archivo de instrucciones, como en la prueba con Claude Code. Como valoración: es una conclusión extraída de la documentación, no un efecto demostrado en el caso de Forever Security.

Codex: aprobaciones, nivel de confianza y modos de sandbox

Para la sandbox y los permisos de Codex existen, según la documentación sobre aprobaciones y seguridad, dos niveles. La política de aprobación determina cuándo pregunta Codex (por ejemplo on-request o never). El modo de sandbox determina qué es técnicamente posible: read-only, workspace-write o danger-full-access. En el modo workspace-write, la red está desactivada por defecto.

A ello se suma un nivel de confianza por proyecto en ~/.codex/config.toml (trust_level). Según la documentación, en las carpetas bajo control de versiones se aplica el modo Auto, es decir, escritura en el espacio de trabajo con confirmación. En las carpetas sin control de versiones se aplica read-only hasta que el directorio se marca como de confianza. Una carpeta como Descargas se considera no fiable sin esa marca. El riesgo surge cuando los usuarios confirman el diálogo de confianza. El flag –yolo elimina la sandbox y las aprobaciones y no tiene cabida en las directrices de equipo. No se informó con qué configuración hizo las pruebas Forever Security, por lo que se desconoce si los niveles de protección por defecto actuaron en la prueba.

Cursor

No hay una indicación clara del fabricante sobre las aprobaciones de terminal en Cursor. Por eso, aquí solo cabe recomendar mantener activas las aprobaciones para comandos de terminal y revisar la documentación vigente del fabricante.

Sandbox y aislamiento: limitar el daño aunque el agente siga el archivo

Una sandbox limita lo que puede hacer un agente, incluso cuando sigue una instrucción ajena. La sandbox de Claude Code permite escribir en el directorio de trabajo y en carpetas temporales. El acceso a la red pasa por un proxy con una lista de dominios permitidos que por defecto está vacía. Las rutas protegidas, como los ajustes de Claude Code, el archivo de inicio de la shell .bashrc y los hooks de Git, siguen protegidas contra escritura. Un ejemplo:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    },
    "allowUnsandboxedCommands": false
  }
}

La documentación también señala límites. La sandbox está desactivada por defecto. El acceso de lectura es amplio, por lo que las credenciales deben bloquearse de forma explícita. La protección solo se aplica a los comandos de shell y sus procesos hijos, no a las herramientas de archivos integradas, a MCP ni a los hooks. Sin allowUnsandboxedCommands: false, un comando fallido puede repetirse fuera de la sandbox. En Windows no funciona de forma nativa; para ello se usa WSL2. Frente al código malicioso no es una barrera completa. Para un aislamiento fuerte, los contenedores o las máquinas virtuales son la mejor opción.

Lista de dominios permitidos y entorno desechable

Una lista de dominios permitidos así habría dificultado la descarga del paquete y la redirección de la API. Es una valoración, no una prueba del caso. El código desconocido debe ejecutarse en un entorno desechable: contenedor, máquina virtual o Dev Container, sin las credenciales del perfil principal. Los tokens deberían ser de corta duración. Ante una sospecha, se recomienda considerar comprometido el token de autenticación y renovarlo.

Ajuste del navegador para las descargas

Contra las descargas silenciosas ayuda el ajuste que pregunta por la ubicación antes de cada guardado. En Chrome se llama «Preguntar dónde se guardará cada archivo antes de descargarlo» y se encuentra en la configuración, en Descargas. Edge y Firefox ofrecen opciones equivalentes; los nombres varían según la versión (Firefox: Ajustes, General, Archivos y aplicaciones). En la prueba de BleepingComputer, Brave preguntó por sí mismo. Como alternativa, la carpeta de descargas puede situarse en un lugar que nunca sirva como directorio de trabajo. Un alias de shell o un hook que impida el inicio en ~/Downloads es una opción adicional.

Lista de comprobación para equipos y directriz para el uso de agentes de programación

La siguiente lista resume las medidas. Completa las recomendaciones de los dos informes con las configuraciones de la documentación de los fabricantes.

• Los agentes se inician solo en el directorio raíz de un repositorio de confianza. Descargas, Escritorio y el directorio personal quedan excluidos.
• Los archivos ajenos como AGENTS.md, CLAUDE.md o .cursor/rules se leen antes de abrir un proyecto recién clonado o descomprimido.
• Las solicitudes de permiso y la sandbox permanecen activas. Los modos automáticos y flags como –yolo solo se usan en entornos aislados.
• El acceso a la red pasa por una lista de dominios permitidos, las credenciales quedan fuera de alcance y los tokens son de corta duración.
• Las instalaciones de paquetes por parte de agentes solo se hacen tras aprobación, con lockfile y revisión del registro. El caso de function-color y function-flag muestra con qué rapidez un paquete arrastra otros.
• Los ajustes se gestionan de forma centralizada. Se supervisan los cambios en ~/.codex/config.toml y .claude/settings.json.
• Los archivos de instrucciones cargados se registran, en la medida en que las herramientas lo permitan.
• Plan de incidentes: detener la sesión, renovar tokens y claves, revisar los archivos de configuración y rastrear las instalaciones de paquetes.

Las organizaciones con obligaciones de seguridad de la información incluyen estos agentes en su gestión de riesgos. Eso afecta a la autorización, a la configuración y a la prueba de que las reglas se aplican. Un artículo sobre agentic coding describe cómo organizar su uso en los equipos de desarrollo.

Directriz modelo

Una directriz breve se puede formular en pocas frases. Su ámbito abarca a todos los empleados y proveedores de servicios que usen agentes de programación con IA en dispositivos de la empresa o con datos de la empresa. Los agentes se inician solo en el directorio raíz de un repositorio revisado, nunca en las carpetas Descargas, Escritorio o personal. Los modos automáticos y la desactivación de la sandbox o de las aprobaciones solo se permiten en entornos aislados y desechables sin credenciales. Las instalaciones de paquetes y los cambios en archivos de configuración requieren la aprobación de los desarrolladores. La seguridad informática es responsable de los ajustes centrales, y la dirección del proyecto, de su cumplimiento en el proyecto. Los casos sospechosos se comunican de inmediato a la seguridad informática y los tokens afectados se renuevan sin demora.

Revisar las propias webs y sistemas

El caso afecta sobre todo a los equipos de los desarrolladores. Quien ofrece archivos para descargar forma parte de la cadena con su propia web. Una comprobación de sitios web muestra qué scripts y cabeceras entrega una página, pero solo revisa la página, no el equipo de los desarrolladores. Para una revisión de seguridad sistemática en equipos, los Web Security Checks ofrecen un punto de partida.

Conclusión

La responsabilidad es del usuario; la técnica pone el límite.

Un archivo de texto ajeno puede controlar a un agente de programación porque el agente trata los archivos de la carpeta de trabajo como instrucciones. La protección solo se vuelve fiable con límites impuestos: permisos, hooks, sandbox, lista de dominios permitidos y ajustes gestionados de forma centralizada.

Queda abierto si los atacantes usan en la práctica la vía de las descargas del navegador y cómo llegó el archivo al equipo del cliente. En cualquier caso, parece importante sensibilizar a los empleados y a los desarrolladores (hasta que se extingan).