@lateos/npm-scan 0.3.1 → 0.3.3

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.js

@@ -33,6 +33,10 @@ export function getFindings(scanId) {
   return db.prepare('SELECT * FROM findings WHERE scan_id = ?').all(scanId);
 }
 
+export function getScan(scanId) {
+  return db.prepare('SELECT * FROM scans WHERE id = ?').get(scanId);
+}
+
 export function close() {
   db.close();
 }

package/backend/report.js

@@ -6,7 +6,7 @@ export function generateHTML(scans) {
     const worstLabel = ['', 'info', 'low', 'medium', 'high', 'critical'][worst] || 'clean';
     const color = { critical: '#d73a49', high: '#cb2431', medium: '#f66a0a', low: '#dbab09', clean: '#28a745' }[worstLabel] || '#28a745';
     const findingRows = findings.map(f =>
-      `<tr><td>${f.id}</td><td style="color:${color}">${f.severity}</td><td>${f.title || ''}</td><td>${(f.evidence || '').slice(0, 80)}</td></tr>`
+      `<tr><td>${f.atk_id || f.id}</td><td style="color:${color}">${f.severity}</td><td>${f.description || f.title || ''}</td><td>${(f.evidence || '').slice(0, 80)}</td></tr>`
     ).join('');
     return { name: s.package_name, worstLabel, color, count: findings.length, findingRows };
   });
@@ -65,7 +65,7 @@ th { background: #161b22; font-weight: 600; }
 <h2>NIST SP 800-161 Compliance Summary</h2>
 ${nistMap}
 
-<p class="meta">npm-scan v0.2.5 | Apache-2.0 + Commons Clause | NIST SP 800-161 mapped</p>
+<p class="meta">npm-scan v${process.env.npm_package_version || '0.3.2'} | Apache-2.0 + Commons Clause | NIST SP 800-161 mapped</p>
 </body>
 </html>`;
 }
@@ -74,8 +74,9 @@ function getAtkFindings(scans) {
   const map = {};
   for (const s of scans) {
     for (const f of (s.findings || [])) {
-      if (!map[f.id]) map[f.id] = [];
-      map[f.id].push(f);
+      const key = f.atk_id || f.id;
+      if (!map[key]) map[key] = [];
+      map[key].push(f);
     }
   }
   return map;

package/backend/sbom.js

@@ -15,7 +15,7 @@ function generateCycloneDX(pkgJson, findings) {
         version: pkgJson.version || 'unknown',
         purl: `pkg:npm/${pkgJson.name || 'unknown'}@${pkgJson.version || 'unknown'}`
       },
-      tools: [{ name: 'npm-scan', version: '0.2.5' }]
+      tools: [{ name: 'npm-scan', version: '0.3.2' }]
     },
     vulnerabilities: findings.map(f => {
       const atkId = f.atk_id || f.id;
@@ -60,7 +60,7 @@ function generateSPDX(pkgJson, findings) {
       annotationDate: new Date().toISOString(),
       annotationType: 'OTHER',
       annotator: 'Tool: npm-scan',
-      comment: `[${f.id}] ${f.severity.toUpperCase()}: ${f.title || ''} — ${f.description || ''}`
+      comment: `[${f.atk_id || f.id}] ${f.severity.toUpperCase()}: ${f.description || f.title || ''}`
     }))
   };
   return JSON.stringify(spdx, null, 2);

package/cli/cli.js

@@ -50,17 +50,20 @@ program
   .option('--html', 'HTML report')
   .option('--nist', 'NIST 800-161 compliance report')
   .action(async (options) => {
-    const { getRecentScans, getFindings, db } = await import('../backend/db.js');
+    const { getRecentScans, getFindings, getScan } = await import('../backend/db.js');
     if (options.id) {
       const findings = getFindings(options.id);
-      const pkg = { name: 'scanned-pkg', version: 'unknown' };
+      const scanInfo = getScan(options.id);
+      const pkgName = scanInfo?.package_name || 'scan-' + options.id;
+      const pkgVer = scanInfo?.version || 'unknown';
+      const pkg = { name: pkgName, version: pkgVer };
       if (options.sbom) {
         const { generateSBOM } = await import('../backend/sbom.js');
         const sbom = generateSBOM(pkg, findings, options.sbom === true ? 'json' : options.sbom);
         console.log(sbom);
       } else if (options.html || options.nist) {
         const { generateHTML } = await import('../backend/report.js');
-        const scan = findings.length ? { package_name: 'scan-' + options.id, findings } : null;
+        const scan = findings.length ? { package_name: pkgName, version: pkgVer, findings } : null;
         const html = generateHTML(scan ? [scan] : []);
         console.log(html);
       } else {

package/package.json

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