Plantilla · Intermedio · 5 min

Comprobador de settings.json de Claude Code: detecta riesgos

Pega tu settings.json de Claude Code y ve cada riesgo de permisos con su nivel, la explicación en español y el enlace a la documentación oficial.

Probado con Claude Code 2.1.316 · revisado 2026-11-01

Ver los archivos en GitHub Gratis · licencia MIT

Qué incluye

La herramienta está arriba: pegas un .claude/settings.json, ~/.claude/settings.json o settings.local.json, eliges de qué archivo es y en un segundo ves cada riesgo ordenado por nivel (crítico, alto, medio, bajo, info), con su explicación en español y el enlace a la página oficial que lo respalda. Son 21 reglas, cada una basada en una frase concreta de las páginas de permisos, modos de permiso, sandbox y referencia de ajustes de Claude Code 2.1.316, y todas tienen pruebas automáticas. Funciona entera en tu navegador: el texto no sale de tu equipo.

El código (un único archivo JavaScript sin dependencias, un index.html de ejemplo, sus pruebas con Node y los archivos de ejemplo) está en el repositorio gratuito ctrlia-comprobador-settings.

Reglas críticas y altas

Sobre R06, la doc explica que los ejecutores como devbox run o docker exec no se quitan del comando y que Bash(git * main) incluye git -c, que ejecuta un programa.

Reglas medias, bajas e informativas

Límites honestos

Es una revisión del texto de las reglas, no un análisis del sistema:

1. No lee tus hooks ni tus scripts, solo avisa de que existen.
2. La lista de ejecutores es fija y puede faltar alguno (por ejemplo un script propio que acepte comandos).
3. No combina los cuatro ámbitos como hace Claude Code; por eso conviene comprobar también /permissions.
4. Las reglas Read deny solo protegen frente a las herramientas de Claude y a los comandos de archivo que Claude Code reconoce (cat, head, sed…), no frente a un programa en Python o Node que abra el archivo por su cuenta, como dice la doc; para eso está el sandbox.
5. «Sin hallazgos» no significa seguro.

Cada hallazgo enlaza a la página oficial para que no tengas que fiarte de nosotros. Las reglas se revisan cada 30 días contra el CHANGELOG, porque el sistema de permisos cambia casi en cada versión.

Privacidad y diseño técnico

Un único script servido desde ctrlia.dev, cargado con defer, sin código en línea, sin fetch, sin almacenamiento y sin dependencias. El JSON se analiza con JSON.parse (nunca eval) y los resultados se pintan con textContent, así que un archivo con HTML o scripts dentro no puede ejecutarse. La función analizar(texto, ambito) es pura y devuelve {error} o {hallazgos: [{id, nivel, texto, doc}]}, lo que permite probarla con Node y reutilizarla, por ejemplo en un hook. Accesibilidad: label en el selector y en el área de texto, botón real, resultados en una lista con aria-live="polite" y niveles indicados con texto, no solo con color. Aunque nada se envía, quita las claves antes de pegar.

Cómo usarla

1. Elige de qué archivo es

Importa, porque Claude Code trata distinto cada ámbito. bypassPermissions o auto en .claude/settings.json o settings.local.json no tienen efecto (la sesión arranca en Manual), pero en ~/.claude/settings.json sí; y las reglas allow de un archivo de proyecto solo se aplican cuando aceptas confiar en la carpeta, mientras que deny y ask se aplican siempre.

2. Pega el contenido y pulsa «Comprobar»

Si no es JSON válido te dice la posición del error: el archivo no admite comentarios ni comas finales.

3. Lee los hallazgos de crítico a info

Abre el enlace de cada uno: es la página oficial que lo explica.

4. Corrige y vuelve a comprobar

Corrige con la receta Permisos de Claude Code y vuelve a pegar el archivo. Para ver lo que de verdad está cargado (sumando todos los ámbitos), dentro de Claude Code ejecuta:

/permissions

Lista cada regla y el archivo del que viene. La herramienta mira un archivo a la vez; Claude Code combina los de usuario, proyecto, local y gestionado.

Los archivos

Un .claude/settings.json de proyecto con errores típicos (ejemplo.json en el repositorio):

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(python3 *)", "Bash(git * main)", "WebFetch"],
    "deny": ["Bash(curl *)", "Write(./secrets/**)"]
  },
  "enableAllProjectMcpServers": true,
  "env": { "STRIPE_SECRET_KEY": "sk_test_1234567890" }
}

Salida real del comprobador con ese ejemplo, ámbito proyecto:

