BHEESHMA

Runtime Dependency Behavior Monitor for Node.js See what your npm dependencies actually do when they run.

Runtime behavioral telemetry for your dependency tree — a defense-in-depth layer, not a replacement for static/graph scanners.

Quick Start | GitHub Actions | npm install Monitor | Wall of Shame | CLI | Configuration

Why BHEESHMA?

In 2025-2026, the npm ecosystem was hit by a wave of supply-chain attacks:

| Attack | When | Impact | |--------|------|--------| | Shai-Hulud Worm | Sept 2025 | 200+ packages, automated CI/CD hijacking | | axios compromise | Early 2026 | Stolen npm credentials, 10K+ systems, RAT malware | | Mini Shai-Hulud | May 2026 | 84 TanStack packages compromised | | CanisterWorm | 2026 | Self-propagating, exfiltration + persistence |

Static and registry-graph scanners (Socket.dev, Snyk, Dependabot, npm audit) reason about a package before it runs. BHEESHMA adds the complementary view: it observes what your dependencies actually do when they execute — env access, file I/O, network connections, DNS, subprocesses — and attributes each behavior to the responsible package. It surfaces things like:

• Postinstall scripts that read credential files and shell out
• Outbound connections to unexpected hosts (incl. http.get/https.get, raw TCP, DNS)
• Obfuscation indicators in package source
• Behavior deferred across async boundaries (a common evasion)
• Typosquat-shaped names

Zero dependencies. Zero configuration. Zero telemetry — all analysis is local.

Important — read this first: BHEESHMA runs in-process, with the same privileges as the code it watches. It is behavioral telemetry and a detection aid, not a sandbox or an enforcement boundary, and a motivated attacker can evade or disable it. Use it alongside static/graph scanners and install hardening, never as your only control. See docs/THREAT_MODEL.md for exactly what it does and does not catch, and benchmark/FINDINGS.md for measured detection and false-positive rates.

Evaluating for a team? See docs/ENTERPRISE.md for deployment patterns, gating posture, data-handling, assurance, and an evaluation checklist.

Two engines: the default in-process engine is fast and precise per-package but is telemetry, not a boundary. An experimental out-of-process engine (bheeshma-sandbox, Linux + strace) observes syscalls from outside the process — it cannot be evaded by the monitored code and sees native subprocess egress (e.g. curl) the in-process engine is blind to, and can even prevent egress (--block-network). See docs/ARCHITECTURE.md.

30-Second Quick Start

GitHub Actions (recommended)

Add to your CI pipeline — one YAML line:

# .github/workflows/ci.yml
- uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main
  with:
    command: 'npm test'
    fail-level: 'high'

Every PR will now show runtime behavior annotations from bheeshma directly in the GitHub diff view.

npm install Monitor

Watch what packages do during installation:

npx bheeshma install

Basic Monitoring

npx bheeshma -- node app.js

GitHub Actions Integration

BHEESHMA outputs SARIF v2.1.0 — the standard format for GitHub Code Scanning. Findings appear as inline annotations on every PR.

Basic Setup

name: CI
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main
        with:
          command: 'npm test'
          fail-level: 'high'        # fail on HIGH+ (default; see docs/ENTERPRISE.md)
          upload-sarif: 'true'      # upload to Code Scanning

All Options

| Input | Default | Description | |-------|---------|-------------| | command | (required) | Command to run under monitoring | | fail-level | high | Minimum risk level to fail build (critical, high, medium, low) | | config | '' | Path to .bheeshmarc.json | | sarif-output | bheeshma-results.sarif | SARIF output file path | | skip-low | true | Skip LOW-risk signals in SARIF (reduces noise) | | upload-sarif | true | Upload SARIF to GitHub Code Scanning |

Advanced: Multiple Commands

- name: Monitor npm install
  uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main
  with:
    command: 'npm ci'
    fail-level: 'high'

- name: Monitor tests
  uses: bb1nfosec/bheeshma/.github/actions/bheeshma@main
  with:
    command: 'npm test'
    fail-level: 'critical'
    sarif-output: 'bheeshma-test-results.sarif'

npm install Monitor

The #1 attack vector in 2025-2026 is malicious packages that steal CI secrets during npm install. BHEESHMA watches every package's install-time behavior:

# Monitor npm install
npx bheeshma install

# Monitor npm ci (lockfile-strict)
npx bheeshma install ci

# Monitor installing a specific package
npx bheeshma install -- --save-dev some-package

# Output SARIF for CI
npx bheeshma install -- --sarif --output install-results.sarif

What it catches:

• Postinstall scripts running shell commands
• Packages reading .npmrc, .env, or credential files
• Outbound network connections during install
• File writes outside node_modules/

CLI Usage

Monitor any command

# Monitor a Node.js app
bheeshma -- node app.js

# Monitor test suite
bheeshma -- npm test

