@theoptimalpartner/npm-security-kit

v1.0.2

Published

5 months ago

Portable security kit to protect Node.js/npm projects against malicious packages and vulnerabilities

Downloads

0High
0Medium
0Low

security npm malicious-packages supply-chain vulnerability audit phishing typosquatting socket.dev dependabot github-actions

NPM Security Kit 🛡️

Protección instant contra paquetes maliciosos y vulnerabilidades

Kit portable y reutilizable para proteger cualquier proyecto Node.js/npm contra:

✅ 175+ paquetes maliciosos conocidos (campaña de phishing Oct 2025)
✅ Vulnerabilidades en dependencias
✅ Supply chain attacks
✅ Typosquatting
✅ Malware en dependencias transitivas

🚀 Instalación Rápida (2 minutos)

Opción 1: Instalación Automática (Recomendado)

# Desde la raíz de tu proyecto
curl -sSL https://raw.githubusercontent.com/tu-org/npm-security-kit/main/install.sh | bash

O si tienes el kit localmente:

# Desde la raíz de tu proyecto
bash /ruta/a/npm-security-kit/install.sh

Opción 2: Instalación Manual (3 pasos)

# 1. Copiar archivos de seguridad
cp -r /ruta/a/npm-security-kit/template/.security .
cp -r /ruta/a/npm-security-kit/template/scripts .
cp -r /ruta/a/npm-security-kit/template/.github .

