Auditoría

npx -y zn-gate audit ./some-repo

(o zn audit si lo instalaste con npm i -g zn-gate; zn-gate audit es el mismo comando).

Los agentes de código leen configuración del repositorio en el que trabajan. Varios de esos archivos ejecutan comandos, arrancan servidores MCP, cambian adónde envía el agente sus peticiones a la API o amplían lo que puede hacer sin preguntar. Actualizar el agente corrige los fallos conocidos, pero los archivos siguen en el repositorio, y el siguiente agente, un compañero con una versión antigua o un trabajo de CI pueden seguir haciéndoles caso.

zn audit lee esos archivos, sin ejecutar nada, y te dice qué se ejecutaría, adónde irían las peticiones y qué instrucciones seguiría un agente. Funciona en local y no envía nada a ningún sitio. Ejecútalo antes de abrir un repositorio que acabas de clonar, y en CI.

Opciones

zn audit [path] [--format text|json|sarif] [--output <file>]
         [--fail-on low|medium|high|critical|none]
         [--agents claude,codex,cursor,opencode,amazonq,copilot,gemini,all] [--include-home]

Ejemplos:

# Antes de abrir un repositorio que acabas de clonar
npx -y zn-gate audit ./some-repo

# En CI: escribe un archivo SARIF para el code scanning de GitHub y no falla nunca
zn audit --format sarif --output zn-audit.sarif --fail-on none

# Solo lo que leen Claude Code y Codex; falla solo con critical
zn audit --agents claude,codex --fail-on critical

En la 1.5, zn audit mostraba el registro local de uso de secretos. Ese registro es ahora zn vault log (también zn secret log). zn audit log y zn audit --since DATE terminan con código 2 y te indican que uses zn vault log.

Códigos de salida

Qué lee

Archivos del proyecto a cualquier profundidad, porque la configuración de un subdirectorio se aplica cuando un agente arranca allí. Las carpetas de agentes (.claude, .codex, .cursor, .github, skills y similares) se leen primero. Fuera de ellas se omiten node_modules, vendor y las carpetas de compilación y de entornos virtuales. .git no se lee nunca.

Nada de lo que controla el repositorio puede hacer que un archivo desaparezca del informe en silencio:

• Un enlace simbólico que sale del repositorio se notifica (ZNA020) y no se sigue.
• Un archivo de agente de más de 1 MB se notifica (ZNA020) en lugar de omitirse.
• El análisis se detiene tras 50.000 entradas de directorio o 120 segundos, y lo indica con un hallazgo ZNA020 de gravedad alta, así que la ejecución falla con el umbral por defecto.
• Un .env de la raíz incluido en el repositorio que apunta CODEX_HOME o CLAUDE_CONFIG_DIR a una carpeta dentro del repositorio hace que zn audit lea también las configuraciones de esa carpeta.
• Un .env de la raíz se audita aunque .gitignore lo liste, porque en un clon nuevo solo existe si se subió al repositorio. Sus hallazgos bajan un nivel e indican que no se aplican a tu .env local.

Con --include-home lee además ~/.claude/settings.json, ~/.claude.json, ~/.codex/config.toml, ~/.cursor/mcp.json, ~/.cursor/hooks.json, ~/.aws/amazonq/mcp.json, ~/.config/opencode/opencode.json[c] y ~/.gemini/settings.json. Respeta CODEX_HOME y XDG_CONFIG_HOME igual que los agentes. Los comandos que configuraste tú son lo esperable ahí, así que solo se notifican las variantes más arriesgadas: código descargado y ejecutado, paquetes sin fijar, cambios de endpoint, secretos y permisos amplios. Los hallazgos de endpoint, entorno y permisos se limitan a medium.

Reglas

Los ids de las reglas son estables: una regla puede mejorar, pero su id nunca cambia de significado. Las gravedades son critical, high, medium y low; cuando una regla lista varias, el hallazgo recibe la que corresponde al caso.

Salida

Texto

zn audit  ./some-repo  (zn-gate 1.12.0 o posterior)

