Contenidos

• Primeros pasos — de cero a instalado en unos cinco minutos
• Qué hace
• Qué lo activa
• Qué hay en este repositorio
• Ecosistemas compatibles
• Instalación
  • Configuración
  • Cambiar el período de enfriamiento
• Niveles de advertencia
• Cómo funciona
  • Modo Normal (Manual)
  • Modo Intercepción (Automático)
  • Modo Pre-Instalación (Hook de Bash)
  • Modo Post-Instalación (Hook de Bash)
  • Modo Post-Agente (Par de Hooks de Agente)
• Registro de auditoría
• Requisitos
• FAQ

Primeros pasos

GETTING-STARTED.md te lleva de cero a una instalación funcional en unos cinco minutos — requisitos previos, la instalación interactiva y la verificación. Para la referencia completa de instalación (instalaciones globales/de proyecto/manuales, detalles de Windows, la lista de permisos permitidos, actualización y desinstalación), consulta INSTALLATION.md.

Uso diario: una vez instalados los hooks, no hay nada que ejecutar — safer-dependencies funciona automáticamente en segundo plano. Cuando Claude añade o instala paquetes, marca las dependencias arriesgadas y actualiza las versiones vulnerables a una segura en el mismo lugar — y bloquea una instalación conocidamente vulnerable antes de que siquiera se ejecute — de modo que los paquetes inseguros se detectan y corrigen sin que tengas que pedirlo. Aun así puedes invocarlo directamente en cualquier momento: "¿es seguro [email protected]?", "comprueba la configuración de safer-dependencies" o "muestra las estadísticas de safer-dependencies".

Qué hace

Cuando Claude está a punto de añadir un paquete a tu proyecto, safer-dependencies lo intercepta y ejecuta 5 comprobaciones:

1. Procedencia — registro oficial, detección de typosquats (npm/PyPI/RubyGems/Maven/crates.io), antigüedad del paquete
2. Antigüedad de la versión — elige la versión estable más reciente publicada hace 7+ días (ventana de enfriamiento)
3. Escaneo de vulnerabilidades — API de OSV, con herramientas nativas del ecosistema (npm audit, pip-audit, bundle audit) cuando están disponibles
4. Integridad del pin de hash — para líneas de requirements.txt de PyPI con pines --hash=sha256:..., el hash declarado se valida contra los hashes publicados por PyPI; una discrepancia emite una ADVERTENCIA
5. Paquetes abandonados y obsoletos — los paquetes conocidamente abandonados (p. ej. paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) se bloquean de inmediato con una alternativa sugerida; los paquetes sin lanzamiento estable en 2+ años reciben una advertencia informativa STALE:. Los paquetes bloqueados se eliminan del manifiesto y Claude preguntará cómo proceder; los paquetes solo obsoletos se dejan en su lugar.

Si se encuentran problemas, Claude emite advertencias y puede retroceder a una versión más segura. Todas las comprobaciones se registran en ~/.claude/safer-dependencies-audit-YYYY-MM.log (un archivo por mes calendario).

Qué lo activa

La skill se activa automáticamente cuando Claude:

Operaciones de manifiesto / instalación

