@lateos/npm-scan 0.9.7 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,200 @@
+# Changelog
+
+All notable changes to [@lateos/npm-scan](https://github.com/lateos-ai/npm-scan) are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `scan --file <path>` flag to analyze local `.tgz` tarballs without fetching from npm registry
+- `scan --fail-on <level>` flag to exit with code 1 when findings >= severity (CI/CD integration)
+- `scan --sarif [file]` to output SARIF v2.1 format for GitHub Advanced Security, VS Code, Azure DevOps
+- `scan --csv [file]` and `report --csv [file]` to export tabular CSV for Excel/Sheets import
+- `scan --score-only` to output only risk score (0-10), auto-added to JSON output
+- Government/SOC 2 features: `--audit-log`, `--fips`, `--stig`, `--cache-dir` for air-gapped/federal compliance
+- **BYOC (Bring Your Own Cloud)**: Helm chart v1.0.0 for enterprise/government VPC deployments with SIEM, PDF, SSO
+
+## [0.9.7] — 2026-05-12
+
+- Sigstore provenance attestation on every publish via new GitHub Actions workflow
+- Fix duplicate Docker section in README.md
+- Add SECURITY.md with vulnerability disclosure policy and PGP key
+
+## [0.9.6] — 2026-05-12
+
+- Add Docker badge (`ghcr.io/lateos/npm-scan`) to all 5 READMEs
+- Add dedicated Docker quick-start section in all languages
+- Replace duplicate Docker pull instructions in Integrations with cross-references
+
+## [0.9.5] — 2026-05-12
+
+- Fix literal `\n` escape sequences in LICENSING.md (replaced with real newlines)
+
+## [0.9.4] — 2026-05-11
+
+- Fix language badge links to use absolute GitHub URLs so they work from npm web UI
+- Fix GitHub organization links from `lateos` to `lateos-ai` across all READMEs
+
+## [0.9.3] — 2026-05-11
+
+- Add multi-language README: Chinese (`README.zh.md`), Japanese (`README.ja.md`), French (`README.fr.md`), German (`README.de.md`)
+- Language-switcher badges with absolute GitHub URLs in all 5 READMEs
+
+## [0.9.2] — 2026-05-11
+
+- **222 tests across 8 test files** (212 passing, 10 skipped for known FPs)
+- **85% line coverage** with Node.js native test runner
+- New test files: `test/db.test.js`, `test/detectors-edge-cases.test.js`, `test/detectors-corpus.test.js`, `test/report-snapshots.test.js`, `test/fetch.test.js`, `test/policy-edge-cases.test.js`, `test/cli.test.js`, `test/fixtures/mock-data.js`
+- `backend/db.js:close()` resets `initPromise = null` for test isolation
+- GitHub Actions CI with Node 18/20/22 matrix, corpus tests, and self-scan
+- GitHub Actions PR lockfile scanner with `fail-on: high`
+
+## [0.9.1] — 2026-05-11
+
+- Remove `node-fetch` import and dependency (replaced in 0.9.0)
+
+## [0.9.0] — 2026-05-11
+
+- **Replace `node-fetch` with native `fetch`** (Node 18+) — removes external HTTP dependency
+- **Replace `better-sqlite3` with `sql.js`** (WASM) — zero native compilation, fixes `npx` silent failure on systems without build tools
+- Add 404 check in `backend/fetch.js` for robust registry lookups
+- Reduce ATK-009 false positives on `lodash`/`axios`/`express`
+- Fix ATK-002/011 false positives — stricter eval+decode rules, remove self-referential checks
+- Fix ATK-008 `knownRepos` for `vue`
+
+## [0.8.0] — 2026-05-11
+
+- **YAML/JSON policy-as-code engine** — allowlists, severity overrides, suppressions, `fail_on` threshold
+- **Text report generator** (free tier)
+- **PDF report generator** (premium, via `pdf-lib`)
+- **Docker**: multi-stage builds, Compose profiles, health checks, validation script, Makefile
+- Comprehensive README rewrite with comparison table, ATK taxonomy, usage examples, integrations
+- `.npmignore` cleanup for smaller package
+
+## [0.7.6] — 2026-05-10
+
+- **GitHub Action** (`action.yml`) — scan on push/PR with lockfile or package mode, fail-on severity threshold, SIEM/SBOM output support
+- **28 comprehensive tests** covering SIEM exporters (CEF, ECS, Sentinel, QRadar), EU CRA compliance, SBOM (CycloneDX + SPDX), License key gen/validation/edition/tamper/expiry, Report/NIST (HTML, SR-series table, severity badges, all 11 ATK IDs)
+- Fix tampered key test determinism
+
+## [0.7.5] — 2026-05-10
+
+- Add Elastic ECS, Microsoft Sentinel, and IBM QRadar SIEM exporters
+
+## [0.7.4] — 2026-05-10
+
+- Version bump only; no functional changes
+
+## [0.7.3] — 2026-05-10
+
+- Version bump only; no functional changes
+
+## [0.7.2] — 2026-05-10
+
+- Fix duplicate Enterprise Features section in README
+
+## [0.7.1] — 2026-05-10
+
+- Add SAML SSO and REST API sections to README
+
+## [0.7.0] — 2026-05-10
+
+- **Enterprise SAML SSO integration**
+
+## [0.6.0] — 2026-05-10
+
+- **License key enforcement** — HMAC-signed keys with community/premium/enterprise editions
+- Feature gating for SIEM, CRA, REST API, Helm, PostgreSQL backend, SSO, audit logs
+- **PostgreSQL schema** — teams, users, RBAC, audit log, webhooks, API keys, materialized `package_risk` view
+- **FastAPI REST API** — scan/list/retrieve endpoints, webhook CRUD with HMAC-signed dispatch
+- **Webhook engine** — event dispatch with retry, signature verification header
+- **Helm chart** — API + worker + PostgreSQL deployments, secrets, ingress, PVC
+- CLI hardened: premium features blocked without valid license key
+
+## [0.5.0] — 2026-05-10
+
+- **ATK-011 (Transitive Propagation)** detector
+- **SIEM CEF export** for Splunk and ArcSight integration
+- **EU CRA compliance report** — EU Cyber Resilience Act readiness assessment
+- Phase 3 enterprise foundation
+
+## [0.4.1] — 2026-05-10
+
+- Update README for Phase 3 (ATK-011, SIEM, CRA)
+
+## [0.4.0] — 2026-05-10
+
+- **ATK-008 (Tarball Tampering)**, **ATK-009 (Dormant Trigger)**, **ATK-010 (Sandbox Evasion)** detectors
+- **SPDX 2.3 SBOM** support alongside CycloneDX
+- **NIST SP 800-161 compliance report** — supply chain risk management controls
+- Sandbox threat model and gVisor isolation strategy
+
+## [0.3.3] — 2026-05-10
+
+- Fix report HTML/SBOM generation to use `atk_id`, description, package name, dynamic version
+
+## [0.3.2] — 2026-05-10
+
+- Update README for Phase 2 (ATK-008–010, SPDX, NIST)
+
+## [0.3.1] — 2026-05-10
+
+- Fix schema literal newlines
+- Fix CLI SBOM defaults
+- Fix SBOM finding IDs
+
+## [0.3.0] — 2026-05-10
+
+- **ATK-001 (Lifecycle Script)** detector — detects `preinstall`, `postinstall`, `preuninstall` hooks with suspicious commands
+- **ATK-002 (Obfuscated Payload)** detector — hex/base64/decode-driven eval, regex obfuscation
+- **ATK-003 (Credential Harvester)** detector — env var exfiltration, filesystem credential scraping
+- **ATK-004 (Persistence Mechanism)** detector — cron jobs, startup scripts, `postinstall` service installs
+- **ATK-005 (Data Exfiltration)** detector — DNS tunneling, HTTP beaconing, unexpected network calls
+- **ATK-006 (Dependency Confusion)** detector — internal package name heuristics
+- **ATK-007 (Typosquatting)** detector — edit-distance based package name similarity
+
+## [0.2.5] — 2026-05-10
+
+- Fix `.npmignore` to exclude corpus tarballs from published package
+
+## [0.2.4] — 2026-05-10
+
+- Version bump only; no functional changes
+
+## [0.2.2] — 2026-05-10
+
+- **Corpus test suite** — 50 clean packages (0% FP) + 22 malicious PoC (100% detect rate)
+- **HTML report generator** with CLI `--html` flag
+- ATK-007 edit-distance typosquatting implementation
+- Switch from `adm-zip` to `tar` for tgz extraction
+- ATK detectors hardened for fewer false positives
+- `README.md`, `.gitignore`, corpus download scripts
+- **Phase 1 exit**: FP < 2%, passes unit tests + corpus
+
+## [0.2.1] — 2026-05-10
+
+- Version bump only; no functional changes
+
+## [0.2.0] — 2026-05-10
+
+- **Commander.js CLI** with `scan`, `scan-lockfile`, `report` commands
+- **ATK-001–007 detector stubs** via `backend/detectors/index.js` (`runAll`)
+- **SQLite persistence** via `better-sqlite3` — scan auto-save, report by ID/recent
+- **CycloneDX SBOM** — JSON and XML output with ATK vulnerability references
+- `.github/workflows/scan.yml` — GitHub Action example for PR scanning
+- Dependencies: `commander`, `adm-zip`, `acorn`, `node-fetch`
+
+## [0.1.0] — 2026-05-09
+
+- **Initial foundation**
+- Monorepo structure (`cli/`, `backend/`, `docker/`, `docs/`)
+- `LICENSING.md` — Apache-2.0 core + Commons Clause for premium features
+- `CONTRIBUTING.md`
+- `docs/attack-taxonomy.md` — ATK-001 through ATK-011 stubs
+- `backend/license.js` skeleton for HMAC-signed license key gating
+- `backend/db/schema.sql`
+- `docker/Dockerfile.cli` + `docker-compose.yml`
+- npm scripts (lint, test stubs)
+- `.github/workflows/ci.yml`
+- `AGENTS.md` — project instructions

package/README.de.md

@@ -108,6 +108,25 @@ Kein Node.js. Kein `npm install`. Keine globalen Pakete. Funktioniert auf jedem
 
 ---
 
+## 🛡️ Behörden- & SOC 2 L2-bereit
+
+| Funktion | SOC 2 | NIST 800-161 | STIG/FedRAMP |
+|----------|-------|--------------|--------------|
+| Audit-Protokolle (--audit-log) | CC6.8 | AU-2 | ✓ |
+| FIPS-Krypto (--fips) | CC6.1 | SC-13 | ✓ |
+| STIG-Bericht (--stig) | CC7.3 | RA-5 | ✓ |
+| Offline-Cache (--cache-dir) | A1.2 | SC-8 | ✓ |
+| Sigstore-Herleitung | CC6.2 | SI-7 | ✓ |
+| SBOM (SPDX/CycloneDX) | CC7.4 | SA-10 | ✓ |
+
+```bash
+# Vollständig konformer Scan in luftdichten Umgebungen
+npm-scan scan-lockfile --cache-dir /offline/cache --audit-log /var/log/npm-scan.audit --fips
+npm-scan report --stig
+```
+
+---
+
 ## 📖 Verwendungsbeispiele
 
 ### Ein einzelnes Paket scannen
@@ -123,6 +142,9 @@ npm-scan scan express --sbom spdx        # SPDX 2.3
 
 # Eine YAML-Policy anwenden
 npm-scan scan some-package --policy .npm-scan.yml
+
+# Lokales Tarball scannen (kein Registry-Abruf nötig)
+npm-scan scan --file path/to/malicious-package.tgz
 ```
 
 ### Eine Lock-Datei scannen
@@ -133,6 +155,18 @@ npm-scan scan-lockfile
 
 # Eine bestimmte Lock-Datei scannen
 npm-scan scan-lockfile -f ./path/to/package-lock.json
+
+# CI/CD bei hohen oder kritischen Problemen fehlschlagen (Exit-Code 1)
+npm-scan scan-lockfile --fail-on high
+
+# Bei allen Erkenntnissen fehlschlagen (low und höher)
+npm-scan scan-lockfile --fail-on low
+
+# SARIF v2.1-Ausgabe für GitHub Advanced Security / VS Code generieren
+npm-scan scan-lockfile --sarif results.sarif
+
+# Nur Risiko-Score ausgeben (0-10) für Dashboards/Schwellenwerte
+npm-scan scan-lockfile --score-only
 ```
 
 ### Berichte generieren
@@ -153,6 +187,10 @@ npm-scan report -i 42 --nist
 # EU-CRA-Compliance-Tabelle ausgeben
 npm-scan report --cra
 
+# CSV-Export für Excel / Sheets (audit-bereit)
+npm-scan report --csv risks.csv
+npm-scan scan lodash --csv          # CSV nach stdout
+
 # Textbericht (kostenlos)
 npm-scan report --text
 
@@ -576,6 +614,7 @@ node --test test/detectors-corpus.test.js
 
 ### Hilfe benötigt?
 
+- 🔒 Siehe [Sicherheitsrichtlinie](SECURITY.md) für die Offenlegung von Schwachstellen
 - 📖 Lesen Sie den [Projektplan](docs/project-plan.md)
 - 🧬 Überprüfen Sie die [Angriffstaxonomie](docs/attack-taxonomy.md)
 - 🐛 Öffnen Sie ein Issue oder PR
@@ -587,6 +626,19 @@ node --test test/detectors-corpus.test.js
 Apache-2.0 Core + Commons Clause.  
 Siehe [`LICENSING.md`](LICENSING.md) für die genaue Grenze zwischen kostenlosen und Premium-Funktionen.
 
+---
+
+## 👤 Über den Maintainer
+
+**Roongrunchai Chongolnee** — Ersteller und Maintainer von `@lateos/npm-scan`. Zertifizierter Sicherheitsexperte (CISSP, CEH, Cisco Security, AWS Cloud Practitioner) mit einem Jahrzehnt Erfahrung in Infrastruktur- und Anwendungssicherheit bei Philips. Ich habe dieses Tool entwickelt, um der Open-Source-Community eine praktische, detektorgesteuerte Abwehr gegen Supply-Chain-Malware zu bieten — und ich bin bestrebt, es transparent, gemeinschaftseigen und kontinuierlich verbessert zu halten.
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin)](https://www.linkedin.com/in/roongrunchai-chong-c-ab9742108/)
+[![GitHub](https://img.shields.io/badge/GitHub-lateos--ai-181717?style=flat-square&logo=github)](https://github.com/lateos-ai/npm-scan)
+
+Issues, Ideen und Pull-Requests sind immer willkommen — Sicherheit ist am stärksten, wenn wir zusammenarbeiten.
+
+---
+
 ```
 @lateos/npm-scan — npm supply chain security scanner
 Copyright (C) 2026 Lateos

package/README.fr.md

@@ -108,6 +108,25 @@ Pas de Node.js. Pas de `npm install`. Pas de paquets globaux. Fonctionne sur tou
 
 ---
 
+## 🛡️ Prêt pour le Gouvernement et SOC 2 L2
+
+| Fonctionnalité | SOC 2 | NIST 800-161 | STIG/FedRAMP |
+|----------------|-------|--------------|--------------|
+| Journaux d'audit (--audit-log) | CC6.8 | AU-2 | ✓ |
+| Crypto FIPS (--fips) | CC6.1 | SC-13 | ✓ |
+| Rapport STIG (--stig) | CC7.3 | RA-5 | ✓ |
+| Cache hors ligne (--cache-dir) | A1.2 | SC-8 | ✓ |
+| Provenance Sigstore | CC6.2 | SI-7 | ✓ |
+| SBOM (SPDX/CycloneDX) | CC7.4 | SA-10 | ✓ |
+
+```bash
+# Scan conforme en environnement hermétique
+npm-scan scan-lockfile --cache-dir /offline/cache --audit-log /var/log/npm-scan.audit --fips
+npm-scan report --stig
+```
+
+---
+
 ## 📖 Exemples d'utilisation
 
 ### Scanner un seul paquet
@@ -123,6 +142,9 @@ npm-scan scan express --sbom spdx        # SPDX 2.3
 
 # Appliquer une politique YAML
 npm-scan scan some-package --policy .npm-scan.yml
+
+# Scanner un fichier tarball local (pas de téléchargement depuis le registre)
+npm-scan scan --file path/to/malicious-package.tgz
 ```
 
 ### Scanner un fichier de verrouillage
@@ -133,6 +155,18 @@ npm-scan scan-lockfile
 
 # Scanner un fichier de verrouillage spécifique
 npm-scan scan-lockfile -f ./path/to/package-lock.json
+
+# Échouer en CI/CD sur les découvertes de severity haute ou critique (code de sortie 1)
+npm-scan scan-lockfile --fail-on high
+
+# Échouer sur toute découverte (low et au-delà)
+npm-scan scan-lockfile --fail-on low
+
+# Générer une sortie SARIF v2.1 pour GitHub Advanced Security / VS Code
+npm-scan scan-lockfile --sarif results.sarif
+
+# Afficher uniquement le score de risque (0-10) pour les tableaux de bord/seuils
+npm-scan scan-lockfile --score-only
 ```
 
 ### Générer des rapports
@@ -153,6 +187,10 @@ npm-scan report -i 42 --nist
 # Afficher le tableau de conformité EU CRA
 npm-scan report --cra
 
+# Export CSV pour Excel / Sheets (prêt pour audit)
+npm-scan report --csv risks.csv
+npm-scan scan lodash --csv          # CSV vers stdout
+
 # Rapport texte (gratuit)
 npm-scan report --text
 
@@ -576,6 +614,7 @@ node --test test/detectors-corpus.test.js
 
 ### Besoin d'aide ?
 
+- 🔒 Voir la [politique de sécurité](SECURITY.md) pour la divulgation des vulnérabilités
 - 📖 Lire le [plan du projet](docs/project-plan.md)
 - 🧬 Consulter la [taxonomie des attaques](docs/attack-taxonomy.md)
 - 🐛 Ouvrir une issue ou une PR
@@ -587,6 +626,19 @@ node --test test/detectors-corpus.test.js
 Apache-2.0 core + Commons Clause.  
 Voir [`LICENSING.md`](LICENSING.md) pour la limite exacte entre les fonctionnalités gratuites et premium.
 
+---
+
+## 👤 À propos du mainteneur
+
+**Roongrunchai Chongolnee** — créateur et mainteneur de `@lateos/npm-scan`. Professionnel de la sécurité certifié (CISSP, CEH, Cisco Security, AWS Cloud Practitioner) avec une décennie d'expérience en sécurité des infrastructures et des applications chez Philips. J'ai construit cet outil pour offrir à la communauté open-source une défense pratique et pilotée par des détecteurs contre les logiciels malveillants de la chaîne d'approvisionnement — et je m'engage à le maintenir transparent, détenu par la communauté et en amélioration continue.
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin)](https://www.linkedin.com/in/roongrunchai-chong-c-ab9742108/)
+[![GitHub](https://img.shields.io/badge/GitHub-lateos--ai-181717?style=flat-square&logo=github)](https://github.com/lateos-ai/npm-scan)
+
+Les issues, idées et pull requests sont toujours les bienvenus — la sécurité est plus forte quand nous collaborons.
+
+---
+
 ```
 @lateos/npm-scan — npm supply chain security scanner
 Copyright (C) 2026 Lateos

package/README.ja.md

@@ -108,6 +108,25 @@ Node.js不要。`npm install`不要。グローバルパッケージ不要。Doc
 
 ---
 
+## 🛡️ 政府機関・SOC 2 L2 対応
+
+| 機能 | SOC 2 | NIST 800-161 | STIG/FedRAMP |
+|------|-------|--------------|--------------|
+| 監査ログ (--audit-log) | CC6.8 | AU-2 | ✓ |
+| FIPS暗号化 (--fips) | CC6.1 | SC-13 | ✓ |
+| STIGレポート (--stig) | CC7.3 | RA-5 | ✓ |
+| オフラインキャッシュ (--cache-dir) | A1.2 | SC-8 | ✓ |
+| Sigstoreプロvenes | CC6.2 | SI-7 | ✓ |
+| SBOM (SPDX/CycloneDX) | CC7.4 | SA-10 | ✓ |
+
+```bash
+# エアギャップ環境での完全なコンプライアンススキャンを実行
+npm-scan scan-lockfile --cache-dir /offline/cache --audit-log /var/log/npm-scan.audit --fips
+npm-scan report --stig
+```
+
+---
+
 ## 📖 使用例
 
 ### 単一パッケージのスキャン
@@ -123,6 +142,9 @@ npm-scan scan express --sbom spdx        # SPDX 2.3
 
 # YAMLポリシーを適用
 npm-scan scan some-package --policy .npm-scan.yml
+
+# ローカルtarballをスキャン（レジストリからの取得不要）
+npm-scan scan --file path/to/malicious-package.tgz
 ```
 
 ### ロックファイルのスキャン
@@ -133,6 +155,18 @@ npm-scan scan-lockfile
 
 # 特定のロックファイルをスキャン
 npm-scan scan-lockfile -f ./path/to/package-lock.json
+
+# 高重大または致命的な問題でCI/CDを失敗させる（終了コード1）
+npm-scan scan-lockfile --fail-on high
+
+# 任何の発見項目でビルドを失敗させる（low以上）
+npm-scan scan-lockfile --fail-on low
+
+# SARIF v2.1出力を生成（GitHub Advanced Security / VS Code向け）
+npm-scan scan-lockfile --sarif results.sarif
+
+# リスクスコアのみを出力（0-10）（ダッシュボード/閾値向け）
+npm-scan scan-lockfile --score-only
 ```
 
 ### レポートの生成
@@ -576,6 +610,7 @@ node --test test/detectors-corpus.test.js
 
 ### ヘルプが必要ですか？
 
+- 🔒 [セキュリティポリシー](SECURITY.md)で脆弱性の開示方法を確認
 - 📖 [プロジェクト計画](docs/project-plan.md)を読む
 - 🧬 [攻撃分類](docs/attack-taxonomy.md)を確認
 - 🐛 IssueまたはPRを開く
@@ -587,6 +622,19 @@ node --test test/detectors-corpus.test.js
 Apache-2.0コア＋Commons Clause。  
 無料版とプレミアム版機能の正確な境界については[`LICENSING.md`](LICENSING.md)を参照してください。
 
+---
+
+## 👤 メンテナーについて
+
+**Roongrunchai Chongolnee** — `@lateos/npm-scan` の作成者兼メンテナー。CISSP、CEH、Cisco Security、AWS Cloud Practitioner の認定を持つセキュリティ専門家で、Philips で10年間のインフラおよびアプリケーションセキュリティの経験があります。このツールは、オープンソースコミュニティに実用的で検出器駆動型のサプライチェーン型マルウェア防御を提供するために構築しました。透明性、コミュニティ所有、継続的改善に取り組んでいます。
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin)](https://www.linkedin.com/in/roongrunchai-chong-c-ab9742108/)
+[![GitHub](https://img.shields.io/badge/GitHub-lateos--ai-181717?style=flat-square&logo=github)](https://github.com/lateos-ai/npm-scan)
+
+Issue、アイデア、PRはいつでも歓迎します——セキュリティは協力によって最も強力になります。
+
+---
+
 ```
 @lateos/npm-scan — npm supply chain security scanner
 Copyright (C) 2026 Lateos

package/README.md

@@ -107,6 +107,61 @@ No Node.js. No `npm install`. No global packages. Works on any system with Docke
 
 ---
 
+## 🛡️ Government & SOC 2 L2 Ready
+
+| Feature | SOC 2 | NIST 800-161 | STIG/FedRAMP |
+|---------|-------|--------------|--------------|
+| Audit logs (--audit-log) | CC6.8 | AU-2 | ✓ |
+| FIPS crypto (--fips) | CC6.1 | SC-13 | ✓ |
+| STIG report (--stig) | CC7.3 | RA-5 | ✓ |
+| Offline cache (--cache-dir) | A1.2 | SC-8 | ✓ |
+| Sigstore provenance | CC6.2 | SI-7 | ✓ |
+| SBOM (SPDX/CycloneDX) | CC7.4 | SA-10 | ✓ |
+
+```bash
+# Air-gapped scan with full compliance
+npm-scan scan-lockfile --cache-dir /offline/cache --audit-log /var/log/npm-scan.audit --fips
+npm-scan report --stig
+```
+
+[![SOC 2 L2](https://img.shields.io/badge/SOC%202-L2-green?style=flat-square&logo=aicpa)](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/sorhome.html)
+[![FedRAMP](https://img.shields.io/badge/FedRAMP-Moderate-blue?style=flat-square)](https://fedramp.gov/)
+
+---
+
+## ☁️ BYOC — Bring Your Own Cloud
+
+Deploy npm-scan in your VPC with full data sovereignty. No data leaves your infrastructure.
+
+| Feature | Description |
+|---------|-------------|
+| **Self-hosted** | Run on EKS/GKE/AKS in your AWS/Azure/GCP account |
+| **SIEM Export** | CEF/ECS/Sentinel/QRadar to your existing SIEM |
+| **SSO/OIDC** | SAML/OIDC integration with your identity provider |
+| **PDF Reports** | Generate NIST-compliant PDF reports locally |
+| **External DB** | Connect to your existing PostgreSQL/Redis |
+
+```bash
+# Deploy to your VPC with Helm
+git clone https://github.com/lateos-ai/npm-scan.git
+cd npm-scan/deploy/helm
+helm install npm-scan -f values.byoc.yaml .
+
+# BYOC values example (see values.byoc.yaml)
+premium:
+  enabled: true
+  edition: enterprise
+  byoc:
+    enabled: true
+    cloudProvider: aws
+    vpcId: vpc-xxx
+    region: us-east-1
+```
+
+**Pricing**: Enterprise license $10k/yr — self-supported (docs + GitHub issues).
+
+---
+
 ## 📖 Usage Examples
 
 ### Scan a single package
@@ -122,6 +177,9 @@ npm-scan scan express --sbom spdx        # SPDX 2.3
 
 # Apply a YAML policy
 npm-scan scan some-package --policy .npm-scan.yml
+
+# Scan a local tarball (no registry fetch needed)
+npm-scan scan --file path/to/malicious-package.tgz
 ```
 
 ### Scan a lockfile
@@ -132,6 +190,18 @@ npm-scan scan-lockfile
 
 # Scan a specific lockfile
 npm-scan scan-lockfile -f ./path/to/package-lock.json
+
+# Fail CI/CD on high or critical findings (exit code 1)
+npm-scan scan-lockfile --fail-on high
+
+# Fail on any findings (low and above)
+npm-scan scan-lockfile --fail-on low
+
+# Generate SARIF v2.1 output for GitHub Advanced Security / VS Code
+npm-scan scan-lockfile --sarif results.sarif
+
+# Output only risk score (0-10) for dashboards/thresholds
+npm-scan scan-lockfile --score-only
 ```
 
 ### Generate reports
@@ -152,6 +222,10 @@ npm-scan report -i 42 --nist
 # Print EU CRA compliance table
 npm-scan report --cra
 
+# CSV export for Excel / Sheets (audit-ready)
+npm-scan report --csv risks.csv
+npm-scan scan lodash --csv          # CSV to stdout
+
 # Text report (free)
 npm-scan report --text
 
@@ -575,6 +649,7 @@ node --test test/detectors-corpus.test.js
 
 ### Need help?
 
+- 🔒 See [security policy](SECURITY.md) for vulnerability disclosure
 - 📖 Read the [project plan](docs/project-plan.md)
 - 🧬 Review the [attack taxonomy](docs/attack-taxonomy.md)
 - 🐛 Open an issue or PR
@@ -586,6 +661,19 @@ node --test test/detectors-corpus.test.js
 Apache-2.0 core + Commons Clause.  
 See [`LICENSING.md`](LICENSING.md) for the exact boundary between free and premium features.
 
+---
+
+## 👤 About the Maintainer
+
+**Roongrunchai Chongolnee** — creator and maintainer of `@lateos/npm-scan`. Certified security professional (CISSP, CEH, Cisco Security, AWS Cloud Practitioner) with a decade of infrastructure and application security experience at Philips. I built this tool to give the open-source community a practical, detector-driven defense against supply-chain malware — and I'm committed to keeping it transparent, community-owned, and continuously improved.
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin)](https://www.linkedin.com/in/roongrunchai-chong-c-ab9742108/)
+[![GitHub](https://img.shields.io/badge/GitHub-lateos--ai-181717?style=flat-square&logo=github)](https://github.com/lateos-ai/npm-scan)
+
+Issues, ideas, and pull requests are always welcome — security is strongest when we collaborate.
+
+---
+
 ```
 @lateos/npm-scan — npm supply chain security scanner
 Copyright (C) 2026 Lateos

package/README.zh.md

@@ -108,6 +108,25 @@ docker compose --profile pipeline up -d
 
 ---
 
+## 🛡️ 政府与 SOC 2 L2 就绪
+
+| 功能 | SOC 2 | NIST 800-161 | STIG/FedRAMP |
+|------|-------|--------------|--------------|
+| 审计日志 (--audit-log) | CC6.8 | AU-2 | ✓ |
+| FIPS 加密 (--fips) | CC6.1 | SC-13 | ✓ |
+| STIG 报告 (--stig) | CC7.3 | RA-5 | ✓ |
+| 离线缓存 (--cache-dir) | A1.2 | SC-8 | ✓ |
+| Sigstore 溯源 | CC6.2 | SI-7 | ✓ |
+| SBOM (SPDX/CycloneDX) | CC7.4 | SA-10 | ✓ |
+
+```bash
+# 气隙环境下的完整合规扫描
+npm-scan scan-lockfile --cache-dir /offline/cache --audit-log /var/log/npm-scan.audit --fips
+npm-scan report --stig
+```
+
+---
+
 ## 📖 使用示例
 
 ### 扫描单个包
@@ -123,6 +142,9 @@ npm-scan scan express --sbom spdx        # SPDX 2.3
 
 # 应用 YAML 策略
 npm-scan scan some-package --policy .npm-scan.yml
+
+# 扫描本地 tarball（无需从注册表获取）
+npm-scan scan --file path/to/malicious-package.tgz
 ```
 
 ### 扫描锁定文件
@@ -133,6 +155,18 @@ npm-scan scan-lockfile
 
 # 扫描特定锁定文件
 npm-scan scan-lockfile -f ./path/to/package-lock.json
+
+# 在高危或严重问题时使 CI/CD 失败（退出码 1）
+npm-scan scan-lockfile --fail-on high
+
+# 任何发现项都使构建失败（low 及以上）
+npm-scan scan-lockfile --fail-on low
+
+# 生成 SARIF v2.1 输出，用于 GitHub Advanced Security / VS Code
+npm-scan scan-lockfile --sarif results.sarif
+
+# 仅输出风险分数（0-10）用于仪表板/阈值
+npm-scan scan-lockfile --score-only
 ```
 
 ### 生成报告
@@ -153,6 +187,10 @@ npm-scan report -i 42 --nist
 # 打印 EU CRA 合规表格
 npm-scan report --cra
 
+# CSV 导出用于 Excel / Sheets（审计就绪）
+npm-scan report --csv risks.csv
+npm-scan scan lodash --csv          # CSV 输出到标准输出
+
 # 文本报告（免费）
 npm-scan report --text
 
@@ -576,6 +614,7 @@ node --test test/detectors-corpus.test.js
 
 ### 需要帮助？
 
+- 🔒 查看[安全策略](SECURITY.md)了解漏洞披露流程
 - 📖 阅读[项目计划](docs/project-plan.md)
 - 🧬 查看[攻击分类](docs/attack-taxonomy.md)
 - 🐛 提交 issue 或 PR
@@ -587,6 +626,19 @@ node --test test/detectors-corpus.test.js
 Apache-2.0 核心 + Commons Clause。  
 请参阅 [`LICENSING.md`](LICENSING.md) 了解免费版和高级版功能之间的确切界限。
 
+---
+
+## 👤 关于维护者
+
+**Roongrunchai Chongolnee** — `@lateos/npm-scan` 的创建者和维护者。持有 CISSP、CEH、思科安全、AWS 云从业者认证的安全专业人士，在飞利浦拥有十年的基础设施和应用安全经验。我构建这个工具是为了让开源社区拥有一个实用、检测器驱动的供应链恶意软件防御方案——我致力于保持其透明、社区拥有和持续改进。
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin)](https://www.linkedin.com/in/roongrunchai-chong-c-ab9742108/)
+[![GitHub](https://img.shields.io/badge/GitHub-lateos--ai-181717?style=flat-square&logo=github)](https://github.com/lateos-ai/npm-scan)
+
+欢迎提交 issue、想法和 PR——安全在协作中最强大。
+
+---
+
 ```
 @lateos/npm-scan — npm supply chain security scanner
 Copyright (C) 2026 Lateos