R06 · alto: «Bash(python3 *)» equivale a ejecutar código arbitrario: python3 ejecuta lo que va detrás. Escribe el comando exacto (p. ej. Bash(python3 -m pytest *)).
R07 · medio: «Bash(git * main)» tiene un * antes del subcomando: también aprueba opciones como git -c, que ejecutan programas. Pon el * al final.
R09 · alto: No hay deny para .env: añade "Read(.env)" y "Read(.env.*)" (un nombre suelto cubre cualquier profundidad). Bloquea las herramientas de Claude y cat/head/sed, no un script que abra el archivo: para eso, el sandbox.
R11 · medio: «Bash(curl *)» no es un bloqueo de red: no para /usr/bin/curl, sh -c "curl …" ni otros programas. Para bloquear red de verdad, activa el sandbox con su lista de dominios.
R12 · medio: «Write(./secrets/**)» nunca coincide: las rutas solo se comprueban con Edit(...) y Read(...). Si era un deny, no te protege.
R13 · alto: enableAllProjectMcpServers: true aprueba sin preguntar todos los servidores de .mcp.json (en el archivo de proyecto, una vez aceptas confiar en la carpeta).
R15 · medio: «WebFetch» permite descargar cualquier URL sin preguntar: puerta para instrucciones inyectadas. Limita a dominios concretos.
R17 · crítico: env.STRIPE_SECRET_KEY tiene un valor que parece un secreto en un archivo que se sube a git. Usa variables del sistema o apiKeyHelper.
R19 · info: Sandbox desactivado. Es lo único que bloquea lectura de archivos y red para cualquier proceso, no solo para las herramientas de Claude (/sandbox).
R21 · info: Las reglas allow de este archivo solo se aplican cuando aceptas confiar en la carpeta; deny y ask se aplican siempre.

En la página los hallazgos salen ordenados de crítico a info, cada uno con su enlace.

Punto de partida que pasa el comprobador sin avisos altos ni críticos (punto-de-partida.json, para .claude/settings.json): allow con comandos exactos, ask para git push y git commit, deny para .env, .env.*, secrets/** y claves, y el sandbox activado en modo estricto.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(python3 -m pytest *)",
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "ask": ["Bash(git push *)", "Bash(git commit *)"],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(./secrets/**)",
      "Read(**/*.pem)",
      "Read(**/*.key)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}

Antes de copiarla, adapta los comandos a tu proyecto: una regla que no coincide no protege ni ahorra preguntas. Con el sandbox activado y autoAllowBashIfSandboxed por defecto, la doc indica que los comandos dentro del sandbox se ejecutan sin preguntar: el límite pasa a ser el sandbox, no la lista allow. En tu archivo de usuario (~/.claude/settings.json) añade además:

{
  "permissions": { "disableBypassPermissionsMode": "disable" }
}

En el repositorio están todos los archivos de la herramienta:

Para probarla en tu equipo:

git clone https://github.com/carlosp5751258-lgtm/ctrlia-comprobador-settings
cd ctrlia-comprobador-settings
node pruebas.js        # → ok: comprobador

Y abre index.html en el navegador. Para entender cada regla a fondo, la receta de hooks de seguridad y la de MCP para programadores. Si además quieres un CLAUDE.md, usa el generador de CLAUDE.md. Fuentes: permisos, modos de permiso, ajustes, referencia de ajustes, sandbox, modo headless, seguridad y el CHANGELOG.

Preguntas frecuentes

¿Por qué Bash(python3 *) es peligroso si solo quiero ejecutar mis scripts?

Porque también aprueba python3 -c "…" con cualquier código. Escribe la regla con el argumento fijo: Bash(python3 -m pytest *) o Bash(python3 scripts/build.py).

Puse bypassPermissions en .claude/settings.json y no hace nada, ¿por qué?

Es lo documentado: desde ese archivo y desde settings.local.json no tiene efecto y la sesión arranca en Manual. Solo funciona desde ~/.claude/settings.json o la línea de comandos, y la doc lo limita a entornos aislados.

¿Un deny de Bash(curl *) bloquea internet?

No. La doc muestra que no para /usr/bin/curl ni sh -c 'curl …'. Para bloquear la red de verdad usa el sandbox con su lista de dominios.

¿Read(.env) protege mi .env de todo?

De las herramientas de Claude y de comandos como cat o sed, sí. De un script que abra el archivo por su cuenta, no: para eso, el sandbox.

¿Se envía mi archivo a algún servidor?

No. El análisis se hace en tu navegador. Aun así, borra las claves antes de pegar: no deberían estar en settings.json.

No me sale ningún aviso, ¿estoy seguro?

No necesariamente: la herramienta revisa el texto de las reglas, no tus hooks ni tus scripts, y mira un archivo a la vez. Comprueba también /permissions dentro de Claude Code.

Toda la biblioteca