# 2. Hacer scripts ejecutables
chmod +x scripts/*.sh

# 3. Agregar scripts a package.json
# Ver sección "Scripts NPM" más abajo

📦 ¿Qué Incluye?

Archivos Instalados

tu-proyecto/
├── .github/
│   ├── workflows/
│   │   └── security-audit.yml       # GitHub Actions automático
│   └── dependabot.yml               # Actualizaciones automáticas
├── .security/
│   ├── malicious-packages-blacklist.json  # 175+ paquetes maliciosos
│   └── config.json                  # Configuración personalizable
├── scripts/
│   ├── check-malicious-packages.sh  # Verificar paquetes maliciosos
│   └── security-check.sh            # Auditoría completa
└── SECURITY.md                      # Documentación

Scripts NPM Agregados

{
  "scripts": {
    "security:check": "./scripts/security-check.sh",
    "security:check-malicious": "./scripts/check-malicious-packages.sh",
    "security:audit": "npm audit --audit-level=moderate",
    "security:audit:fix": "npm audit fix",
    "security:outdated": "npm outdated",
    "security:licenses": "npm list --json | jq -r '.dependencies | to_entries[] | \"\\(.key): \\(.value.license)\"'",
    "security:full": "npm run security:audit && npm run security:check"
  }
}

🎯 Uso Diario

Antes de Instalar un Paquete

# Verificar si un paquete es seguro
npm run security:check-malicious

# Ver info del paquete
npm info paquete-nombre

Después de Instalar Dependencias

# Verificación rápida
npm run security:audit

# Verificación completa (recomendado)
npm run security:full

Antes de Deploy

# Auditoría completa
npm run security:full

# Si hay problemas, auto-fix
npm run security:audit:fix

⚙️ Configuración

Personalizar para tu Proyecto

Edita .security/config.json:

{
  "projectName": "mi-proyecto",
  "projectType": "node",
  "excludeDirs": ["node_modules", "dist", "build"],
  "strictMode": true,
  "notifications": {
    "email": "[email protected]",
    "slack": "https://hooks.slack.com/..."
  }
}

Tipos de Proyecto Soportados

node - Proyectos Node.js backend
react - Aplicaciones React
nextjs - Aplicaciones Next.js
vue - Aplicaciones Vue.js
express - APIs Express
serverless - Funciones serverless
library - Librerías npm

🔒 Características

1. Verificación de Paquetes Maliciosos

Blacklist de 175+ paquetes conocidos:

Campaña de phishing Oct 2025
Patrones maliciosos (redirect-*)
Dominios de phishing
Cuentas npm comprometidas

npm run security:check-malicious

2. Auditoría Automática

npm audit mejorado:

Verifica vulnerabilidades conocidas
Auto-fix cuando es posible
Reportes detallados

npm run security:audit

3. GitHub Actions

Verificación en cada PR/Push:

✅ npm audit
✅ Paquetes maliciosos
✅ Dependency review
✅ License compliance
✅ Secrets detection

Ejecución semanal automática (Lunes 9am UTC)

4. Dependabot

Actualizaciones automáticas:

Security patches prioritarios
Agrupación inteligente
PRs con contexto

5. Pre-commit Hooks (Opcional)

Instalar con Husky:

npm install --save-dev husky
npx husky init
echo "npm run security:check-malicious" > .husky/pre-commit

📊 Ejemplos de Salida

✅ Proyecto Limpio

========================================
Malicious Package Detection
========================================

Loading blacklist...
✓ Loaded 175 malicious packages
  Source: Socket.dev - 175 Malicious npm Packages...
  Last Updated: 2025-10-20

Analyzing installed packages...
  Total installed packages: 342

Checking against blacklist...

Checking against malicious patterns...

========================================
Results
========================================
✓ No malicious packages detected

Summary:
  - Checked: 342 packages
  - Against: 175 known malicious packages
  - Found: 0 threats

❌ Amenaza Detectada

========================================
Results
========================================
✗ MALICIOUS PACKAGES FOUND!

Summary:
  - Direct matches: 1
  - Pattern matches: 0
  - Total threats: 1

Malicious packages found:
  - redirect-abc123 (direct match)

IMMEDIATE ACTIONS REQUIRED:
1. DO NOT use this application
2. Uninstall malicious packages immediately
3. Review application logs for suspicious activity
4. Check for data exfiltration
5. Report to security team

🔄 Actualización

Actualizar Blacklist

# Descargar última blacklist
curl -o .security/malicious-packages-blacklist.json \
  https://raw.githubusercontent.com/tu-org/npm-security-kit/main/blacklist.json

# Verificar
npm run security:check-malicious

Actualizar Scripts

# Re-ejecutar instalación (preserva config)
bash /ruta/a/npm-security-kit/install.sh --update

🎓 Mejores Prácticas

1. Verificar Antes de Instalar

# ❌ NO HACER
npm install paquete-random

# ✅ HACER
npm info paquete-random
npm view paquete-random repository
npm view paquete-random license
npm install paquete-random
npm run security:check-malicious

2. Mantener Dependencias Actualizadas

# Ver paquetes desactualizados
npm run security:outdated

# Actualizar con cuidado
npm update
npm run security:full

3. Revisar Dependabot PRs

✅ Priorizar PRs de seguridad
✅ Leer changelog antes de aprobar
✅ Probar en staging primero

4. Auditorías Regulares

| Frecuencia | Acción | Comando | |------------|--------|---------| | Diario | Revisar Dependabot PRs | GitHub UI | | Semanal | GitHub Actions (automático) | - | | Mensual | Auditoría manual completa | npm run security:full | | Trimestral | Actualizar blacklist | Ver sección Actualización |

🚨 Respuesta a Incidentes

Si se Detecta un Paquete Malicioso

DETENER - No desplegar ni ejecutar
AISLAR - Marcar entorno como comprometido

ANALIZAR:

npm run security:check-malicious
npm list | grep nombre-paquete
git log package-lock.json

REMOVER:

npm uninstall nombre-paquete
npm audit
npm run security:full

INVESTIGAR:
- Revisar logs de aplicación
- Verificar conexiones de red
- Buscar data exfiltration
REPORTAR:
- Equipo de seguridad interno
- npm security ([email protected])
- Socket.dev (https://socket.dev/report)

🔧 Troubleshooting

Error: "jq command not found"

# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

# Windows (WSL)
sudo apt-get install jq

Error: "Permission denied" en scripts

chmod +x scripts/*.sh

GitHub Actions no ejecuta

Verifica que .github/workflows/security-audit.yml esté commiteado:

git add .github/workflows/security-audit.yml
git commit -m "chore: add security audit workflow"
git push

Dependabot no abre PRs

Verifica en GitHub Settings > Security > Dependabot que esté habilitado.

📚 Recursos

Documentación Adicional

SECURITY_PROTOCOL.md - Protocolo completo (en auth-service)
SECURITY_AUDIT_REPORT.md - Ejemplo de informe
SECURITY_QUICK_GUIDE.md - Guía rápida

Enlaces Útiles

Socket.dev Blog: https://socket.dev/blog
npm Security: https://docs.npmjs.com/security
OWASP Dependency Check: https://owasp.org/www-community/Component_Analysis
Snyk Advisor: https://snyk.io/advisor

Reportar Vulnerabilidades

NPM Security: [email protected]
Socket.dev: https://socket.dev/report
GitHub Security: https://github.com/security

🤝 Contribuir

Agregar Paquetes a la Blacklist

Verificar en múltiples fuentes (Socket.dev, Snyk, GitHub)
Editar .security/malicious-packages-blacklist.json
Agregar evidencia y referencias
Pull request con documentación

Mejorar Scripts

Fork del repositorio
Crear rama con feature
Probar en múltiples proyectos
PR con tests y documentación

📄 Licencia

MIT License - Úsalo libremente en proyectos comerciales y open source

⭐ Proyectos Usando Este Kit

auth-service
jwt-auth-package
auth-react-client

¿Usas este kit? Agrega tu proyecto aquí!

🎯 Roadmap

[ ] npm package instalable (npm install -D @tuorg/security-kit)
[ ] Integración con más CI/CD (GitLab, Bitbucket, CircleCI)
[ ] Dashboard web de métricas
[ ] Integración con Slack/Discord
[ ] Soporte para Python/pip, Ruby/gems, etc.
[ ] Machine learning para detectar patrones

📞 Soporte

Issues: GitHub Issues
Discusiones: GitHub Discussions
Email: [email protected]
Slack: #security channel

Versión: 1.0.0 Última actualización: 2025-10-20 Mantenedor: Diego

🚀 Quick Start

# 1. Clonar o descargar el kit
git clone https://github.com/tu-org/npm-security-kit

# 2. Ir a tu proyecto
cd mi-proyecto

# 3. Ejecutar instalación
bash /ruta/a/npm-security-kit/install.sh

# 4. Verificar
npm run security:check-malicious

# 5. ¡Listo! Tu proyecto está protegido

¿Preguntas? Lee la documentación completa o abre un issue.