@lateos/npm-scan 0.7.5 → 0.8.0

package/.dockerignore

@@ -0,0 +1,20 @@
+node_modules
+.git
+.env
+*.log
+*.tmp
+*.swp
+coverage
+.nyc_output
+tests
+docs
+docker
+*.md
+!README.md
+.eslintrc*
+.prettierrc*
+tsconfig*
+.vscode
+.idea
+*.test.js
+*.spec.js

package/README.md

@@ -1,122 +1,383 @@
-# npm-scan
+# @lateos/npm-scan
 
-Powerful npm supply chain security scanner. Detects malicious packages, supply chain attacks, and generates SBOM + compliance reports.
+[![npm version](https://img.shields.io/npm/v/@lateos/npm-scan?style=flat-square)](https://www.npmjs.com/package/@lateos/npm-scan)
+[![License](https://img.shields.io/badge/license-Apache%202.0%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSING.md)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](package.json)
 
-## Quick Start
+**Modern supply chain security for the npm ecosystem.**  
+Static + behavioral analysis that catches what npm audit, Snyk, and Socket miss — obfuscated payloads, credential stealers, conditional triggers, sandbox evasion, and worm-like propagation.
+
+---
+
+## 📌 The Problem
+
+The 2025–2026 wave of npm supply chain attacks proved that traditional tooling is no longer enough.
+
+Attackers have moved past simple typosquatting. They now ship **obfuscated preinstall hooks**, **credential harvesters hidden behind environment detection**, **dormant backdoors with time-based activation**, and **worm-style transitive propagation** that spreads through peer dependencies.
+
+**npm audit** checks known CVEs. **Snyk** scans for vulnerabilities. **Socket** looks at package behavior. None of them were designed for the generation of attacks that emerged in 2025 — attacks that look benign until they reach production.
+
+**@lateos/npm-scan** was built for this moment.
+
+---
+
+## 🔬 Why @lateos/npm-scan?
+
+| Capability | npm audit | Snyk | Socket | **@lateos/npm-scan** |
+|---|---|---|---|---|
+| Known CVE matching | ✅ | ✅ | ❌ | ✅ |
+| Static analysis | ❌ | ✅ | ✅ | ✅ |
+| Obfuscated payload detection | ❌ | ❌ | ❌ | ✅ |
+| Behavioral / heuristic analysis | ❌ | ❌ | Partial | ✅ |
+| Conditional trigger detection (ATK-009) | ❌ | ❌ | ❌ | ✅ |
+| Sandbox evasion detection (ATK-010) | ❌ | ❌ | ❌ | ✅ |
+| Transitive worm propagation (ATK-011) | ❌ | ❌ | ❌ | ✅ |
+| Attack taxonomy (ATK series) | ❌ | ❌ | ❌ | ✅ |
+| SBOM output (CycloneDX + SPDX) | ❌ | ✅ | ❌ | ✅ |
+| NIST 800-161 compliance reporting | ❌ | ❌ | ❌ | ✅ |
+| EU CRA compliance reporting | ❌ | ❌ | ❌ | ✅ |
+| SIEM export (CEF / ECS / Sentinel / QRadar) | ❌ | ❌ | ❌ | ✅ |
+| Runs entirely locally — no telemetry | ✅ | ❌ | ❌ | ✅ |
+| Policy-as-code (YAML allowlists) | ❌ | ❌ | ❌ | ✅ |
+
+> **Privacy first.** All scanning happens on your machine. No code leaves your environment. No telemetry. No cloud dependency.
+
+---
+
+## ✨ Key Features
+
+| Icon | Feature | Description |
+|------|---------|-------------|
+| 🕵️ | **Heuristic static analysis** | AST-level inspection catches obfuscation, eval chains, env probing, and suspicious lifecycle scripts that regex-based tools miss |
+| 🧠 | **Behavioral detection** | Identifies conditional triggers (time-based, CI-aware), sandbox evasion, and dormant activation patterns |
+| 🧬 | **ATK attack taxonomy** | 11 classified attack types with NIST 800-161 mappings — versioned, documented, and PR-able |
+| 📦 | **SBOM generation** | CycloneDX 1.5 and SPDX 2.3 with findings embedded as vulnerabilities |
+| 🧾 | **Compliance reporting** | NIST SP 800-161 traceability matrix + EU Cyber Resilience Act mapping (free tier) |
+| 🔌 | **SIEM export** | Splunk CEF, Elastic ECS, Microsoft Sentinel, IBM QRadar formats (premium) |
+| 📜 | **Policy-as-code** | YAML/JSON policy engine with allowlists, severity overrides, suppressions, and fail-on thresholds |
+| 🐳 | **Docker + GitHub Action** | Multi-arch images, one-command Compose pipeline, PR scan action |
+| 🛡️ | **Zero telemetry** | No data leaves your machine. No cloud. No callbacks. |
+| 💾 | **Local scan history** | SQLite-backed persistence, zero external dependencies |
+
+---
+
+## ⚡ Quick Start
 
 ```bash
+# Install globally
 npm install -g @lateos/npm-scan
+
+# Scan a single package
 npm-scan scan lodash
+
+# Scan your lockfile
+npm-scan scan-lockfile
+
+# View latest scans
+npm-scan report
 ```
 
-Or run without install:
+**No install? No problem:**
 
 ```bash
-npx @lateos/npm-scan scan lodash
+npx @lateos/npm-scan scan commander
 ```
 
-## Features
+---
+
+## 📖 Usage Examples
+
+### Scan a single package
 
-- **Static Analysis** — detects malicious lifecycle scripts, obfuscated payloads, credential harvesting, persistence, network exfiltration, dependency confusion, typosquatting, tarball tampering, conditional triggers, sandbox evasion, and transitive propagation (ATK-001–011)
-- **SBOM Output** — CycloneDX 1.5 and SPDX 2.3 with findings mapped as vulnerabilities
-- **NIST 800-161 Compliance** — HTML report includes control traceability matrix (SR-2.1 → SR-11.4)
-- **EU CRA Compliance** — report maps findings to Cyber Resilience Act articles and Annex I requirements
-- **SIEM Export** — Splunk CEF, Elastic ECS, Microsoft Sentinel, IBM QRadar formats (premium)
-- **EU CRA Compliance** — report maps findings to Cyber Resilience Act articles (premium)
-- **License Key Gating** — premium features locked behind signed license keys
-- **REST API** — FastAPI-based API with webhooks, auth, scan management (premium)
-- **SAML SSO** — enterprise single sign-on via Okta, Azure AD, OneLogin, Keycloak (enterprise)
-- **Kubernetes / Helm** — Helm chart for deploying the full pipeline on K8s (premium)
-- **SQLite Storage** — local scan history, zero external dependencies
-- **CLI** — `scan`, `scan-lockfile`, `report --sbom --html --nist --cra --siem`
-- **Dynamic Sandbox** — gVisor-based isolation (premium, documented in `docs/sandbox-threat-model.md`)
-- **GitHub Action** — scans lockfile on PRs
-- **Docker** — multi-arch images via GHCR
+```bash
+# Default JSON output with all findings
+npm-scan scan axios
 
-## Commands
+# Generate an SBOM alongside the scan
+npm-scan scan express --sbom             # CycloneDX JSON
+npm-scan scan express --sbom xml         # CycloneDX XML
+npm-scan scan express --sbom spdx        # SPDX 2.3
 
+# Apply a YAML policy
+npm-scan scan some-package --policy .npm-scan.yml
 ```
-npm-scan scan <package>              Scan a package from the npm registry
-npm-scan scan <package> --sbom       Scan + output CycloneDX SBOM
-npm-scan scan <package> --sbom spdx  Scan + output SPDX SBOM
-npm-scan scan-lockfile               Scan a local package-lock.json
-npm-scan report                      List recent scans
-npm-scan report -i <id>              Show findings for a scan
-npm-scan report -i <id> --sbom       Generate CycloneDX SBOM
-npm-scan report -i <id> --sbom spdx  Generate SPDX SBOM
-npm-scan report -i <id> --html       Generate HTML report (with NIST table)
-npm-scan report -i <id> --nist       Print NIST 800-161 compliance table
-npm-scan report -i <id> --cra        Print EU CRA compliance table
-npm-scan report -i <id> --siem <fmt>   Generate SIEM output (cef|ecs|sentinel|qradar) (premium)
-npm-scan report --html               Generate HTML report for all scans
-npm-scan report --nist               Print NIST compliance for all scans
-npm-scan report --cra                Print EU CRA compliance for all scans (premium)
-npm-scan report --siem cef           Generate SIEM for all scans (premium)
+
+### Scan a lockfile
+
+```bash
+# Scan the current project's dependencies
+npm-scan scan-lockfile
+
+# Scan a specific lockfile
+npm-scan scan-lockfile -f ./path/to/package-lock.json
+```
+
+### Generate reports
+
+```bash
+# List all recent scans
+npm-scan report
+
+# View a specific scan
+npm-scan report -i 42
+
+# Generate an HTML report (free) with full findings + NIST table
+npm-scan report -i 42 --html
+
+# Print NIST 800-161 compliance table
+npm-scan report -i 42 --nist
+
+# Print EU CRA compliance table
+npm-scan report --cra
+
+# Text report (free)
+npm-scan report --text
+
+# PDF report (premium)
+npm-scan report --pdf --license-key <key>
+
+# SIEM export (premium)
+npm-scan report --siem cef        # Splunk CEF
+npm-scan report --siem ecs        # Elastic ECS
+npm-scan report --siem sentinel   # Microsoft Sentinel
+npm-scan report --siem qradar     # IBM QRadar
+
+# Combine all scans into a single report
+npm-scan report --html            # all scans
+npm-scan report --pdf             # all scans (premium)
+```
+
+---
+
+## 🧬 Detection Capabilities (ATK Taxonomy)
+
+| ID | Attack Class | Detection Method | Severity | NIST 800-161 |
+|---|---|---|---|---|
+| **ATK-001** | Malicious lifecycle scripts (`preinstall`, `postinstall`, `install`) | Static | 🔴 high | SR-3.1 |
+| **ATK-002** | Obfuscated payload delivery (hex, base64, eval chains) | Static | 🟠 medium | SR-4.2 |
+| **ATK-003** | Credential harvesting (env vars, .npmrc, SSH keys) | Static + Dynamic | 🔴 high | SR-5.3 |
+| **ATK-004** | Persistence via editor/config dirs (.vscode, .claude, .cursor) | Static | 🔴 high | SR-6.4 |
+| **ATK-005** | Network exfiltration (GitHub API, DNS tunneling, HTTP C2) | Static + Dynamic | ⚫ critical | SR-7.5 |
+| **ATK-006** | Dependency confusion / namespace squatting | Static (lockfile) | 🟠 medium | SR-2.2 |
+| **ATK-007** | Typosquatting (edit-distance matching) | Static | 🟢 low | SR-2.1 |
+| **ATK-008** | Tarball tampering (published ≠ source) | Static | 🔴 high | SR-8.1 |
+| **ATK-009** | Conditional/dormant triggers (CI detection, time-based) | Behavioral | 🔴 high | SR-9.2 |
+| **ATK-010** | Sandbox evasion / anti-analysis | Behavioral | 🟠 medium | SR-10.3 |
+| **ATK-011** | Transitive propagation (worm-style lateral spread) | Behavioral | 🔴 high | SR-11.4 |
+
+> **How evasive attacks are caught:** ATK-009 detects packages that check `process.env.CI`, probe hostnames, or use time-based activation. ATK-010 flags `debugger` statements, `os.hostname()` probes, and env fingerprinting. ATK-011 traces peer dependency graphs to detect worm-like propagation patterns.  
+> See [`docs/attack-taxonomy.md`](docs/attack-taxonomy.md) for full evasion surface documentation and PoC examples.
+
+---
+
+## 📊 Output & Reports
+
+### Formats
+
+| Format | Availability | Description |
+|--------|-------------|-------------|
+| JSON | ✅ Free | Structured machine-readable findings |
+| HTML | ✅ Free | Rich HTML report with NIST compliance table, severity badges, control matrix |
+| Text | ✅ Free | Clean terminal-friendly text report |
+| CycloneDX SBOM | ✅ Free | Industry-standard SBOM with findings as vulnerabilities |
+| SPDX SBOM | ✅ Free | SPDX 2.3 document format |
+| NIST 800-161 | ✅ Free | Control traceability matrix (SR-2.1 → SR-11.4) |
+| EU CRA | ✅ Free | Cyber Resilience Act article mapping |
+| PDF | 🔐 Premium | Multi-page PDF with title page, findings table, NIST compliance matrix |
+| Splunk CEF | 🔐 Premium | Common Event Format for Splunk ingestion |
+| Elastic ECS | 🔐 Premium | Elastic Common Schema format |
+| Microsoft Sentinel | 🔐 Premium | Sentinel-ready formatted output |
+| IBM QRadar | 🔐 Premium | QRadar DSM-ready format with QID mappings |
+
+### Sample output
+
+```json
+{
+  "scanId": 1,
+  "findings": [
+    {
+      "id": "ATK-003",
+      "severity": "high",
+      "title": "Credential harvesting",
+      "evidence": "process.env.NPM_TOKEN detected in postinstall.js:17"
+    }
+  ]
+}
 ```
 
-## Architecture
+---
+
+## ⚙️ Configuration & Advanced Usage
+
+### Policy-as-code
+
+Define allowlists, severity overrides, suppressions, and fail thresholds in a YAML file:
+
+```yaml
+# .npm-scan.yml
+allowlist:
+  - lodash
+  - chalk
 
+severity_overrides:
+  - id: ATK-001
+    severity: medium
+
+suppress:
+  - atk_id: ATK-009
+  - package: some-package
+
+fail_on: high
+```
+
+```bash
+npm-scan scan target --policy .npm-scan.yml
 ```
-cli/          Commander.js CLI entrypoint
-backend/      Detectors, fetch, SQLite db, SBOM, report, license, SIEM, CRA
-api/          FastAPI REST API + webhooks (premium)
-docker/       Multi-arch Docker images + compose
-deploy/       Kubernetes Helm chart (premium)
-docs/         Project plan, attack taxonomy (ATK), sandbox threat model
-tests/        Corpus: 5 clean + 33 malicious packages
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NPM_SCAN_LICENSE_KEY` | Premium / enterprise license key | — |
+| `NPM_SCAN_DATA_DIR` | Scan history directory | `./.npm-scan` |
+| `NPM_SCAN_LOG_LEVEL` | Log verbosity | `info` |
+
+### Premium licensing
+
+```bash
+# Generate a development key
+node -e "console.log(require('@lateos/npm-scan/backend/license').generateKey('premium'))"
+
+# Use it
+npm-scan scan target --license-key <key>
+npm-scan report --pdf --license-key <key>
+npm-scan report --siem cef --license-key <key>
 ```
 
-## Detectors (ATK Taxonomy)
+---
+
+## 🔗 Integrations
 
-| ID      | Class                                      | Severity |
-|---------|--------------------------------------------|----------|
-| ATK-001 | Malicious lifecycle scripts                 | high     |
-| ATK-002 | Obfuscated payloads                         | medium   |
-| ATK-003 | Credential harvesting                       | high     |
-| ATK-004 | Persistence via editor configs              | high     |
-| ATK-005 | Network exfiltration                        | critical |
-| ATK-006 | Dependency confusion                        | medium   |
-| ATK-007 | Typosquatting                               | low      |
-| ATK-008 | Tarball tampering (published ≠ source)      | high     |
-| ATK-009 | Conditional/dormant triggers (CI, time)     | high     |
-| ATK-010 | Sandbox evasion / anti-analysis             | medium   |
-| ATK-011 | Transitive propagation (worm)               | high     |
+### GitHub Action
 
-See `docs/attack-taxonomy.md` for full NIST 800-161 mappings, evasion surfaces, and PoC examples.
+Scan your lockfile on every PR. Add to `.github/workflows/scan.yml`:
 
-## Enterprise Features
+```yaml
+name: npm-scan
+on: [pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: lateos/npm-scan-action@v1
+        with:
+          lockfile: package-lock.json
+          policy: .npm-scan.yml       # optional
+          license-key: ${{ secrets.NPM_SCAN_LICENSE_KEY }}  # optional (premium)
+```
 
-### SAML SSO
+### Docker
 
-SAML 2.0 single sign-on for enterprise deployments. Supports:
+```bash
+# Pull and run
+docker pull ghcr.io/lateos/npm-scan:cli
+docker run --rm ghcr.io/lateos/npm-scan:cli scan lodash
 
-- **IdPs:** Okta, Azure AD / Entra ID, OneLogin, Keycloak, any SAML 2.0 compliant provider
-- **Flow:** SP-initiated SSO redirect → IdP auth → assertion validation → JWT issuance
-- **Provisioning:** auto-creates users from SAML attributes with RBAC (admin/editor/viewer)
-- **Security:** signed AuthnRequests, verified assertions, HMAC-SHA256 JWTs, Single Logout
+# Full pipeline with Compose (Redis-based queue)
+docker compose --profile pipeline up -d
 
+# CLI with persistent storage
+docker compose --profile cli up -d
 ```
-GET  /api/v1/sso/metadata    # SP metadata XML for IdP registration
-GET  /api/v1/sso/login       # Start SSO (redirects to IdP)
-POST /api/v1/sso/acs         # SAML callback (IdP POSTs here)
-POST /api/v1/sso/slo         # Single Logout
+
+Multi-arch images available for `linux/amd64` and `linux/arm64`.
+
+### CI/CD
+
+```bash
+# Fail the build if critical findings exist
+npm-scan scan express --policy .npm-scan.yml || exit 1
 ```
 
-Requires enterprise license. Configure via env vars or `api/saml-config.yaml`. See `api/README.md` for full docs.
+---
 
-### REST API
+## 🗺️ Roadmap & Enterprise Features
 
-FastAPI-based API for the hosted tier. See `api/README.md` for endpoint reference, auth methods, and configuration.
+### Free tier (shipped)
 
-## Development
+- All 11 ATK detectors (static + behavioral)
+- SBOM output (CycloneDX + SPDX)
+- HTML, text, and compliance reports (NIST + EU CRA)
+- Policy-as-code engine (YAML)
+- Local SQLite scan history
+- GitHub Action
+- Docker images + Compose pipeline
+
+### Premium (🔐 license key)
+
+- PDF compliance reports with NIST traceability matrix
+- SIEM export (Splunk CEF, Elastic ECS, Microsoft Sentinel, IBM QRadar)
+- Dynamic sandbox (gVisor-based — ATK-008–010)
+- Reachability analysis (call graph filtering)
+
+### Enterprise (🏢 custom license)
+
+- SAML 2.0 SSO (Okta, Azure AD, OneLogin, Keycloak)
+- REST API + webhooks (FastAPI)
+- Team RBAC + audit logs
+- Helm chart for Kubernetes deployment
+- PostgreSQL backend for hosted/team tier
+- SLA-backed priority support
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions — especially new detectors, improved evasion resistance, and compliance templates.
+
+See [`docs/attack-taxonomy.md`](docs/attack-taxonomy.md) for the ATK governance process. Every new detector requires:
+
+1. A proof-of-concept sample
+2. A detection rule with tests
+3. False-positive analysis on top-500 npm packages
+4. NIST 800-161 control mapping
 
 ```bash
+git clone https://github.com/lateos/npm-scan.git
 npm install
-npm run dev          # CLI stub
-npm run test         # Unit tests (14)
-npm run corpus       # False-positive corpus test (33 malicious, 5 clean)
+npm test
 ```
 
-## License
+### Need help?
+
+- 📖 Read the [project plan](docs/project-plan.md)
+- 🧬 Review the [attack taxonomy](docs/attack-taxonomy.md)
+- 🐛 Open an issue or PR
+
+---
+
+## 📄 License
 
-Apache-2.0 core + Commons Clause premium. See `LICENSING.md`.
+Apache-2.0 core + Commons Clause.  
+See [`LICENSING.md`](LICENSING.md) for the exact boundary between free and premium features.
+
+```
+@lateos/npm-scan — npm supply chain security scanner
+Copyright (C) 2026 Lateos
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+```
+
+---
+
+**Scan your first package now:**
+
+```bash
+npx @lateos/npm-scan scan lodash
+```