Skip to content

VULNERABILITY_SCAN_RUNBOOK.md

Latest commit

 

History

History
140 lines (110 loc) · 6.46 KB

VULNERABILITY_SCAN_RUNBOOK.md

File metadata and controls

140 lines (110 loc) · 6.46 KB
Raw

Dependency Vulnerability Scan Runbook

Purpose

Operator procedures for automated dependency vulnerability scanning, alerting, and blue-green / canary deployment gates.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│  CI/CD Pipeline (.github/workflows/dependency-scan.yml)          │
│                                                                  │
│  pnpm audit  ──►  npm audit  ──►  OSV-Scanner  ──►  SBOM gen   │
│       │              │               │               │          │
│       └──────────────┴───────────────┴───────────────┘          │
│                              │                                   │
│                              ▼                                   │
│  scripts/check-deployment-gate.mjs                               │
│    ──► blocks deploy if critical vulnerabilities found           │
│    ──► warns on high, passes on medium/low                       │
│                              │                                   │
│                              ▼                                   │
│  Runtime Dashboard (/dashboard/vulnerability)                    │
│    ──► useDependencyScan hook                                    │
│    ──► POST /api/telemetry/vulnerability                         │
│    ──► DependencyScanner service (src/services/dependencyScan.ts)│
└──────────────────────────────────────────────────────────────────┘

Components

Path Role
src/lib/vulnerability/types.ts Shared types, severity levels, performance budgets
src/lib/vulnerability/scanner.ts Pure functions: parse lockfiles, build findings, canary gating
src/lib/vulnerability/advisorySource.ts npm audit + OSV API adapters
src/lib/vulnerability/redact.ts Redact sensitive package names from telemetry
src/services/dependencyScan.ts Service orchestrator, registry, history, singleton
src/hooks/useDependencyScan.ts React subscription + periodic scanning
src/utils/vulnerabilityTelemetry.ts Telemetry reporter with offline queue fallback
src/app/api/telemetry/vulnerability/route.ts Monitoring ingest endpoint
src/components/dashboard/VulnerabilityDashboard.tsx Operator dashboard
src/app/dashboard/vulnerability/page.tsx Dashboard route
.github/workflows/dependency-scan.yml CI/CD pipeline
scripts/check-deployment-gate.mjs Deployment gate decision

Monitoring

Signal Source Alert when
Critical vulnerabilities pnpm audit / npm audit / OSV criticalCount > 0
High vulnerability rate CI gate output highRate > 5% in canary
Scan latency metrics.durationMs / withinBudget P99 >= 100ms
Canary hold checkCanaryGate() reason promote === false after min samples

Dashboard

Open /dashboard/vulnerability to inspect:

  • last scan status and duration,
  • per-finding table (package, version, severity, advisory ID, fix available),
  • severity breakdown (critical / high / medium / low),
  • canary promote / hold recommendation,
  • total dependencies scanned and advisory source version.

Log alerts

The telemetry route logs at different levels:

  • console.error for critical vulnerabilities,
  • console.warn for high-severity findings,
  • console.info otherwise.

Wire log drains (CloudWatch, Datadog, etc.) to these messages for paging.

Triage

  1. Open /dashboard/vulnerability and click Run scan.
  2. For each critical finding:
    • Determine if the vulnerable package is in the direct dependency tree or transitive.
    • Check fixedIn field for the patched version.
    • Update package.json dependencies or add a resolution override.
    • Run pnpm update <package> to apply the fix.
  3. For high findings, schedule a fix within the next change window.
  4. Confirm withinBudget is true; if not, reduce advisory source work.

Blue-green deployment

  1. CI runs dependency-scan.yml on every push to main and release/*.
  2. The check-deployment-gate.mjs script reads aggregated scan results.
  3. If criticalCount > 0, the gate blocks the build (exit code 1).
  4. Operators must resolve all critical CVEs before the inactive slot can be promoted.
  5. After resolution, redeploy to the inactive slot; the gate re-runs automatically.
  6. Flip the edge router / CDN to the new slot (instant cutover).
  7. Keep the previous slot warm for rapid rollback.

Canary analysis

  1. CI sets DEPLOY_CHANNEL=canary for PR builds and release/* branches.
  2. Each scan produces a ScanReport recorded in the scanner's history ring.
  3. Promotion requires:
    • Critical vulnerability rate = 0,
    • High vulnerability rate <= 5%,
    • Minimum 3 samples collected.
  4. If promote === false, halt expansion, fix vulnerabilities, and re-sample.
  5. On success, promote canary -> green -> stable.

Rollback

  1. Point traffic to the previous blue/green slot.
  2. Re-run scan on the serving slot; confirm no critical findings.
  3. File an incident note with the vulnerability report from the failed canary.

Security review checklist

  • No plaintext package names from private registries in telemetry (expect [REDACTED]).
  • All findings redacted before telemetry POST (redactReport()).
  • npm audit and OSV API calls are read-only; no credentials transmitted.
  • SBOM generation is scoped to production dependencies only.
  • Advisory sources are pinned to specific versions in CI.
  • New package sources register a PackageSource in the scanner.

Performance budget

  • Critical path: scanSource() / scanAll() (sync parse + advisory fetch).
  • Budget: PERFORMANCE_BUDGET_MS = 100.
  • Each report includes metrics.durationMs and metrics.withinBudget.
  • Advisory fetches are async and may exceed budget on first scan; subsequent scans use cached results to stay within budget.

Test commands

# Core library tests
npx tsx src/lib/vulnerability/__tests__/dependencyScan.test.ts

# Service layer tests
npx tsx src/services/__tests__/dependencyScan.test.ts