chain-audit 0.6.1 → 0.6.3

package/README.md

@@ -5,7 +5,10 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/node/v/chain-audit.svg)](https://nodejs.org)
 
-**Fast, zero-dependency CLI to detect supply chain attacks in `node_modules`.**
+**Zero-dependency heuristic scanner CLI to detect supply chain attacks in `node_modules`.**
+
+> **Disclaimer:** chain-audit is a **heuristic scanner** that searches for suspicious patterns in code. It does **not** detect 100% confirmed attacks, but rather flags potentially suspicious behavior that requires **human analysis**. The tool may produce **false positives** (flagging legitimate code as suspicious) and **false negatives** (missing real attacks). It's up to you to review and determine whether findings are actually suspicious or legitimate. Always investigate findings before taking action.  
+> Licensed under **MIT License**, provided "AS IS" without warranty of any kind.
 
 ---
 
@@ -20,9 +23,9 @@
 | Detects obfuscated code | ✅ | ❌ |
 | Zero dependencies | ✅ | N/A |
 | Works offline | ✅ | ❌ |
-| SARIF output (GitHub integration) | ✅ | ❌ |
+| SARIF output (GitHub integration) [experimental] | ✅ | ❌ |
 
-**Use both together** – `npm audit` for known vulnerabilities, `chain-audit` for detecting novel attacks.
+**Use both together** – `npm audit` for known vulnerabilities, `chain-audit` (heuristic scanner) for detecting novel attacks and suspicious patterns.
 
 ## Installation
 
@@ -69,7 +72,10 @@ bun build src/index.js --compile --outfile chain-audit
 ## Quick Start
 
 ```bash
-# Scan current project
+# Recommended: Thorough scan with detailed analysis
+chain-audit --scan-code --detailed
+
+# Scan current project (basic scan)
 chain-audit
 
 # Fail CI on high severity issues
@@ -84,7 +90,7 @@ chain-audit --severity critical,high --fail-on high
 # JSON output for processing
 chain-audit --json
 
-# SARIF output for GitHub Code Scanning
+# SARIF output for GitHub Code Scanning (experimental)
 chain-audit --sarif > results.sarif
 
 # Deep code analysis (slower but more thorough)
@@ -97,7 +103,7 @@ chain-audit --detailed --scan-code
 chain-audit --detailed --json --scan-code
 
 # Ignore specific packages and rules
-chain-audit --ignore-packages "@types/*" --ignore-rules native_binary
+chain-audit --ignore-packages "@types/*" --ignore-rules native_binary,executable_files
 
 # Additional structure integrity checks
 chain-audit --verify-integrity --fail-on high
@@ -120,7 +126,7 @@ chain-audit --check-typosquatting
 | `-l, --lock <path>` | Path to lockfile (auto-detects npm, yarn, pnpm, bun) |
 | `-c, --config <path>` | Path to config file (auto-detects if not specified) |
 | `--json` | Output as JSON |
-| `--sarif` | Output as SARIF (for GitHub Code Scanning) |
+| `--sarif` | Output as SARIF (for GitHub Code Scanning) [experimental] |
 | `-s, --severity <levels>` | Show only specified severity levels (comma-separated, e.g., `critical,high`) |
 | `--fail-on <level>` | Exit 1 if max severity >= level |
 | `--scan-code` | Deep scan JS files for suspicious patterns |
@@ -131,7 +137,7 @@ chain-audit --check-typosquatting
 | `-f, --force` | Force overwrite existing config file (use with `--init`) |
 | **Filtering Options** | |
 | `-I, --ignore-packages <list>` | Ignore packages (comma-separated, supports globs, e.g., `@types/*,lodash`) |
-| `-R, --ignore-rules <list>` | Ignore rule IDs (comma-separated, e.g., `native_binary,install_script`) |
+| `-R, --ignore-rules <list>` | Ignore rule IDs (comma-separated, e.g., `native_binary,executable_files,install_script`) |
 | `-T, --trust-packages <list>` | Trust packages (comma-separated, supports globs, e.g., `esbuild,@swc/*`) |
 | **Scan Options** | |
 | `--max-file-size <bytes>` | Max file size to scan (default: 1048576 = 1MB) |
@@ -145,11 +151,11 @@ chain-audit --check-typosquatting
 
 | Level | Description | Example |
 |-------|-------------|---------|
-| `critical` | Highly likely malicious | Obfuscated code with network access, extraneous packages |
+| `critical` | Highly likely malicious | Obfuscated code with network access, version mismatch |
 | `high` | Strong attack indicators | Suspicious install scripts with network/exec, typosquatting |
 | `medium` | Warrants investigation | Install scripts, shell execution patterns |
 | `low` | Informational | Native binaries, minimal metadata |
-| `info` | Metadata only | Packages with install scripts that match trusted patterns (if configured) |
+| `info` | Metadata only | Packages with install scripts that are in trusted packages list (if configured) |
 
 ### Filtering by Severity
 
@@ -169,12 +175,13 @@ chain-audit --severity low,medium
 chain-audit --severity critical,high --fail-on high
 ```
 
-Issues will be displayed in the order they are found, grouped by the severity levels you specified.
+Issues will be displayed sorted by severity (highest first), then by package name, grouped by severity level. When using `--severity`, only the specified severity levels are shown.
 
 ## Example Output
 
 ```
-chain-audit v0.6.1
+chain-audit v0.6.3
+Zero-dependency heuristic scanner CLI to detect supply chain attacks in node_modules
 ────────────────────────────────────────────────────────────
 
 node_modules: /path/to/project/node_modules
@@ -186,9 +193,9 @@ Found 3 potential issue(s):
 
 ── CRITICAL ──
   ● evil-package@1.0.0
-    reason: extraneous_package
-    detail: Package exists in node_modules but is missing from lockfile
-    fix: Run `npm ci` to reinstall from lockfile
+    reason: version_mismatch
+    detail: Installed version 1.0.0 does not match lockfile version 0.9.5
+    fix: Run `npm ci` to reinstall correct version
 
 ── HIGH ──
   ● suspic-lib@2.0.0
@@ -198,9 +205,9 @@ Found 3 potential issue(s):
 
 ── MEDIUM ──
   ● some-addon@1.2.3
-    reason: install_script
-    detail: Has postinstall script: node-gyp rebuild
-    fix: Review the script to ensure it performs only expected operations
+    reason: extraneous_package
+    detail: Package exists in node_modules but is missing from lockfile
+    fix: Run `npm ci` to reinstall from lockfile
 
 ────────────────────────────────────────────────────────────
 Summary:
@@ -223,10 +230,10 @@ When `--detailed` is enabled, each finding includes:
 - **Matched patterns** (regex) that triggered the detection
 - **Package metadata**: author, repository URL, license, homepage, full file path
 - **Trust assessment**: trust score (0-100) and trust level (low/medium/high)
-- **Evidence**: file paths, line numbers, column numbers, matched text
+- **Evidence**: file paths, line numbers, column numbers (in matches array), matched text
 - **False positive hints**: guidance on legitimate uses that might trigger the detection
-- **Verification steps**: actionable steps for manual investigation
-- **Risk assessment**: for critical findings, notes about known attack patterns (e.g., Shai-Hulud 2.0)
+- **Verification steps**: actionable steps for manual investigation (available for some findings like typosquatting)
+- **Risk assessment**: for high/critical findings, notes about known attack patterns
 
 ### Trust Score Calculation
 
@@ -234,17 +241,17 @@ The trust score (0-100) is calculated based on multiple factors:
 
 | Factor | Points | Description |
 |--------|--------|-------------|
-| **Trusted scope** | +40 | Package is from a scope listed in `trustedPackages` config (if configured) |
-| **Known legitimate** | +50 | Package is in the `trustedPackages` config list (if configured) |
+| **Trusted scope** | +40 | Package is from a scope in the internal trusted scopes list (currently empty by default) |
+| **Known legitimate** | +50 | Package is in the internal known legitimate packages list (currently empty by default) |
 | **Has repository** | +20 | Package has a repository URL in package.json |
 | **Has homepage** | +10 | Package has a homepage URL |
 | **Has author** | +10 | Package has author information |
 | **Has license** | +10 | Package has a license field |
 
-**Note:** By default, no packages are whitelisted. All packages are checked with equal severity. You can configure `trustedPackages` in `.chainauditrc.json` if you need to reduce false positives for specific packages.
+**Note:** Trust score is calculated independently from the `trustedPackages` config option. The `trustedPackages` config option affects severity levels for install scripts, but does not influence the trust score calculation. By default, no packages are whitelisted in the trust score calculation. All packages are checked with equal severity.
 
 **Trust Levels:**
-- **High (70-100)**: Package is likely legitimate (e.g., configured as trusted with repository)
+- **High (70-100)**: Package is likely legitimate (e.g., has repository, homepage, author, and license)
 - **Medium (40-69)**: Package has some trust indicators but needs verification
 - **Low (0-39)**: Package lacks trust indicators, warrants closer investigation
 
@@ -306,10 +313,12 @@ Alternatively, you can manually create a config file in your project root. Suppo
   ],
   "trustedPatterns": {
     "node-gyp rebuild": true,
-    "prebuild-install": true
+    "prebuild-install": true,
+    "node-pre-gyp": true
   },
   "scanCode": false,
   "checkTyposquatting": false,
+  "checkLockfile": false,
   "failOn": "high",
   "severity": ["critical", "high"],
   "format": "text",
@@ -331,9 +340,10 @@ Alternatively, you can manually create a config file in your project root. Suppo
 | `trustedPatterns` | `object` | `{node-gyp rebuild: true, ...}` | Install script patterns considered safe |
 | `scanCode` | `boolean` | `false` | Enable deep code scanning by default |
 | `checkTyposquatting` | `boolean` | `false` | Enable typosquatting detection (disabled by default to reduce false positives) |
+| `checkLockfile` | `boolean` | `false` | Enable lockfile integrity checks (disabled by default due to possible false positives) |
 | `failOn` | `string` | `null` | Default fail threshold (`info\|low\|medium\|high\|critical`) |
 | `severity` | `string[]` | `null` | Show only specified severity levels (e.g., `["critical", "high"]`) |
-| `format` | `string` | `"text"` | Output format: `text`, `json`, or `sarif` |
+| `format` | `string` | `"text"` | Output format: `text`, `json`, or `sarif` (sarif is experimental) |
 | `verbose` | `boolean` | `false` | Show detailed analysis with code snippets and trust scores (Note: CLI flag is `--detailed`, but config uses `verbose` for consistency) |
 | `maxFileSizeForCodeScan` | `number` | `1048576` | Max file size (bytes) to scan for code patterns |
 | `maxNestedDepth` | `number` | `10` | Max depth to traverse nested node_modules |
@@ -372,7 +382,7 @@ jobs:
         run: npm rebuild
 ```
 
-### With SARIF Upload (GitHub Code Scanning)
+### With SARIF Upload (GitHub Code Scanning) [experimental]
 
 ```yaml
 name: Security Scan
@@ -427,9 +437,9 @@ jobs:
 
 **Available inputs:**
 - `node-modules-path` (default: `./node_modules`) – Path to node_modules directory
-- `fail-on` (default: `high`) – Severity threshold to fail on (info|low|medium|high|critical)
+- `fail-on` (default: `critical`) – Severity threshold to fail on (info|low|medium|high|critical)
 - `scan-code` (default: `false`) – Enable deep code scanning (slower)
-- `upload-sarif` (default: `true`) – Upload SARIF to GitHub Code Scanning
+- `upload-sarif` (default: `true`) – Upload SARIF to GitHub Code Scanning [experimental]
 
 The reusable workflow automatically uses `--ignore-scripts` for safe installation.
 
@@ -448,7 +458,7 @@ The reusable workflow automatically uses `--ignore-scripts` for safe installatio
 
 ### CI/CD Security Best Practices
 
-Supply chain attacks like [Shai-Hulud 2.0](https://www.wiz.io/blog/shai-hulud-2-0-aftermath-ongoing-supply-chain-attack) exploited misconfigured GitHub Actions. **Protect your CI/CD:**
+Supply chain attacks have exploited misconfigured GitHub Actions. **Protect your CI/CD:**
 
 ```yaml
 # DANGEROUS - Don't use pull_request_target with checkout
@@ -479,44 +489,52 @@ chain-audit automatically detects and parses:
 
 | Lockfile | Package Manager |
 |----------|-----------------|
-| `package-lock.json` | npm v2/v3 |
-| `npm-shrinkwrap.json` | npm |
+| `package-lock.json` | npm v2/v3 (v1 supported as fallback) |
+| `npm-shrinkwrap.json` | npm (v1/v2/v3) |
 | `yarn.lock` | Yarn Classic & Berry |
 | `pnpm-lock.yaml` | pnpm |
-| `bun.lock` | Bun |
+| `bun.lock` | Bun (text format) |
+| `bun.lockb` | Bun (binary format, not supported - use `bun install --save-text-lockfile` to generate text format) |
 
 ## Detection Rules
 
 ### Critical Severity
-- **extraneous_package** – Package in node_modules not in lockfile
-- **version_mismatch** – Installed version differs from lockfile
+- **version_mismatch** – Installed version differs from lockfile (requires `--check-lockfile`)
+- **pipe_to_shell** – Script pipes content to shell (`| bash`)
+- **potential_env_exfiltration** – Env access + network in install script
+
+### High Severity
 - **corrupted_package_json** – Package has malformed or unreadable package.json
 
 ### High Severity (with `--verify-integrity`)
 - **package_name_mismatch** – Package name in package.json doesn't match expected from path
 - **suspicious_resolved_url** – Package resolved from local file or suspicious URL
-- **pipe_to_shell** – Script pipes content to shell (`| bash`)
-- **potential_env_exfiltration** – Env access + network in install script
-- **env_with_network** – Code accesses env vars and has network/exec capabilities
-- **obfuscated_code** – Base64/hex encoded strings, char code arrays
 
 ### High Severity
-- **network_access_script** – Install script with curl/wget/fetch patterns
+- **network_access_script** – Install script with curl/wget/fetch patterns (high for install scripts, low for trusted install scripts, medium/low for others)
 - **potential_typosquat** – Package name similar to popular package (requires `--check-typosquatting`)
-- **suspicious_name_pattern** – Package name uses character substitution (l33t speak) (requires `--check-typosquatting`)
-- **eval_usage** – Code uses eval() or new Function()
-- **sensitive_path_access** – Code accesses ~/.ssh, ~/.aws, etc.
-- **shell_execution** – Script executes shell commands
+- **suspicious_name_pattern** – Package name uses character substitution (l33t speak) or prefix patterns (requires `--check-typosquatting`) (high for character substitution, medium for prefix patterns)
+- **eval_usage** – Code uses eval() or new Function() (requires `--scan-code`)
+- **sensitive_path_access** – Code accesses ~/.ssh, ~/.aws, etc. (requires `--scan-code`)
+- **shell_execution** – Script executes shell commands (high for install scripts, medium/low for others)
+
+### Critical Severity (with `--scan-code`)
+- **obfuscated_code** – Base64/hex encoded strings, char code arrays
+
+### High Severity (with `--scan-code`)
+- **env_with_network** – Code accesses env vars and has network/exec capabilities (critical severity, or medium for install scripts)
 
 ### Medium Severity
-- **install_script** – Has preinstall/install/postinstall/prepare script
-- **code_execution** – Script runs code via node -e, python -c, etc.
+- **extraneous_package** – Package in node_modules not in lockfile (requires `--check-lockfile`)
+- **install_script** – Has preinstall/install/postinstall script (medium, or info/low for trusted packages/patterns)
+- **code_execution** – Script runs code via node -e, python -c, etc. (high for install scripts, medium/low for others)
 - **child_process_usage** – Code uses child_process module
 - **node_network_access** – Code uses Node.js network APIs (fetch, https, axios)
 - **git_operation_install** – Install script performs git operations
+- **executable_files** – Contains executable files (shell scripts, etc.) - high if outside bin/, medium if in bin/
 
 ### Low/Info Severity
-- **native_binary** – Contains .node, .so, .dll, .dylib files
+- **native_binary** – Contains native module binaries (.node, .so, .dylib files)
 - **no_repository** – No repository URL in package.json
 - **minimal_metadata** – Very short/missing description
 
@@ -525,11 +543,13 @@ chain-audit automatically detects and parses:
 ```javascript
 const { run } = require('chain-audit');
 
-const result = await run(['node', 'script.js', '--json', '--fail-on', 'high']);
+const result = run(['node', 'script.js', '--json', '--fail-on', 'high']);
 
 console.log(result.exitCode);  // 0 or 1
-console.log(result.issues);    // Array of issues found
-console.log(result.summary);   // { counts: {...}, maxSeverity: 'high' }
+console.log(result.issues);    // Array of all issues found (not filtered by --severity)
+console.log(result.summary);   // { counts: {...}, maxSeverity: 'high' } (calculated from filtered issues if --severity is used)
+
+// Note: run() also outputs to console.log() by default. Use --json format to get structured output.
 ```
 
 ## Best Practices
@@ -565,7 +585,7 @@ npm rebuild
 3. **Run in sandboxed CI** – Isolate potentially malicious code
 4. **Combine with npm audit** – chain-audit detects different threats
 5. **Review all findings** – Some may be false positives
-6. **Use `--scan-code` periodically** – More thorough but slower
+6. **Recommended: Use `--scan-code --detailed` for thorough analysis** – Deep code scanning with detailed evidence (slower but most comprehensive)
 7. **Use `--detailed` for manual investigation** – Get code snippets and trust assessment to distinguish false positives (`--verbose` is an alias)
 8. **Keep registry secure** – Use private registry or npm audit signatures
 9. **All packages are checked equally** – No packages are whitelisted by default. Even popular packages like `sharp`, `esbuild`, or `@babel/*` are checked for malicious patterns. This ensures that compromised packages are detected regardless of their reputation.
@@ -598,7 +618,13 @@ Hubert Kasperek
 
 ---
 
-**Disclaimer:** chain-audit is a heuristic scanner created for **educational and research purposes**, provided "AS IS" without warranty of any kind. It may produce false positives and **cannot catch all attacks**.
+**Disclaimer:** chain-audit is a **heuristic scanner** created for **educational and research purposes**, licensed under **MIT License**, provided "AS IS" without warranty of any kind. The author makes no guarantees about the tool's accuracy, completeness, or reliability. 
+
+**Important limitations:**
+- chain-audit does **not** detect 100% confirmed attacks – it scans code for suspicious patterns
+- It may produce **many false positives** – findings require human analysis to determine if they're actually suspicious
+- It **cannot catch all attacks** – sophisticated or novel attack patterns may be missed
+- The tool flags potentially suspicious behavior, but **you are responsible** for reviewing and validating all findings
 
 **The author takes no responsibility for:**
 - False positives or false negatives in detection

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chain-audit",
-  "version": "0.6.1",
-  "description": "Fast, zero-dependency CLI to detect supply chain attacks in node_modules. Scans for malicious install scripts, typosquatting, extraneous packages, and suspicious code patterns.",
+  "version": "0.6.3",
+  "description": "Zero-dependency heuristic scanner CLI to detect supply chain attacks in node_modules. Scans for malicious install scripts, typosquatting, extraneous packages, lockfile integrity, obfuscated code, executable files, and suspicious code patterns.",
   "main": "src/index.js",
   "bin": {
     "chain-audit": "src/index.js"
@@ -31,17 +31,12 @@
   "keywords": [
     "security",
     "supply-chain",
-    "supply-chain-attack",
-    "node-modules",
-    "audit",
-    "malware",
     "dependency",
-    "npm-audit",
-    "postinstall",
-    "typosquatting",
-    "ci",
-    "github-actions",
-    "sarif"
+    "heuristic-scanner",
+    "lockfile",
+    "obfuscation",
+    "static-analysis",
+    "ci"
   ],
   "author": "Hubert Kasperek",
   "license": "MIT",