tayyabt/trustlockUn controlador de admisión de dependencias nativo de Git. Evalúa señales de confianza en cada cambio de dependencia y bloquea commits o builds cuando los paquetes incumplen la política de tu equipo. Hook de pre-commit + puerta de CI con flujo de aprobación integrado.
Un controlador de admisión de dependencias nativo de Git. Evalúa señales de confianza en cada cambio de dependencia.
trustlock se ejecuta como un hook pre-commit de Git (modo consultivo) y una verificación de CI (modo forzado):
--enforce): bloquea en caso de infracciones, sale con 1, nunca avanza la línea base.Señales de confianza evaluadas por paquete:
npm install -g trustlock
Requiere Node.js >= 18.3.
| Archivo de bloqueo | Ecosistema | Versiones |
|---|---|---|
package-lock.json | npm | v1, v2, v3 |
pnpm-lock.yaml | pnpm | v5, v6, v9 |
yarn.lock | yarn | classic (v1), berry (v2/v3) |
requirements.txt | Python (pip) | — |
uv.lock | Python (uv) | — |
# 1. Inicializar trustlock en tu proyecto
trustlock init
# 2. Instalar el hook pre-commit de Git
trustlock install-hook
# 3. Opcionalmente revisar la postura actual de tus dependencias
trustlock audit
Después de init, trustlock crea:
.trustlockrc.json — configuración de políticas.trustlock/baseline.json — instantánea de dependencias de confianza.trustlock/approvals.json — registros de aprobaciones.trustlock/.cache/ — caché del registro (ignorado por git)Haz commit de .trustlockrc.json y .trustlock/baseline.json a tu repositorio.
# Ejecutar la instalación de dependencias como de costumbre
npm install [email protected]
# La verificación de trustlock se ejecuta automáticamente mediante el hook pre-commit.
# Para ejecutarla manualmente:
trustlock check
# Salida cuando todos los paquetes son admitidos:
# ✔ [email protected] — admitido
Cuando todos los paquetes pasan, trustlock check avanza la línea base automáticamente (solo en modo consultivo) y sale con 0.
# Un nuevo paquete falla la regla de enfriamiento:
trustlock check
# ✖ [email protected] — bloqueado
# exposure:cooldown Publicado hace 2h (la política requiere 72h)
# Ejecuta para aprobar: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d
# Aprobar la excepción y luego volver a verificar:
trustlock approve [email protected] \
--override cooldown \
--reason "Necesario para la funcionalidad X; verificado seguro por revisión del equipo" \
--expires 7d
trustlock check
# ✔ [email protected] — admitido con aprobación
# Detectar desviaciones de versiones e inconsistencias de procedencia en paquetes de monorepo
trustlock audit --compare packages/frontend packages/backend packages/shared
| Comando | Descripción |
|---|---|
trustlock init | Inicializar trustlock en el proyecto actual |
trustlock check | Evaluar cambios de dependencias contra la política |
trustlock approve <paquete>@<versión> | Aprobar un paquete bloqueado |
trustlock audit | Escanear todo el árbol de dependencias para evaluar la postura de confianza |
trustlock audit --compare <directorio...> | Comparar la postura de dependencias entre múltiples proyectos |
trustlock clean-approvals | Eliminar entradas de aprobación vencidas |
trustlock install-hook | Instalar el hook pre-commit de Git |
trustlock incluye dos perfiles integrados seleccionables con --profile:
| Perfil | Efecto |
|---|---|
strict | 168h de enfriamiento, se requiere procedencia para todos los paquetes |
relaxed | 24h de enfriamiento, no bloquea por regresión de procedencia o cambio de publicador |
# Usar perfil estricto en CI
trustlock check --enforce --profile strict
Los equipos pueden centralizar la política en una URL compartida y extenderla por repositorio:
{
"extends": "https://policy.example.com/trustlockrc.json",
"cooldown_hours": 96
}
Las configuraciones de repositorio solo pueden endurecer la política organizacional — la aplicación de un piso impide que los repositorios reduzcan los umbrales establecidos por la organización.
.trustlockrc.jsonAgrega trustlock a tu pipeline de CI:
# GitHub Actions — ver examples/ci/github-actions.yml
- run: npx trustlock check --enforce
Consulta examples/ para configuraciones de GitHub Actions, Lefthook y Husky.
##Dónde se ubica trustlock en la línea de tiempo
Trustlock evalúa los cambios en el archivo de bloqueo en el momento del commit. No intercepta ni aísla npm install. Si un paquete malicioso ejecuta un script postinstall, eso ocurre antes de que trustlock lo vea. Trustlock evita que el archivo de bloqueo comprometido sea confirmado y fusionado, limitando el radio de explosión a una sola máquina de desarrollador en lugar de a todo el equipo y la producción. Para el bloqueo de scripts en tiempo de instalación, usa --ignore-scripts o los controles predeterminados de ciclo de vida de pnpm.
--ignore-scripts para eso.npm audit o Snyk para bases de datos de vulnerabilidades.license-checker o similar.trustlock fue creado por la frustración con lo pasiva que es la cadena de herramientas estándar de Node.js respecto a lo que realmente se incorpora a un proyecto. npm install descargará cualquier cosa — un paquete publicado hace dos minutos, uno que ejecuta scripts arbitrarios en la instalación, uno que cambió de un tarball del registro a una URL de git de la noche a la mañana — y la única retroalimentación que recibes es un diff del archivo de bloqueo.
El modelo de amenazas que trustlock aborda es estrecho pero real: la ventana entre que se publica una versión maliciosa y es retirada o señalada. Los escáneres de vulnerabilidades operan después del hecho. trustlock opera en el punto de admisión, antes de que algo llegue a tu repositorio o a tu CI.
El diseño es intencionalmente mínimo. trustlock no tiene dependencias en tiempo de ejecución — es en sí mismo una herramienta de cero riesgo en la cadena de suministro. No reemplaza un escáner de vulnerabilidades ni una auditoría de dependencias; aplica continuidad de confianza. Una vez que una versión está en tu línea base, es confiable. Cualquier cosa nueva debe ganarse la admisión contra la política que declaras.
El flujo de trabajo de aprobación existe para equipos que necesitan una salida de emergencia sin perder auditabilidad. Cada excepción tiene marca de tiempo, está limitada a reglas específicas y expira. clean-approvals es un comando de primera clase, no una ocurrencia tardía.