# Monitor a specific script
bheeshma -- node scripts/build.js

Output formats

# CLI (default, color-coded terminal output)
bheeshma -- node app.js

# JSON (machine-readable, for pipelines)
bheeshma --format json --output report.json -- npm test

# HTML (self-contained dark-themed report)
bheeshma --format html --output report.html -- node app.js

# SARIF (GitHub Code Scanning integration)
bheeshma --format sarif --output results.sarif -- npm test

Enforcement mode

# Exit code 1 if any package is CRITICAL
bheeshma --enforce -- npm test

# Fail on HIGH or above
bheeshma-ci --fail-level high -- npm test

# JSON output + enforcement
bheeshma --enforce --format json --output report.json -- npm test

CI-optimized mode

# bheeshma-ci is a thin wrapper optimized for CI pipelines
# - No ANSI colors, no HTML
# - SARIF output by default
# - Exit codes for policy enforcement
# - GitHub Actions ::error annotations

bheeshma-ci -- npm test
bheeshma-ci --fail-level high --output results.sarif -- npm test

Subcommands

bheeshma install            # Monitor npm install
bheeshma ci -- <command>    # CI-optimized mode
bheeshma -- <command>       # Standard monitoring

Programmatic API

const bheeshma = require('bheeshma');

// Initialize with default settings
bheeshma.init();

// Your application code runs here
require('./your-app');

// Generate report in any format
console.log(bheeshma.generateReport('cli'));
console.log(bheeshma.generateReport('json'));
console.log(bheeshma.generateReport('sarif'));

// Check enforcement policy
const result = bheeshma.enforcePolicy();
if (!result.passed) {
  console.error('Policy violation:', result.message);
  process.exit(1);
}

What BHEESHMA Monitors

| Behavior | Signal Type | Risk | What It Detects | |----------|-------------|------|------------------| | Environment variable access | ENV_ACCESS | Medium | Credential theft, API key exfiltration | | File system reads | FS_READ | Low | Reconnaissance, credential file access | | File system writes | FS_WRITE | High | Persistence, backdoor installation | | Raw TCP connections | NET_CONNECT | High | Reverse shells, C2 communication | | HTTP requests | HTTP_REQUEST | High | Unencrypted data exfiltration | | HTTPS requests | HTTPS_REQUEST | Medium-High | Encrypted data exfiltration | | DNS queries | DNS_QUERY | Medium-High | DNS tunneling, encoded subdomain exfil | | Shell execution | SHELL_EXEC | Critical | Arbitrary code execution | | Obfuscated code | OBFUSCATION_DETECTED | Critical | Hidden payloads, eval/Function | | Blacklisted packages | BLACKLISTED_PACKAGE | Critical | Known malicious packages |

Pattern Detection

BHEESHMA correlates signals to detect complex attack patterns:

| Pattern | Signals | Severity | |---------|---------|----------| | Crypto mining | WALLET_ADDRESS + MINING_POOL env vars | CRITICAL | | Data exfiltration | Credential file read + outbound HTTP | CRITICAL | | Backdoor | Shell exec + reverse connection | CRITICAL | | Credential theft | .env/.npmrc read (context-aware) | HIGH/LOW* | | Typosquat | Package name similar to popular package | HIGH |

*Context-aware: dotenv reading .env = LOW (expected). A random package reading .env = HIGH (suspicious).

Trust Scoring

Each package gets a deterministic trust score [0-100]:

• 80-100 (LOW risk): Minimal or benign behavior
• 60-79 (MEDIUM risk): Moderate activity, review recommended
• 30-59 (HIGH risk): Elevated activity, investigation required
• 0-29 (CRITICAL risk): Highly suspicious, immediate action needed

Configuration

Create .bheeshmarc.json in your project root (fully optional):

{
  "thresholds": {
    "critical": 30,
    "high": 60,
    "medium": 80
  },
  "packageThresholds": {
    "axios": 40,
    "express": 50
  },
  "whitelist": ["express@*", "@types/*"],
  "blacklist": ["malicious-package"],
  "patterns": {
    "enabled": true,
    "detectCryptoMiners": true,
    "detectDataExfiltration": true,
    "detectBackdoors": true
  },
  "performance": {
    "maxSignals": 10000,
    "deduplicateSignals": true
  }
}

Or use bheeshma --config .bheeshmarc.json -- node app.js.

Wall of Shame Dashboard

The bheeshma Wall of Shame is a live threat intelligence dashboard that tracks every known npm supply chain attack and shows how bheeshma catches them.

Live at: bb1nfosec.github.io/bheeshma

What It Shows

• 20+ curated supply chain threats — from the axios compromise to Shai-Hulud to AI-themed phishing packages
• Live OSV feed — real-time npm vulnerabilities from the Open Source Vulnerabilities database
• 100% bheeshma coverage — every tracked threat is caught by bheeshma signals at runtime
• Trend charts — supply chain attack frequency over time (2024-2025)
• Attack type breakdown — malware, typosquats, backdoors, credential theft, protest-ware, data exfiltration
• Signal detection bars — which bheeshma signals fire most across all known attacks

Auto-Updates

The dashboard refreshes daily at 06:00 UTC via GitHub Actions:

1. scripts/fetch-threats.js fetches the latest npm vulnerabilities from the OSV API
2. Merges with the curated local threat database
3. Regenerates dashboard/data/threats.json
4. Commits and pushes the updated data
5. GitHub Pages deploys the updated dashboard automatically

Add Your Own Threats

Edit scripts/fetch-threats.js and add entries to the CURATED_THREATS array. The format:

{
  id: 'T2025-021',
  package: 'package-name',
  version: '1.0.0',
  title: 'Short descriptive title',
  description: 'Full description of the attack',
  severity: 'critical', // critical | high | medium | low
  type: 'backdoor',   // malware | typosquat | backdoor | data-exfil | etc.
  date: '2025-05-01',
  status: 'removed',  // active | removed | patched | unpublished
  downloads: '50K+',
  bheeshma_signals: ['NETWORK_CONNECTION', 'SHELL_EXEC', 'DNS_QUERY'],
  references: ['https://source-url'],
  cve: 'CVE-YYYY-XXXXX' // optional
}

Security Guarantees

• Zero telemetry — No outbound communication (except webhook alerts if configured)
• Local-only — All processing happens on your machine
• Zero dependencies — Pure Node.js, no npm packages required
• Metadata only — Never captures secrets, file contents, or request bodies
• Non-invasive — Observes behavior without modifying it
• Fail-safe — Hook errors never break your application
• Immutable signals — All signals are frozen after creation

Installation

# Global install
npm install -g bheeshma

# Or use with npx (no install needed)
npx bheeshma -- node app.js

Requirements: Node.js >= 14.0.0. No other dependencies.

Architecture

┌──────────────────────────────────────────────────────┐
│                    CLI Layer                         │
│   bheeshma  │  bheeshma-ci  │  bheeshma-install     │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────┐
│              Output Formatters                        │
│   CLI  │  JSON  │  HTML  │  SARIF v2.1.0            │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────┐
│     Policy Engine + Trust Scoring                     │
│   Enforcement │ Thresholds │ Dedup │ Blacklist        │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────┐
│        Pattern + Obfuscation Detection                 │
│   Crypto │ Exfil │ Backdoors │ Typosquat │ Static    │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────┐
│          Attribution Engine                            │
│   Stack trace → outermost node_modules resolution    │
└──────────────────┬───────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────┐
│            Runtime Hooks (6 types)                    │
│   env │ fs │ net │ http │ dns │ child_process         │
├──────────────────────────────────────────────────────┤
│   Worker Thread Support  │  ESM Loader                │
└──────────────────────────────────────────────────────┘

Testing

npm test            # 44/44 unit/integration tests, no network required
node benchmark/run.js   # efficacy benchmark: detection & false-positive rates

All tests run offline with deterministic results.

Runtime telemetry as a complement to static analysis

Static and registry-graph scanners (Socket.dev, Snyk, Dependabot, npm audit) reason about a package before it runs and across the whole registry graph. BHEESHMA adds a different, narrower lens — what a package did during an observed run — and is best used with them, not instead of them.

| | Static / graph scanners | BHEESHMA (runtime telemetry) | |---|---|---| | Reasons about code before execution | ✅ | ❌ (observes what runs) | | Sees runtime behavior of executed code paths | ❌ | ✅ | | Attributes behavior to a specific package | partial | ✅ | | Runs fully offline / no data leaves the machine | varies | ✅ | | Zero dependencies / open source | varies | ✅ | | SARIF / Code Scanning output | ✅ (some) | ✅ | | Catches dormant payloads (don't run during the observed run) | ✅ (can) | ❌ | | Resists an adversary who disables/evades the monitor | n/a | ❌ (in-process) | | Sees native/WASM/process.binding paths | varies | ❌ |

Honest framing: BHEESHMA observes a slice of behavior — what executes, in your environment, through the JS APIs it hooks. It is strong for behavioral visibility and opportunistic malware, and weak against dormant, native, or actively evasive code. Run it as a defense-in-depth layer next to static/graph tooling. Measured detection and false-positive numbers (and their caveats) live in benchmark/FINDINGS.md; the full threat model is in docs/THREAT_MODEL.md.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

We especially want:

• Real-world attack replay scripts (like our demos/)
• False positive reports with reproduction steps
• New hook types (e.g., crypto, fs.watch)
• Performance optimizations for large codebases

License

Apache License 2.0

Credits

Built by security engineers who believe the npm ecosystem deserves a runtime monitoring tool that anyone can use, understand, and trust.

BHEESHMA: Trust, but verify. At runtime.