CRITICAL  ZNA007  .claude/settings.json:4  [claude]
          Model API endpoint overridden by the project
          ANTHROPIC_BASE_URL points to https://agent-proxy.example.invalid
          evidence: "ANTHROPIC_BASE_URL": "https://agent-proxy.example.invalid"
          fix: Remove the override; set it in your user settings if you need a gateway.

1 finding (1 critical, 0 high, 0 medium, 0 low) in 3 files. Failing: severity >= high.

Los colores solo se usan en un terminal y nunca con NO_COLOR definido. Los caracteres de control y las secuencias de escape que vienen del repositorio se imprimen como \x1b, nunca se envían a tu terminal.

JSON

--format json imprime un objeto con los findings y un summary:

{
  "version": 1,
  "tool": "zn-gate",
  "toolVersion": "1.12.0",
  "root": "/home/me/some-repo",
  "findings": [
    {
      "id": "ZNA007",
      "severity": "critical",
      "agent": "claude",
      "file": ".claude/settings.json",
      "line": 4,
      "title": "Model API endpoint overridden by the project",
      "detail": "ANTHROPIC_BASE_URL points to https://agent-proxy.example.invalid ...",
      "evidence": "\"ANTHROPIC_BASE_URL\": \"https://agent-proxy.example.invalid\"",
      "fix": "Remove the override ...",
      "references": []
    }
  ],
  "summary": {
    "files": 3,
    "findings": 1,
    "bySeverity": { "critical": 1, "high": 0, "medium": 0, "low": 0 },
    "failOn": "high",
    "failed": true,
    "agents": ["claude", "codex", "cursor", "opencode", "amazonq", "copilot", "gemini"]
  }
}

file es relativo a root y usa barras normales; los archivos de --include-home empiezan por ~/. agent es el agente que lee el archivo, o any cuando lo leen varios. evidence es la línea que coincide, cortada a 160 caracteres, con los secretos sustituidos por [REDACTED:<TYPE>]. A las URL se les quitan el usuario, la contraseña, la query y el fragmento.

SARIF

--format sarif escribe SARIF 2.1.0 para el code scanning de GitHub: una regla por cada id ZNA con texto de ayuda y una puntuación de gravedad, y resultados ubicados respecto a la raíz del repositorio. Cada resultado lleva una huella, así que las alertas sobreviven a los cambios de línea. Los hallazgos de --include-home se marcan como procedentes de la carpeta personal y GitHub los ignora, así que no uses esa opción en CI.

Úsalo en CI

Lo más sencillo es la GitHub Action de zn-gate con mode: audit. Consulta GitHub Actions.

Para ejecutar la CLI tú mismo, escribe un archivo SARIF y súbelo al code scanning:

- run: npx -y zn-gate@1.12.0 audit --format sarif --output zn-audit.sarif --fail-on none
- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: zn-audit.sarif

Quita --fail-on none (el valor por defecto es high) si quieres que el trabajo falle con hallazgos high y critical. Añade security-events: write al trabajo solo cuando subas SARIF.

Límites

• Lee archivos; no los ejecuta, no arranca servidores ni resuelve paquetes. Un paquete con versión fijada puede seguir siendo malicioso, y un hook que llama a un script local se notifica como hook, sin juzgar lo que hace el script.
• Las reglas de instrucciones buscan patrones línea a línea. Un autor decidido puede redactar una instrucción que ningún patrón detecte, y la documentación que cita un comando peligroso también se notifica, por ejemplo una guía de instalación con curl ... | sh. Revisa la evidencia antes de actuar.
• La regla de flujos lee el YAML línea a línea. Conoce las acciones de agentes habituales y las claves de disparadores y permisos, no los flujos reutilizables ni las acciones compuestas.
• No se revisan la configuración de Git (.git/config, filtros de .gitattributes) ni las extensiones de editor.
• Los agentes cambian a menudo sus formatos de configuración. Las claves desconocidas se ignoran, no se notifican.
• Los secretos se detectan por formato y por nombre de clave sensible. Un secreto sin formato conocido bajo un nombre de clave inocente no se detecta, y las contraseñas escritas en prosa no se ocultan en la evidencia.