Nexus - AI Task Orchestrator

72-npm-security-audit
Procedimiento: NPM Security Audit

Dependencias
1 plugin(s)
Titulo
Descripcion
Contenido Markdown
7953 caracteres
# Procedimiento: NPM Security Audit

## Metadata
- **ID**: PROC-72
- **Frecuencia**: Semanal
- **Duraci├│n estimada**: 15-30 min
- **Requiere**: Acceso al repositorio, npm/yarn instalado
- **Dependencias**: Ninguna
- **Bloquea**: Release (si hay vulnerabilidades cr├¡ticas)
- **Agentes**: security-engineer

---

## Objetivo

Auditar dependencias JavaScript/TypeScript:
1. Ejecutar npm audit / yarn audit
2. Identificar vulnerabilidades por severidad
3. Priorizar actualizaciones
4. Remediar o documentar excepciones

---

## Severidades

| Nivel | Descripci├│n | Acci├│n |
|-------|-------------|--------|
| Critical | Explotable remotamente, impacto alto | Fix inmediato |
| High | Explotable, impacto significativo | Fix antes de release |
| Moderate | Requiere condiciones espec├¡ficas | Planificar fix |
| Low | Impacto m├¡nimo | Evaluar en pr├│xima revisi├│n |

---

## Checklist Ejecutable

### 1. Identificar Proyectos Frontend

```bash
# Encontrar package.json en el repositorio
find . -name "package.json" -not -path "*/node_modules/*" -type f

# Listar proyectos
for pkg in $(find . -name "package.json" -not -path "*/node_modules/*"); do
  echo "=== $pkg ==="
  jq '.name // "unnamed"' "$pkg"
done
```

- [ ] Proyectos identificados: ___

### 2. Ejecutar npm audit

```bash
# Ir a cada proyecto
cd path/to/project

# npm audit
npm audit

# Con formato JSON
npm audit --json > audit-report.json

# Resumen
npm audit --json | jq '{
  total: .metadata.vulnerabilities | add,
  critical: .metadata.vulnerabilities.critical,
  high: .metadata.vulnerabilities.high,
  moderate: .metadata.vulnerabilities.moderate,
  low: .metadata.vulnerabilities.low
}'
```

**O con yarn:**
```bash
yarn audit

yarn audit --json | jq -s '
  [.[] | select(.type == "auditAdvisory")] |
  group_by(.data.advisory.severity) |
  map({severity: .[0].data.advisory.severity, count: length})'
```

- [ ] Audit ejecutado
- [ ] Vulnerabilidades encontradas: ___

### 3. Analizar Resultados

```bash
# Detalle de vulnerabilidades cr├¡ticas y altas
npm audit --json | jq '
  .vulnerabilities | to_entries |
  map(select(.value.severity == "critical" or .value.severity == "high")) |
  .[] | {
    package: .key,
    severity: .value.severity,
    via: [.value.via[] | if type == "object" then .title else . end],
    fixAvailable: .value.fixAvailable
  }'
```

**Resumen por severidad:**

| Severidad | Cantidad | Acci├│n |
|-----------|----------|--------|
| Critical | ___ | Fix inmediato |
| High | ___ | Fix antes de release |
| Moderate | ___ | Planificar |
| Low | ___ | Evaluar |

- [ ] Severidades analizadas

### 4. Identificar Fixes Disponibles

```bash
# Ver qu├® se puede arreglar autom├íticamente
npm audit fix --dry-run

# Fixes que requieren major version bump
npm audit fix --force --dry-run

# Detalle de actualizaciones necesarias
npm outdated
```

**Fixes disponibles:**

| Paquete | Actual | Fix | Breaking |
|---------|--------|-----|----------|
| ___ | ___ | ___ | S├¡/No |

- [ ] Fixes identificados

### 5. Aplicar Fixes Seguros

```bash
# Aplicar fixes que no son breaking changes
npm audit fix

# Verificar que no se rompi├│ nada
npm test
npm run build
```

- [ ] Fixes aplicados
- [ ] Tests pasando
- [ ] Build exitoso

### 6. Evaluar Breaking Changes

Para vulnerabilidades que requieren major version:

```bash
# Ver changelog del paquete
npm view package-name changelog

# Verificar breaking changes
npm view package-name@latest --json | jq '.readme' | head -50
```

| Paquete | Versi├│n Actual | Versi├│n Target | Breaking Changes | Decisi├│n |
|---------|----------------|----------------|------------------|----------|
| ___ | ___ | ___ | ___ | Actualizar/Postergar |

- [ ] Breaking changes evaluados

### 7. Documentar Excepciones