• Añade o actualiza un paquete en package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod o cualquier otro manifiesto compatible
• Escribe un import, require o use para un paquete aún no declarado en el manifiesto
• Genera o actualiza un archivo de bloqueo (comprueba solo las entradas nuevas/cambiadas)
• Ejecuta una instalación del gestor de paquetes vía Bash (npm install, bundle install, poetry install, uv sync, go mod tidy, etc.) — Pre-Instalación audita los argumentos del comando, Post-Instalación audita el archivo de bloqueo resultante
• Escribe un Dockerfile o un flujo de trabajo de CI (.github/workflows/*.yml, etc.) que incorpore pasos de instalación del gestor de paquetes con versiones fijadas

Preguntas de selección y recomendación

• Comparaciones de bibliotecas/frameworks: "¿debería usar axios o node-fetch?", "¿moment vs dayjs?", "¿cuál es mejor X o Y?"
• Solicitudes de recomendación: "¿cuál es un buen cliente HTTP para Python?", "recomienda una biblioteca de registro para Go", "¿qué paquete maneja CSV en Node?"
• Selección de versión: "¿qué versión de Django debería usar?", "¿última versión estable de Flask?"

Expresiones de intención de uso (pre-adición)

• "Quiero usar FastAPI para esto", "estoy pensando en añadir Celery", "estamos considerando Prisma como ORM", "usemos Tailwind"

Preguntas sobre salud y confianza de paquetes

• "¿Sigue mantenido moment.js?", "¿sigue activa esta gema?", "¿está abandonado X?", "¿está X en fin de vida (EOL)?", "¿puedo confiar en este paquete?", "¿cuándo se actualizó faker por última vez?"

Comandos de scaffolding

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, "inicializar un nuevo proyecto FastAPI"

Adiciones implícitas de paquetes (solicitudes de funciones que implican una nueva dependencia)

• "Añade caché de Redis a la aplicación", "conéctate a Postgres", "añade autenticación JWT", "escribe código para enviar correos" — se activa cuando no hay ningún paquete para esa capacidad ya en el manifiesto

Migración y portabilidad

• "Migra de requests a httpx", "pasa de CRA a Vite", "porta de moment a date-fns" — audita el paquete entrante

No se activa para:

• Importaciones de la biblioteca estándar (os, fs, java.util.*, etc.)
• Dependencias ya declaradas que no se están modificando
• Discusión académica sobre cómo funciona un paquete internamente ("explica el reconciler de React", "¿cómo funciona la resolución de módulos de webpack?") — las preguntas de comparación y selección sí se activan
• Instalación de aplicaciones a nivel de sistema operativo, runtimes o extensiones de IDE (el propio Python, Docker, Homebrew, extensiones de VS Code)

Qué hay en este repositorio

Este es un paquete de skill + hooks, no un único archivo de skill. Una instalación completa despliega estas piezas:

El archivo de skill por sí solo no es suficiente — sin hooks, la invocación automática depende de que Claude decida recurrir a la skill. Instala las cinco piezas para una cobertura completa; muchas skills y comandos de barra despachan subagentes internamente, por lo que el par Post-Agente importa incluso si nunca generas uno explícitamente. (Consulta FAQ.md para saber por qué una skill por sí sola no puede garantizar la cobertura.)

Ecosistemas compatibles

Instalación

¿Nuevo en el proyecto? Empieza con GETTING-STARTED.md. La versión corta:```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

Los mismos verbos funcionan fuera de una sesión de Claude:```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

El agente padre utiliza estas señales para identificar el código afectado y refactorizarlo según sea necesario.

Modo Pre-Instalación (Hook de Bash)

Configura .claude/settings.json con un hook PreToolUse:Bash para habilitar la auditoría previa al vuelo de los comandos de instalación del gestor de paquetes. Esto complementa (no reemplaza) el Modo Interceptación — juntos forman una defensa en capas.

1. Claude intenta una llamada a la herramienta Bash (p. ej. npm install [email protected])
2. El hook PreToolUse se dispara antes de que se ejecute la llamada e invoca safer-dependencies-pretooluse-bash.sh
3. Un filtro temprano en bash puro cortocircuita los comandos que no son de gestor de paquetes en ~115 ms (sin invocación de Python), por lo que git status / ls / npm test pagan un coste insignificante en la ruta crítica
4. Para instalaciones reconocidas de gestores de paquetes (npm/pnpm/yarn install/i/add), el helper tokeniza mediante shlex, extrae cada argumento pkg@version y lo envía por POST a OSV
5. Cualquier pin concreto vulnerable → el hook devuelve permissionDecision: "deny" con un GHSA-id por hallazgo + CVSS + resumen, más una pista para invocar la skill safer-dependencies
6. La instalación nunca se ejecuta — sin fetch de red, sin scripts postinstall

Por qué existe además del Modo Interceptación: el shim posterior a la escritura es ciego a Bash. npm install [email protected] se ejecuta hasta el final (y los scripts postinstall se ejecutan) antes de que se dispare cualquier auditoría; npm install -g typosquat-pkg no escribe ningún manifiesto de proyecto. El Modo Pre-Instalación cierra esas brechas estructuralmente.

El Modo Pre-Instalación solo ve lo que el usuario escribió (argumentos pkg@version en la línea de comandos). No puede ver el árbol transitivo que el resolvedor instalará realmente. El Modo Post-Instalación (abajo) audita el lockfile una vez que la instalación se completa — los dos modos son complementarios, no redundantes.

Alcance: las CLI de gestores de paquetes cubiertas aquí abarcan cinco ecosistemas (npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle, go, cargo), además de Maven mediante el Modo Interceptación (las dependencias de Maven normalmente se declaran en pom.xml/build.gradle, no se añaden mediante un verbo de CLI).

Brecha conocida: la CLI de Maven sí admite descargas directas mediante mvn dependency:get -Dartifact=group:art:version y mvn dependency:copy. Este hook aún no reconoce esas invocaciones. Si las usas con regularidad, el shim posterior a la escritura existente sigue capturando lo que llegue a tu manifiesto, pero la protección previa al fetch solo se aplica a los ecosistemas listados arriba. Se registra como seguimiento.

Sintaxis reconocida por ecosistema:

Los pines de rango (npm ^4.17, pip >=, poetry ^/~, Go @latest) y las versiones no especificadas pasan al Modo Interceptación después de la instalación — el shim posterior a la escritura audita lo que el resolvedor elija. La reescritura automática a una versión segura está en cola como seguimiento.

Modo de fallo: fail-open. Cualquier error (Python ausente, fallo de red, entrada malformada) sale con 0 y sin salida, permitiendo que bash continúe. El Modo Interceptación sigue ejecutándose después de la instalación, por lo que un fallo previo al vuelo degrada con elegancia a la protección existente.

Ejemplo de denegación:``` safer-dependencies pre-flight audit blocked this install. Vulnerable pinned version(s) detected:

• [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash Re-run with a patched version, or invoke the safer-dependencies skill for a recommended pin.

Modo Post-Agente (Par de Hooks de Agente)

Los cuatro modos anteriores solo se activan para llamadas a herramientas de la sesión raíz. Cuando la sesión raíz despacha un subagente (a través de la herramienta Agent — muchas skills y comandos de barra hacen esto internamente), las llamadas Write/Edit/Bash del subagente omiten todos ellos. El Modo Post-Agente es la red de seguridad reactiva para esa brecha.

1. Un hook PreToolUse:Agent (safer-dependencies-pretooluse-agent.sh) se ejecuta inmediatamente antes de cada despacho de Agent y toca un archivo centinela en /tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel (con respaldo a un nombre solo con PPID cuando no hay id de sesión disponible)
2. El subagente se ejecuta y puede escribir manifests o lockfiles
3. Un hook PostToolUse:Agent (safer-dependencies-posttooluse-agent.sh) se ejecuta después de que la llamada de Agent retorna, hace find de cada manifest y lockfile más reciente que el centinela, y audita cada uno a través de la misma ruta del shim
4. Los hallazgos aparecen como additionalContext en el siguiente turno de la sesión raíz; el centinela se elimina

Los subagentes anidados se cubren automáticamente — el PostToolUse:Agent de la raíz solo se activa después de que todo el trabajo del agente externo (incluyendo cualquier cosa que él haya despachado) esté en disco. La única brecha es una instalación global que no escribe ningún manifest ni lockfile (npm install -g …): no hay nada que escanear. Como los otros hooks, falla abierto — cualquier error (centinela faltante, shim faltante, payload ilegible) sale con 0 silenciosamente. El fundamento completo del diseño está en skills/safer-dependencies.md.

Registro de auditoría

Cada comprobación se registra en ~/.claude/safer-dependencies-audit-YYYY-MM.log (un archivo por mes calendario, donde YYYY-MM es el año-mes UTC) como una sola línea JSON. Sobrescribe la ruta completa con la variable de entorno SAFE_DEP_AUDIT_LOG (cuando se establece, el sufijo de fecha no se añade). Los archivos también se rotan por tamaño cuando superan SAFE_DEP_LOG_MAX_BYTES (por defecto 10 MiB; establece en 0 para deshabilitar). Establece SAFE_DEP_MODEL para sobrescribir el valor del modelo escrito en source.model en cada entrada — útil para comparaciones A/B entre versiones de modelos.

Los cinco modos añaden al mismo archivo. Cada entrada lleva un bloque source (esquema 2.2) que identifica qué componente lo escribió:

source.model registra el modelo de Claude Code activo en la sesión (p. ej. "claude-sonnet-4-6"). Presente en el esquema 2.1+; las entradas escritas por instalaciones más antiguas omiten el campo. El comando de estadísticas degrada con elegancia a "unknown" cuando está ausente.

Filtra por source.component con jq:```bash jq -r '.source.component' audit.log | sort | uniq -c | sort -rn jq -c 'select(.source.component == "bash.pretooluse")' audit.log

Surface every silent fail-open across all hooks:

jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log

Esto proporciona resúmenes legibles por humanos de la actividad, el impacto en la seguridad y las métricas de rendimiento extraídas de estos registros de auditoría.

Formas de entrada (esquema 2.2). Tres formas distintas comparten el mismo encabezado ts / schema / source:

Entradas de auditoría: El modo de intercepción ejecuta el pipeline completo (procedencia, antigüedad de versión, OSV, abandonado/obsoleto, typosquat, firmas), por lo que todos los arrays pueden poblarse. El modo de preinstalación ejecuta solo OSV hoy en día, por lo que abandoned / stale / typosquat / signatures siempre están vacíos. El envío posterior a la instalación (auditoría de lockfile) escribe bajo shim.posttooluse con findings poblado por cadenas WARNING: de los auditores de lockfile. El array notes transporta señales informativas NOTE: (p. ej., manifiesto omitido porque no está fijado).

El esquema 2.2 añadió — de forma aditiva — cuatro campos a las entradas de auditoría de lockfile: lockfile, manifest_ref, relation_summary (una clasificación directa/transitiva/desconocida de cada paquete marcado frente al manifiesto hermano) y un bloque policy que registra el nivel transitive en vigor. El cambio es compatible con versiones anteriores: los lectores de entradas 2.1 toleran los nuevos campos, y el campo source.model permanece presente desde 2.1 en adelante.```json { "ts": "2026-04-19T12:34:56Z", "schema": "2.2", "source": { "component": "shim.posttooluse", "script": "shim.sh", "hook": "PostToolUse:Write", "tool": "Write", "mode": "intercept", "model": "claude-sonnet-4-6" }, "file": "/path/to/project/package.json", "ecosystem": "npm", "checked": ["[email protected]", "[email protected]"], "findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"], "abandoned": [], "stale": [], "typosquat": [], "unknown": [], "signatures": [], "notes": [], "clean": ["[email protected]"] }

Fail-open Mode example (Post-Install Bash hook called with no shim adjacent — broken install):```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }