@theoptimalpartner/npm-security-kit 1.0.0

package/EXAMPLES.md

@@ -0,0 +1,528 @@
+# Ejemplos de Uso - NPM Security Kit
+
+## Escenarios Reales
+
+---
+
+## Ejemplo 1: Proyecto Express API (Existente)
+
+### Situación
+Tienes una API Express en producción con 150 dependencias. Quieres agregar protección de seguridad.
+
+### Solución
+
+```bash
+# 1. Navegar al proyecto
+cd /ruta/a/mi-api-express
+
+# 2. Instalar security kit
+bash /home/diego/projects/npm-security-kit/install.sh
+
+# 3. Verificar estado actual
+npm run security:full
+```
+
+**Resultado esperado**:
+```
+========================================
+Security Audit Script
+========================================
+
+1. Checking package-lock.json...
+✓ package-lock.json exists
+
+2. Running npm audit...
+found 2 moderate vulnerabilities
+
+3. Checking for outdated packages...
+Package        Current  Wanted  Latest
+express        4.17.1   4.18.2  4.19.0
+jsonwebtoken   8.5.1    8.5.1   9.0.2
+
+4. Checking for install scripts...
+⚠ Install scripts detected - review manually
+
+5. Checking for hardcoded secrets...
+✓ No hardcoded secrets detected
+
+...
+
+9. Checking for known malicious packages...
+✓ No known malicious packages detected
+
+Summary:
+  Errors: 0
+  Warnings: 2
+```
+
+### Acciones
+
+```bash
+# Arreglar vulnerabilidades
+npm run security:audit:fix
+
+# Actualizar paquetes desactualizados
+npm update express jsonwebtoken
+
+# Verificar de nuevo
+npm run security:full
+```
+
+---
+
+## Ejemplo 2: Nueva App React (Desde Cero)
+
+### Situación
+Inicias una nueva aplicación React y quieres seguridad desde el día 1.
+
+### Solución
+
+```bash
+# 1. Crear proyecto con Vite
+npm create vite@latest mi-app-react -- --template react-ts
+cd mi-app-react
+
+# 2. Instalar security kit ANTES de instalar dependencias
+bash /home/diego/projects/npm-security-kit/install.sh
+
+# 3. Ahora instalar dependencias
+npm install
+
+# 4. Verificar que todo esté limpio
+npm run security:check-malicious
+```
+
+**Resultado**:
+```
+✓ No malicious packages detected
+Summary:
+  - Checked: 342 packages
+  - Against: 175 known malicious packages
+  - Found: 0 threats
+```
+
+### Workflow de desarrollo
+
+```bash
+# Cada vez que instales algo
+npm install axios
+npm run security:check-malicious
+
+# Antes de commit
+npm run security:full
+git add .
+git commit -m "feat: add axios for API calls"
+
+# GitHub Actions verificará automáticamente en el push
+```
+
+---
+
+## Ejemplo 3: Monorepo con Múltiples Proyectos
+
+### Situación
+Tienes un monorepo con varios paquetes (frontend, backend, shared).
+
+### Solución
+
+```bash
+# Estructura
+monorepo/
+├── packages/
+│   ├── frontend/
+│   ├── backend/
+│   └── shared/
+└── package.json
+
+# Instalar en cada paquete
+cd packages/frontend
+bash /home/diego/projects/npm-security-kit/install.sh
+
+cd ../backend
+bash /home/diego/projects/npm-security-kit/install.sh
+
+cd ../shared
+bash /home/diego/projects/npm-security-kit/install.sh
+
+# Script global en raíz (package.json)
+{
+  "scripts": {
+    "security:check-all": "npm run security:check --workspaces"
+  }
+}
+```
+
+---
+
+## Ejemplo 4: CI/CD con GitLab
+
+### Situación
+Usas GitLab CI en lugar de GitHub Actions.
+
+### Solución
+
+Crear `.gitlab-ci.yml`:
+
+```yaml
+security-audit:
+  stage: test
+  image: node:18
+  before_script:
+    - apt-get update && apt-get install -y jq
+    - npm ci
+  script:
+    - npm run security:check-malicious
+    - npm run security:audit
+  only:
+    - merge_requests
+    - main
+  allow_failure: false
+
+weekly-security-scan:
+  stage: test
+  image: node:18
+  before_script:
+    - apt-get update && apt-get install -y jq
+    - npm ci
+  script:
+    - npm run security:full
+  only:
+    - schedules
+  allow_failure: false
+```
+
+---
+
+## Ejemplo 5: Proyecto con Paquete Malicioso Detectado
+
+### Situación
+Instalaste un paquete que resultó ser malicioso.
+
+### Detección
+
+```bash
+npm install some-suspicious-package
+npm run security:check-malicious
+```
+
+**Resultado**:
+```
+✗ MALICIOUS PACKAGES FOUND!
+
+Malicious packages found:
+  - some-suspicious-package (direct match)
+
+IMMEDIATE ACTIONS REQUIRED:
+1. DO NOT use this application
+2. Uninstall malicious packages immediately
+3. Review application logs
+4. Check for data exfiltration
+5. Report to security team
+```
+
+### Respuesta
+
+```bash
+# 1. Desinstalar inmediatamente
+npm uninstall some-suspicious-package
+
+# 2. Revisar logs
+git log package-lock.json
+
+# 3. Verificar si se ejecutó código malicioso
+npm run security:full
+
+# 4. Limpiar node_modules
+rm -rf node_modules package-lock.json
+npm install
+
+# 5. Verificar de nuevo
+npm run security:check-malicious
+```
+
+---
+
+## Ejemplo 6: Actualización de Blacklist
+
+### Situación
+Socket.dev reporta nuevos paquetes maliciosos y quieres actualizar.
+
+### Solución
+
+```bash
+# 1. Descargar blacklist actualizada
+curl -o .security/malicious-packages-blacklist.json \
+  https://url-to-updated-blacklist.json
+
+# 2. Verificar tu proyecto
+npm run security:check-malicious
+
+# 3. Si encuentras problemas, actúa
+npm run security:full
+
+# 4. Propagar a otros proyectos
+for project in proyecto1 proyecto2 proyecto3; do
+  cp .security/malicious-packages-blacklist.json ../$project/.security/
+  (cd ../$project && npm run security:check-malicious)
+done
+```
+
+---
+
+## Ejemplo 7: Pre-commit Hook
+
+### Situación
+Quieres bloquear commits si hay paquetes maliciosos.
+
+### Solución
+
+```bash
+# 1. Instalar Husky
+npm install --save-dev husky
+npx husky init
+
+# 2. Crear pre-commit hook
+cat > .husky/pre-commit <<'EOF'
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+echo "🔒 Running security checks..."
+
+# Check for malicious packages
+npm run security:check-malicious || {
+  echo "❌ Security check failed!"
+  echo "Run 'npm run security:check-malicious' for details"
+  exit 1
+}
+
+echo "✅ Security checks passed"
+EOF
+
+chmod +x .husky/pre-commit
+
+# 3. Probar
+git add .
+git commit -m "test"
+```
+
+**Si hay problema**:
+```
+🔒 Running security checks...
+✗ MALICIOUS PACKAGES FOUND!
+❌ Security check failed!
+```
+
+**Commit bloqueado hasta resolver**
+
+---
+
+## Ejemplo 8: Integración con Slack
+
+### Situación
+Quieres notificaciones en Slack cuando se detectan problemas.
+
+### Solución
+
+Editar `.security/config.json`:
+
+```json
+{
+  "notifications": {
+    "enabled": true,
+    "channels": {
+      "slack": {
+        "enabled": true,
+        "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
+      }
+    }
+  }
+}
+```
+
+Modificar `scripts/check-malicious-packages.sh` (al final):
+
+```bash
+# Si se encuentran amenazas, notificar Slack
+if [ $FOUND_MALICIOUS -gt 0 ]; then
+  WEBHOOK=$(jq -r '.notifications.channels.slack.webhook' .security/config.json)
+  if [ "$WEBHOOK" != "null" ] && [ -n "$WEBHOOK" ]; then
+    curl -X POST -H 'Content-type: application/json' \
+      --data "{\"text\":\"🚨 SECURITY ALERT: Malicious packages detected in $(pwd)\"}" \
+      "$WEBHOOK"
+  fi
+fi
+```
+
+---
+
+## Ejemplo 9: Proyecto Serverless (AWS Lambda)
+
+### Situación
+Despliegas funciones Lambda y quieres asegurar dependencias.
+
+### Solución
+
+```bash
+# 1. En tu proyecto serverless
+cd mi-proyecto-serverless
+bash /home/diego/projects/npm-security-kit/install.sh
+
+# 2. Agregar check pre-deploy en package.json
+{
+  "scripts": {
+    "predeploy": "npm run security:full",
+    "deploy": "serverless deploy"
+  }
+}
+
+# 3. Ahora npm run deploy verificará seguridad primero
+npm run deploy
+```
+
+**Si hay problemas, el deploy se bloquea**:
+```
+> predeploy
+> npm run security:full
+
+✗ Vulnerabilities detected
+Error: Command failed
+```
+
+---
+
+## Ejemplo 10: Auditoría de Proyecto Legacy
+
+### Situación
+Proyecto viejo con 500+ dependencias, muchas desactualizadas.
+
+### Solución
+
+```bash
+# 1. Instalar kit
+bash /home/diego/projects/npm-security-kit/install.sh
+
+# 2. Auditoría inicial (probablemente fallará)
+npm run security:full > audit-report.txt
+
+# 3. Analizar el reporte
+cat audit-report.txt
+
+# 4. Estrategia de remediación
+# - Críticas y High: Arreglar inmediatamente
+npm run security:audit:fix
+
+# - Medium/Low: Planificar para próximo sprint
+npm outdated > outdated.txt
+
+# 5. Ir arreglando gradualmente
+# Actualizar de a pocas dependencias por vez
+npm update package1 package2
+npm test
+npm run security:full
+
+# 6. Repetir hasta estar limpio
+```
+
+---
+
+## Ejemplo 11: Librería npm Pública
+
+### Situación
+Publicas una librería en npm y quieres asegurar que sea segura.
+
+### Solución
+
+```bash
+# 1. Instalar kit
+bash /home/diego/projects/npm-security-kit/install.sh
+
+# 2. Configurar para librería
+# Editar .security/config.json
+{
+  "projectType": "library",
+  "strictMode": true,
+  "settings": {
+    "checkTransitiveDeps": true
+  }
+}
+
+# 3. Pre-publish hook
+# package.json
+{
+  "scripts": {
+    "prepublishOnly": "npm run security:full && npm run build && npm test"
+  }
+}
+
+# 4. Intentar publicar
+npm publish
+# Si hay problemas de seguridad, se bloquea
+```
+
+---
+
+## Ejemplo 12: Docker + Security Kit
+
+### Situación
+Construyes imágenes Docker y quieres verificar seguridad en build.
+
+### Solución
+
+`Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+
+# Instalar jq
+RUN apk add --no-cache jq
+
+WORKDIR /app
+
+# Copiar archivos de seguridad
+COPY .security .security
+COPY scripts scripts
+COPY package*.json ./
+
+# Hacer scripts ejecutables
+RUN chmod +x scripts/*.sh
+
+# Instalar dependencias
+RUN npm ci --production
+
+# Verificar seguridad
+RUN npm run security:check-malicious || exit 1
+
+# Si pasa, continuar con la app
+COPY . .
+
+CMD ["npm", "start"]
+```
+
+**Build con seguridad**:
+```bash
+docker build -t mi-app:latest .
+# Si hay paquetes maliciosos, el build falla
+```
+
+---
+
+## Resumen de Escenarios
+
+| Escenario | Complejidad | Tiempo | Beneficio |
+|-----------|-------------|--------|-----------|
+| Proyecto Express existente | Baja | 5 min | Protección inmediata |
+| Nueva app React | Muy baja | 2 min | Seguridad desde inicio |
+| Monorepo | Media | 15 min | Protección completa |
+| GitLab CI | Media | 10 min | Automatización CI/CD |
+| Paquete malicioso | Alta | Crítico | Prevención de daños |
+| Actualizar blacklist | Baja | 5 min | Protección actualizada |
+| Pre-commit hooks | Media | 10 min | Prevención proactiva |
+| Slack integration | Media | 15 min | Notificaciones tiempo real |
+| Serverless/Lambda | Baja | 5 min | Deploy seguro |
+| Proyecto legacy | Alta | Iterativo | Mejora gradual |
+| Librería npm | Media | 10 min | Reputación |
+| Docker | Media | 15 min | Containers seguros |
+
+---
+
+**Elige el ejemplo que mejor se adapte a tu caso de uso!**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Organization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.