Para vulnerabilidades que no se pueden/quieren arreglar:

```json
// package.json
{
  "overrides": {
    "vulnerable-package": "^2.0.0"
  }
}

// .nsprc o audit-resolve.json
{
  "exceptions": [
    {
      "id": 1234,
      "reason": "No aplica: solo afecta feature que no usamos",
      "expires": "2024-06-01"
    }
  ]
}
```

- [ ] Excepciones documentadas con justificaci├│n

### 8. Actualizar Lockfile

```bash
# Regenerar lockfile limpio
rm -rf node_modules package-lock.json
npm install

# O con npm ci para CI
npm ci
```

- [ ] Lockfile actualizado
- [ ] node_modules limpio

---

## Herramientas Adicionales

```bash
# Snyk (m├ís detallado)
npx snyk test

# npm-check para updates
npx npm-check

# depcheck para dependencias no usadas
npx depcheck
```

---

## Output Esperado

```
====== PROC-72 COMPLETADO [TIMESTAMP] ======
Proyecto: [nombre]
Fecha: [fecha]

RESUMEN:
- Paquetes totales: X
- Vulnerabilidades encontradas: Y
- Fixes aplicados: Z

POR SEVERIDAD:
| Severidad | Antes | Despu├®s | Pendientes |
|-----------|-------|---------|------------|
| Critical | X | 0 | 0 |
| High | Y | 0 | 0 |
| Moderate | Z | W | V |
| Low | A | B | C |

VULNERABILIDADES PENDIENTES:
| Paquete | Severidad | Motivo Pendiente |
|---------|-----------|------------------|
| lodash | moderate | Breaking change, evaluar sprint |

EXCEPCIONES DOCUMENTADAS:
| ID | Paquete | Motivo | Expira |
|----|---------|--------|--------|
| 1234 | xml2js | No usamos feature afectado | 2024-06-01 |

ACTUALIZACIONES APLICADAS:
- package-a: 1.0.0 -> 1.0.1
- package-b: 2.3.0 -> 2.4.0

ESTADO: Ô£à Sin cr├¡ticos/altos / ÔÜá´©Å Pendientes de evaluar / ÔØî Cr├¡ticos sin fix
```

---

## Criterios de ├ëxito

- [ ] 0 vulnerabilidades Critical
- [ ] 0 vulnerabilidades High
- [ ] Moderates con plan de acci├│n
- [ ] Excepciones documentadas

---

## Alertas y Escalaci├│n

| Severidad | Condici├│n | Acci├│n |
|-----------|-----------|--------|
| CRITICAL | Critical sin fix disponible | Buscar alternativa al paquete |
| CRITICAL | Critical sin fix aplicado | Bloquear release |
| WARNING | High sin fix | Planificar para pr├│ximo sprint |
| INFO | Solo Moderate/Low | Documentar y monitorear |

---

## Automatizaci├│n

```yaml
# GitLab CI
npm-audit:
  stage: security
  script:
    - npm audit --audit-level=high
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_COMMIT_BRANCH == "main"
```

---


---

## Output Estructurado (Nexus)

Al finalizar, el agente DEBE generar un bloque JSON con el siguiente formato para que Nexus pueda procesarlo automaticamente:

```json
{
  "result": "success",
  "summary": "Ejecucion de PROC-72 completada. [Descripcion breve de resultados]",
  "metrics": {
    "issues_found": 0,
    "issues_resolved": 0,
    "findings_total": 5, "findings_critical": 0,
    "custom": {
      "procedure_specific_metric": "value"
    }
  },
  "backlog_items": [
    {
      "title": "Titulo del item de seguimiento",
      "description": "Descripcion detallada si se requiere accion futura",
      "priority": "medium",
      "type": "improvement",
      "tags": ["proc-72"]
    }
  ],
  "next_steps": [
    "Accion recomendada 1",
    "Accion recomendada 2"
  ],
  "warnings": [
    "Advertencias encontradas durante la ejecucion"
  ]
}
```

**Campos requeridos:**
- `result`: `"success"` | `"partial"` | `"failed"`
- `summary`: Resumen ejecutivo en 1-3 lineas

**Metricas especificas de este procedure:**
- packages_scanned, vulnerabilities_found, vulnerabilities_fixed

**Criterios de resultado:**
- `success`: Procedimiento completado sin errores criticos
- `partial`: Completado con algunos problemas menores o items pendientes
- `failed`: Error critico o no se pudo completar

## Historial de Ejecuciones

| Fecha | Proyecto | Critical | High | Moderate | Fixes | Estado |
|-------|----------|----------|------|----------|-------|--------|
| | | | | | | |