trustlock

Un controlador de admisión de dependencias nativo de Git. Evalúa señales de confianza en cada cambio de dependencia.

Cómo funciona

trustlock se ejecuta como un hook pre-commit de Git (modo consultivo) y una verificación de CI (modo forzado):

• Consultivo (pre-commit): advierte sobre infracciones, sale con 0, y avanza la línea base de confianza cuando todos los paquetes son admitidos.
• Forzado (--enforce): bloquea en caso de infracciones, sale con 1, nunca avanza la línea base.

Señales de confianza evaluadas por paquete:

• Enfriamiento — cuánto tiempo ha pasado desde que la versión fue publicada en el registro
• Procedencia — si el paquete tiene atestaciones SLSA
• Fijación — si el archivo de bloqueo usa versiones exactas
• Scripts de instalación — si el paquete ejecuta scripts en el momento de la instalación
• Fuentes — si el paquete proviene del registro, una URL de git, una ruta local o una URL
• Nuevas dependencias — primeras incorporaciones al proyecto
• Sorpresa transitiva — salto inesperado en el recuento de dependencias transitivas
• Cambio de publicador — si la identidad del publicador del paquete cambió entre versiones

Instalación

npm install -g trustlock

Requiere Node.js >= 18.3.

Archivos de bloqueo compatibles

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)	—

Inicio rápido

Flujo de trabajo 1 — Incorporación de un proyecto

# 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.

Flujo de trabajo 2 — Verificar y admitir una actualización de dependencia

# 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.

Flujo de trabajo 3 — Manejar una dependencia bloqueada

# 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

Flujo de trabajo 4 — Comparar la postura de dependencias entre proyectos

# Detectar desviaciones de versiones e inconsistencias de procedencia en paquetes de monorepo
trustlock audit --compare packages/frontend packages/backend packages/shared

Comandos

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

Perfiles de política

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

Herencia de políticas organizacionales

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.

Documentación

• USAGE.md — Referencia completa de comandos, todas las banderas, códigos de salida, mensajes de error
• POLICY-REFERENCE.md — Cada opción de .trustlockrc.json
• ARCHITECTURE.md — Decisiones de diseño y mapa de módulos
• examples/ — Ejemplos de configuración y flujos de CI

Integración con CI

Agrega 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.

Lo que trustlock NO hace

• No es un escáner de malware — trustlock no inspecciona el código fuente de los paquetes ni detecta firmas maliciosas conocidas. Usa un escáner dedicado para eso.
• No es un entorno aislado en tiempo de instalación — trustlock no intercepta npm install. Usa --ignore-scripts para eso.
• No es un rastreador de CVEs — usa npm audit o Snyk para bases de datos de vulnerabilidades.
• No es un verificador de licencias — usa license-checker o similar.
• No reemplaza trustPolicy de pnpm o min-release-age de npm — esos son controles del lado del servidor aplicados por el registro. trustlock es una puerta de admisión del lado del cliente en el límite del repositorio.

Acerca de