@lateos/npm-scan 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # npm-scan
 
-Powerful npm supply chain security scanner. Detects malicious packages, supply chain attacks, and generates SBOM reports.
+Powerful npm supply chain security scanner. Detects malicious packages, supply chain attacks, and generates SBOM + compliance reports.
 
 ## Quick Start
 
@@ -17,56 +17,66 @@ npx @lateos/npm-scan scan lodash
 
 ## Features
 
-- **Static Analysis** — detects malicious lifecycle scripts, obfuscated payloads, credential harvesting, persistence, network exfiltration, dependency confusion, and typosquatting (ATK-001–007)
-- **SBOM Output** — CycloneDX 1.5 JSON/XML with findings mapped as vulnerabilities
+- **Static Analysis** — detects malicious lifecycle scripts, obfuscated payloads, credential harvesting, persistence, network exfiltration, dependency confusion, typosquatting, tarball tampering, conditional triggers, and sandbox evasion (ATK-001–010)
+- **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-10.3)
 - **SQLite Storage** — local scan history, zero external dependencies
-- **CLI** — `scan`, `scan-lockfile`, `report --sbom`
+- **CLI** — `scan`, `scan-lockfile`, `report --sbom --html --nist`
+- **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
 
 ## Commands
 
 ```
-npm-scan scan <package>            Scan a package from the npm registry
-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 (json/xml)
+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 --html               Generate HTML report for all scans
 ```
 
 ## Architecture
 
 ```
 cli/          Commander.js CLI entrypoint
-backend/      Detectors, fetch, SQLite db, SBOM, license
+backend/      Detectors, fetch, SQLite db, SBOM, report
 docker/       Multi-arch Docker images + compose
-docs/         Project plan, attack taxonomy (ATK)
-tests/        Corpus: clean + malicious packages
+docs/         Project plan, attack taxonomy (ATK), sandbox threat model
+tests/        Corpus: 5 clean + 30 malicious packages
 ```
 
+## Detectors (ATK Taxonomy)
+
+| 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   |
+
+See `docs/attack-taxonomy.md` for full NIST 800-161 mappings, evasion surfaces, and PoC examples.
+
 ## Development
 
 ```bash
 npm install
 npm run dev          # CLI stub
-npm run test         # Unit tests
-npm run corpus       # False-positive corpus test
+npm run test         # Unit tests (13)
+npm run corpus       # False-positive corpus test (30 malicious, 5 clean)
 ```
 
-## Detectors (ATK Taxonomy)
-
-| 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 |
-
-See `docs/attack-taxonomy.md` for full NIST 800-161 mappings.
-
 ## License
 
-Apache-2.0 core + Commons Clause premium. See `LICENSING.md`.
+Apache-2.0 core + Commons Clause premium. See `LICENSING.md`.

package/backend/db/schema.sql

@@ -1 +1,32 @@
--- SQLite schema for local CLI mode (free tier)\n-- Tables: scans, findings (ATK-linked)\n\nCREATE TABLE IF NOT EXISTS scans (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  package_name TEXT NOT NULL,\n  version TEXT,\n  scanned_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  status TEXT DEFAULT 'completed',\n  sbom_json TEXT\n);\n\nCREATE TABLE IF NOT EXISTS findings (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  scan_id INTEGER NOT NULL,\n  atk_id TEXT NOT NULL REFERENCES attack_taxonomy(id),\n  severity TEXT CHECK (severity IN ('info', 'low', 'medium', 'high', 'critical')),\n  description TEXT,\n  evidence TEXT,\n  mitigation TEXT,\n  FOREIGN KEY (scan_id) REFERENCES scans(id) ON DELETE CASCADE\n);\n\n-- View for reports\nCREATE VIEW scan_findings AS\nSELECT s.*, f.* FROM scans s\nJOIN findings f ON s.id = f.scan_id;\n\n-- Indexes\nCREATE INDEX idx_scans_package ON scans(package_name);\nCREATE INDEX idx_findings_atk ON findings(atk_id);\nCREATE INDEX idx_findings_severity ON findings(severity);
+-- SQLite schema for local CLI mode (free tier)
+-- Tables: scans, findings (ATK-linked)
+
+CREATE TABLE IF NOT EXISTS scans (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  package_name TEXT NOT NULL,
+  version TEXT,
+  scanned_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  status TEXT DEFAULT 'completed',
+  sbom_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS findings (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  scan_id INTEGER NOT NULL,
+  atk_id TEXT NOT NULL,
+  severity TEXT CHECK (severity IN ('info', 'low', 'medium', 'high', 'critical')),
+  description TEXT,
+  evidence TEXT,
+  mitigation TEXT,
+  FOREIGN KEY (scan_id) REFERENCES scans(id) ON DELETE CASCADE
+);
+
+-- View for reports
+CREATE VIEW IF NOT EXISTS scan_findings AS
+SELECT s.*, f.* FROM scans s
+JOIN findings f ON s.id = f.scan_id;
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_scans_package ON scans(package_name);
+CREATE INDEX IF NOT EXISTS idx_findings_atk ON findings(atk_id);
+CREATE INDEX IF NOT EXISTS idx_findings_severity ON findings(severity);

package/backend/sbom.js

@@ -17,13 +17,16 @@ function generateCycloneDX(pkgJson, findings) {
       },
       tools: [{ name: 'npm-scan', version: '0.2.5' }]
     },
-    vulnerabilities: findings.map(f => ({
-      id: f.id,
+    vulnerabilities: findings.map(f => {
+      const atkId = f.atk_id || f.id;
+      return {
+      id: atkId,
       source: { name: 'npm-scan' },
       ratings: [{ severity: f.severity }],
-      description: f.title || '',
+      description: f.description || f.title || '',
       recommendation: f.mitigation || 'Review evidence'
-    }))
+      };
+    })
   };
   return JSON.stringify(bom, null, 2);
 }

package/cli/cli.js

@@ -12,7 +12,7 @@ program
   .description('Scan a package')
   .argument('<target>', 'package name')
   .option('-l, --license-key <key>', 'Premium license')
-  .option('--sbom [format]', 'Generate SBOM (json/xml/spdx)', 'json')
+  .option('--sbom [format]', 'Generate SBOM (json/xml/spdx)')
   .action(async (target, options) => {
     try {
       const { pkgJson, jsFiles, tmpDir } = await import('../backend/fetch.js').then(m => m.fetchPackage(target));
@@ -46,7 +46,7 @@ program
   .command('report')
   .description('Generate report')
   .option('-i, --id <id>', 'Scan ID')
-  .option('--sbom [format]', 'SBOM format (json/xml/spdx)', 'json')
+  .option('--sbom [format]', 'SBOM format (json/xml/spdx)')
   .option('--html', 'HTML report')
   .option('--nist', 'NIST 800-161 compliance report')
   .action(async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lateos/npm-scan",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Powerful npm supply chain security scanner - detects malicious packages (Shai-Hulud style), behavioral analysis, SBOM, and compliance reporting.",
   "main": "backend/index.js",
   "bin": {