Harness X-Ray

Una herramienta que audita el arnés de otros proyectos: qué deja expuesto, qué desperdicia y qué le falta.

  • Proyecto del autor
  • Código abierto, MIT
  • Node.js 22+, sin dependencias npm

Esta página describe el repositorio a fecha de 26 de octubre de 2026 (commit 0cdf7c5).

Ver el repositorio en GitHub

Harness X-Ray es un proyecto mío, con su propio repositorio. Le das la ruta de otro proyecto y revisa su arnés: las instrucciones, los permisos, los hooks, las skills y las herramientas que deciden qué lee un agente de programación, qué puede ejecutar y qué recuerda. No busca errores en la lógica del programa, sino vulnerabilidades y partes del arnés que no funcionan del todo bien.

Qué hace

Responde tres preguntas sobre el arnés del proyecto que revisa:

  • Qué deja expuesto: comandos destructivos o secretos que el agente puede alcanzar sin ninguna barrera, y texto escrito para manipularlo.
  • Qué desperdicia: el contexto que se carga en todas las sesiones, se use o no.
  • Qué le falta o no funciona: una forma de verificar los cambios, un mapa del repositorio, referencias rotas o protecciones que el texto promete y nada aplica.

Sus 19 reglas se agrupan en seis ejes: instrucciones, contexto, seguridad, verificación, estructura y código. Cada recomendación cita su fuente y el resultado es un informe en Markdown y en HTML. X-Ray nunca ejecuta código del proyecto que revisa ni escribe en él. Para entender por qué importa, lee Ejecución segura de agentes.

Cómo funciona

  1. El escáner mide. Un script lee el proyecto como texto y decide con números las reglas que se pueden medir, como cuántos tokens se cargan en cada sesión.
  2. El agente juzga. Lee solo los archivos que el escáner nombra y aplica las reglas de criterio, como si dos instrucciones se contradicen.
  3. El renderizador comprueba. Valida cada hallazgo contra las reglas, las medidas y el proyecto. Si algo no cuadra, no escribe el informe.

Es la misma idea de los hooks de los arneses de esta web: lo que se puede comprobar con código no se deja al criterio del modelo.

Se ejecuta desde Claude Code, con una skill que guía la auditoría, y el proyecto que revisa puede ser cualquiera: preparado para Claude Code, para otro agente o para ninguno. Lo que depende de cómo carga cada agente sus archivos (el contexto, los permisos y los hooks) solo está verificado para Claude Code, y el informe marca el resto como no verificado. También trae un modo de integración continua, sin agente, que aplica solo las reglas medidas.

Pruebas en tres repositorios públicos

El 27 de octubre de 2026 pasé X-Ray (commit 0cdf7c5) por tres repositorios públicos con arneses muy distintos. Cada auditoría la hizo un agente en una sesión sin supervisión, y ese mismo agente revisó los hallazgos.

Hallazgos de la auditoría estándar de cada repositorio, por impacto. Las referencias rotas falsas se cuentan en Medio.
RepoAltoMedioBajoReferencias rotas falsas
kube-image-keeper
89c2850
075067 de 67
glances
7daaaeb
03131 de 1
dyad
1be2b4b
423517 de 18
  • kube-image-keeper: el arnés más completo de los tres, con permisos allow, ask y deny, hooks, subagentes y skills. En el modo por defecto, ningún comando destructivo de la lista de X-Ray pasa sin preguntar. Destacan los permisos de Bash con comodín que dejan ejecutar código, y también el ruido: 67 de sus 75 hallazgos medios son referencias rotas falsas.
  • glances: un arnés mínimo. Sus 9 reglas deny están escritas como Read: build/** y no como Read(build/**), y sus 17 skills son archivos sueltos y no carpetas con SKILL.md. Ninguno de los dos es el formato que documenta Claude Code, así que probablemente no tengan efecto, aunque no se comprobó en una sesión real.
  • dyad: el más permisivo y el único con hallazgos altos, así que fue el único que hizo fallar el modo de integración continua con --fail-on high. Permite Bash(git:*) sin ninguna regla ask o deny, y el escáner calcula que git push --force y git reset --hard pasan sin preguntar.

Lo que mostraron sobre X-Ray

  • El flujo completo funciona. Los comandos terminaron con el código esperado y todos los informes pasaron la validación al primer intento.
  • Una regla hace demasiado ruido. RUL-04 reportó 86 referencias rotas, y el agente consideró falsas 85: imports de Go, nombres como owner/repo o sintaxis como try/except.
  • El escáner no lo ve todo. Acepta sin avisar reglas de permisos mal escritas y skills que no siguen el formato, y no mide los hooks que aprueban comandos en vez de frenarlos. Esos problemas solo aparecieron al leer los archivos.

Son tres repositorios y una pasada por cada uno: sirve para ver cómo se comporta X-Ray, no para comparar proyectos ni para calibrar sus umbrales, que siguen siendo provisionales. Los números describen el arnés en ese commit, no la calidad del software, y pueden haber cambiado. El análisis fue estático: no se ejecutó código de esos proyectos ni se abrió una sesión de agente dentro de ellos. Los informes completos no están publicados.

Cómo probarlo

Necesitas Node.js 22 o superior y Claude Code. No hay dependencias que instalar.

git clone https://github.com/brahianDev21/harness-x-ray.git
cd harness-x-ray
claude

Dentro de Claude Code, pide scan this repo's harness: <ruta> o usa la skill /xray-scan. El proyecto que revises tiene que estar fuera de la carpeta de X-Ray, y no debes añadirlo con --add-dir, porque Claude Code cargaría sus instrucciones en la sesión. Los informes salen en inglés, salvo que pidas el español. El README explica el resto de opciones.

Sus límites

  • Es un análisis estático, no una auditoría de seguridad completa: lee los archivos como texto y no ejecuta comandos ni hooks, así que no sabe si un hook bloquea de verdad lo que promete.
  • Los tokens se estiman a partir de los caracteres; no se cuentan.
  • Comprobar en vivo cómo se comporta un arnés es una segunda función que está en diseño y todavía no tiene código.