@theoptimalpartner/npm-security-kit 1.0.0

package/README.md

@@ -0,0 +1,495 @@
+# 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)
+
+```bash
+# 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:
+
+```bash
+# Desde la raíz de tu proyecto
+bash /ruta/a/npm-security-kit/install.sh
+```
+
+### Opción 2: Instalación Manual (3 pasos)
+
+```bash
+# 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
+
+```json
+{
+  "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
+
+```bash
+# Verificar si un paquete es seguro
+npm run security:check-malicious
+
+# Ver info del paquete
+npm info paquete-nombre
+```
+
+### Después de Instalar Dependencias
+
+```bash
+# Verificación rápida
+npm run security:audit
+
+# Verificación completa (recomendado)
+npm run security:full
+```
+
+### Antes de Deploy
+
+```bash
+# 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`:
+
+```json
+{
+  "projectName": "mi-proyecto",
+  "projectType": "node",
+  "excludeDirs": ["node_modules", "dist", "build"],
+  "strictMode": true,
+  "notifications": {
+    "email": "security@tuempresa.com",
+    "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
+
+```bash
+npm run security:check-malicious
+```
+
+### 2. Auditoría Automática
+
+**npm audit mejorado**:
+- Verifica vulnerabilidades conocidas
+- Auto-fix cuando es posible
+- Reportes detallados
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# Re-ejecutar instalación (preserva config)
+bash /ruta/a/npm-security-kit/install.sh --update
+```
+
+---
+
+## 🎓 Mejores Prácticas
+
+### 1. Verificar Antes de Instalar
+
+```bash
+# ❌ 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
+
+```bash
+# 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
+
+1. **DETENER** - No desplegar ni ejecutar
+2. **AISLAR** - Marcar entorno como comprometido
+3. **ANALIZAR**:
+   ```bash
+   npm run security:check-malicious
+   npm list | grep nombre-paquete
+   git log package-lock.json
+   ```
+4. **REMOVER**:
+   ```bash
+   npm uninstall nombre-paquete
+   npm audit
+   npm run security:full
+   ```
+5. **INVESTIGAR**:
+   - Revisar logs de aplicación
+   - Verificar conexiones de red
+   - Buscar data exfiltration
+6. **REPORTAR**:
+   - Equipo de seguridad interno
+   - npm security (security@npmjs.com)
+   - Socket.dev (https://socket.dev/report)
+
+---
+
+## 🔧 Troubleshooting
+
+### Error: "jq command not found"
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# macOS
+brew install jq
+
+# Windows (WSL)
+sudo apt-get install jq
+```
+
+### Error: "Permission denied" en scripts
+
+```bash
+chmod +x scripts/*.sh
+```
+
+### GitHub Actions no ejecuta
+
+Verifica que `.github/workflows/security-audit.yml` esté commiteado:
+
+```bash
+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: security@npmjs.com
+- Socket.dev: https://socket.dev/report
+- GitHub Security: https://github.com/security
+
+---
+
+## 🤝 Contribuir
+
+### Agregar Paquetes a la Blacklist
+
+1. Verificar en múltiples fuentes (Socket.dev, Snyk, GitHub)
+2. Editar `.security/malicious-packages-blacklist.json`
+3. Agregar evidencia y referencias
+4. Pull request con documentación
+
+### Mejorar Scripts
+
+1. Fork del repositorio
+2. Crear rama con feature
+3. Probar en múltiples proyectos
+4. 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**: security@tuempresa.com
+- **Slack**: #security channel
+
+---
+
+**Versión**: 1.0.0
+**Última actualización**: 2025-10-20
+**Mantenedor**: Diego
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# 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.

package/bin/check.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+/**
+ * NPM Security Kit - Quick Check Tool
+ * Runs malicious package check in current project
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const targetDir = process.cwd();
+const checkScript = path.join(targetDir, 'scripts', 'check-malicious-packages.sh');
+
+// Check if scripts are installed
+if (!fs.existsSync(checkScript)) {
+  console.error('Error: NPM Security Kit not installed in this project');
+  console.error('Run: npx @yourorg/npm-security-kit install');
+  process.exit(1);
+}
+
+try {
+  // Execute check script
+  execSync(`bash "${checkScript}"`, {
+    stdio: 'inherit',
+    cwd: targetDir
+  });
+} catch (error) {
+  process.exit(error.status || 1);
+}

package/bin/install.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+/**
+ * NPM Security Kit - CLI Installation Tool
+ * Installs security infrastructure in any Node.js project
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const installScript = path.join(__dirname, 'install.sh');
+
+// Check if install.sh exists
+if (!fs.existsSync(installScript)) {
+  console.error('Error: install.sh not found');
+  process.exit(1);
+}
+
+// Get target directory from arguments or use current directory
+const targetDir = process.argv[2] || process.cwd();
+
+// Build command
+const args = process.argv.slice(2).join(' ');
+const command = `bash "${installScript}" ${args}`;
+
+try {
+  // Execute install script
+  execSync(command, {
+    stdio: 'inherit',
+    cwd: targetDir
+  });
+} catch (error) {
+  console.error('Installation failed:', error.message);
+  process.exit(1);
+}