@lateos/npm-scan

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?

Privacy first. All scanning happens on your machine. No code leaves your environment. No telemetry. No cloud dependency.

✨ Key Features

⚡ Quick Start

# 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

No install? No problem:

npx @lateos/npm-scan scan commander

📖 Usage Examples

Scan a single package

# Default JSON output with all findings
npm-scan scan axios

# 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

Scan a lockfile

# 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

# 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)

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 for full evasion surface documentation and PoC examples.

📊 Output & Reports

Formats

Sample output

{
  "scanId": 1,
  "findings": [
    {
      "id": "ATK-003",
      "severity": "high",
      "title": "Credential harvesting",
      "evidence": "process.env.NPM_TOKEN detected in postinstall.js:17"
    }
  ]
}

⚙️ Configuration & Advanced Usage

Policy-as-code

Define allowlists, severity overrides, suppressions, and fail thresholds in a YAML file:

# .npm-scan.yml
allowlist:
  - lodash
  - chalk

severity_overrides:
  - id: ATK-001
    severity: medium

suppress:
  - atk_id: ATK-009
  - package: some-package

fail_on: high

npm-scan scan target --policy .npm-scan.yml

Environment variables

Premium licensing

# 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>

🔗 Integrations

GitHub Action

Scan your lockfile on every PR. Add to .github/workflows/scan.yml:

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)

Docker

# Pull and run
docker pull ghcr.io/lateos/npm-scan:cli
docker run --rm ghcr.io/lateos/npm-scan:cli scan lodash

# Full pipeline with Compose (Redis-based queue)
docker compose --profile pipeline up -d

# CLI with persistent storage
docker compose --profile cli up -d

Multi-arch images available for linux/amd64 and linux/arm64.

CI/CD

# Fail the build if critical findings exist
npm-scan scan express --policy .npm-scan.yml || exit 1

🗺️ Roadmap & Enterprise Features

Free tier (shipped)

• 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 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

git clone https://github.com/lateos/npm-scan.git
npm install
npm test

Need help?

• 📖 Read the project plan
• 🧬 Review the attack taxonomy
• 🐛 Open an issue or PR

📄 License

Apache-2.0 core + Commons Clause.
See 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:

npx @lateos/npm-scan scan lodash