np-audit 1.2.1 → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Kobler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
+![np-audit](docs/title-image.png)
+
+[![npm version](https://img.shields.io/npm/v/np-audit.svg)](https://www.npmjs.com/package/np-audit)
+[![npm downloads](https://img.shields.io/npm/dm/np-audit.svg)](https://www.npmjs.com/package/np-audit)
+[![GitHub license](https://img.shields.io/github/license/KoblerS/np-audit.svg)](https://github.com/KoblerS/np-audit/blob/main/LICENSE)
+[![CI](https://github.com/KoblerS/np-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/KoblerS/np-audit/actions/workflows/ci.yml)
+
 # 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`.
@@ -53,13 +60,16 @@ Real-world examples include:
 
 ## Install
 
+**Global install (recommended):**
+
 ```bash
-# Global install (recommended for daily use)
 npm install -g np-audit
+```
 
-# Or use directly with npx (no install needed)
+**Or use directly with npx:**
+
+```bash
 npx np-audit scan
-npx np-audit install
 ```
 
 After global install, use the `npa` command:
@@ -76,11 +86,16 @@ npa --version
 
 | Command | Alias | Description |
 |---|---|---|
-| `npa install [package]` | `npa i [package]` | Audit then run `npm install` |
+| `npa install [package]` | `npa i` | 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 |
+| `npa config set <key> <value>` | `npa c set` | Update a config value |
+| `npa alias` | — | Print shell hook for auto-scanning |
+| `npa alias --install` | — | Install hook to shell profile |
+| `npa alias --uninstall` | — | Remove hook from shell profile |
+
+Use `npa <command> -h` for detailed help on any command.
 
 ### Flags
 
@@ -159,6 +174,42 @@ 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.
 
+### Shell Hook (npm alias)
+
+Automatically run `npa scan` before every `npm install` or `npm ci`:
+
+```bash
+# Install the hook to your shell profile (~/.zshrc or ~/.bashrc)
+npa alias --install
+
+# Reload your shell
+source ~/.zshrc  # or ~/.bashrc
+```
+
+Now when you run `npm install` or `npm ci`, npa will scan first:
+
+```bash
+$ npm install lodash
+[npa] Scanning dependencies before npm install...
+✔ No packages with install scripts found.
+[npa] Scan passed. Running npm install...
+```
+
+If issues are found, the install is blocked:
+
+```bash
+$ npm install evil-pkg
+[npa] Scanning dependencies before npm install...
+✗ evil-pkg@1.0.0 BLOCK (score: 9)
+[npa] Scan found issues. Run 'npa install --aware' for interactive mode.
+```
+
+To remove the hook:
+
+```bash
+npa alias --uninstall
+```
+
 #### All config keys
 
 | Key | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "np-audit",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Static obfuscation detector for npm lifecycle scripts — supply chain attack prevention",
   "bin": {
     "npa": "bin/npa.js",

package/src/cli.js

@@ -1,31 +1,33 @@
 'use strict';
 
-const { scan }      = require('./scanner');
-const { runAware, runNpm } = require('./aware');
-const { loadConfig, setGlobalConfig, getGlobalConfigPath, DEFAULT_CONFIG } = require('./config');
-const output        = require('./output');
+const { loadConfig, DEFAULT_CONFIG } = require('./utils/config');
+const commands = require('./commands');
+const output = require('./utils/output');
 
 const VERSION = require('../package.json').version;
 const NAME    = require('../package.json').name;
 
-const HELP = `
+function buildMainHelp() {
+  const cmdList = commands.list();
+  const lines = cmdList.map(cmd => {
+    const aliases = cmd.aliases.length ? ` (alias: ${cmd.aliases.join(', ')})` : '';
+    return `    npa ${cmd.name.padEnd(20)} ${cmd.description}${aliases}`;
+  });
+
+  return `
   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
+${lines.join('\n')}
 
   Flags:
-    --aware, -a   Interactive mode: choose which scripts to allow
+    --review, -r   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
+    --help, -h    Print this help (use <command> -h for command help)
 
   Config keys (stored in ~/.npmauditor.json):
     blockScore       Score threshold for hard block (default: ${DEFAULT_CONFIG.blockScore})
@@ -36,11 +38,12 @@ const HELP = `
     skipScopes       Array of @scopes to skip
     skipPackages     Array of package names to skip
 `;
+}
 
 function parseArgs(argv) {
   const args  = argv.slice(2);
   const flags = {
-    aware:   false,
+    review:  false,
     json:    false,
     noDev:   false,
     verbose: false,
@@ -48,11 +51,12 @@ function parseArgs(argv) {
     help:    false,
   };
   const positionals = [];
+  const rawArgs = [];
 
   for (const arg of args) {
     switch (arg) {
-      case '--aware':
-      case '-a':         flags.aware   = true; break;
+      case '--review':
+      case '-r':         flags.review  = true; break;
       case '--json':     flags.json    = true; break;
       case '--no-dev':   flags.noDev   = true; break;
       case '--verbose':  flags.verbose = true; break;
@@ -67,164 +71,16 @@ function parseArgs(argv) {
 
   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);
+  const commandIndex = args.indexOf(command);
+  if (commandIndex !== -1) {
+    rawArgs.push(...args.slice(commandIndex + 1));
   }
-}
-
-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 })),
-    })),
-  };
+  return { command, args: cmdArgs, rawArgs, flags };
 }
 
 async function main() {
-  const { command, cmdArgs, flags } = parseArgs(process.argv);
+  const parsed = parseArgs(process.argv);
+  const { command, args, rawArgs, flags } = parsed;
   const cwd    = process.cwd();
   const config = loadConfig(cwd);
 
@@ -233,23 +89,26 @@ async function main() {
     return;
   }
 
+  if (flags.help && command) {
+    const cmd = commands.get(command);
+    if (cmd) {
+      process.stdout.write(cmd.help() + '\n');
+      return;
+    }
+  }
+
   if (flags.help || !command) {
-    process.stdout.write(HELP + '\n');
+    process.stdout.write(buildMainHelp() + '\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);
+  const cmd = commands.get(command);
+  if (!cmd) {
+    output.error(`Unknown command: "${command}". Run npa --help for usage.`);
+    process.exit(1);
   }
+
+  await cmd.run({ args, rawArgs, flags, config, cwd });
 }
 
 main().catch(err => {

package/src/commands/alias.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const output = require('../utils/output');
+
+const BASH_HOOK = `# npa npm hook
+npm() { [[ -n "$NPA_RUNNING" ]] && { command npm "$@"; return; }; case "$1" in scan) npa scan "\${@:2}"; return;; install|i|add) command -v npa >/dev/null && { local pkgs=(); for a in "\${@:2}"; do [[ "$a" != -* ]] && pkgs+=("$a"); done; if [[ \${#pkgs[@]} -gt 0 ]]; then npa scan "\${pkgs[@]}" || { echo "[npa] Blocked. Use 'npa install --review'"; return 1; }; else npa scan || { echo "[npa] Blocked. Use 'npa install --review'"; return 1; }; fi; };; ci) command -v npa >/dev/null && { npa scan || { echo "[npa] Blocked. Use 'npa ci --review'"; return 1; }; };; esac; command npm "$@"; }`;
+
+const POWERSHELL_HOOK = `# npa npm hook
+function npm { if($env:NPA_RUNNING){& npm.cmd @args;return}; if($args[0] -eq 'scan'){& npa scan @($args|Select-Object -Skip 1);return}; if($args[0] -in @('install','i','add')){$pkgs=@($args|Where-Object{$_ -notmatch '^-'}|Select-Object -Skip 1); if($pkgs.Count -gt 0){& npa scan @pkgs; if($LASTEXITCODE -ne 0){Write-Host "[npa] Blocked.";return 1}}else{& npa scan; if($LASTEXITCODE -ne 0){Write-Host "[npa] Blocked.";return 1}}}; if($args[0] -eq 'ci'){& npa scan; if($LASTEXITCODE -ne 0){Write-Host "[npa] Blocked.";return 1}}; & npm.cmd @args }`;
+
+module.exports = {
+  name: 'alias',
+  aliases: [],
+  description: 'Shell hook to auto-scan before npm install/ci',
+
+  help() {
+    return `
+  npa alias — Shell hook to auto-scan before npm install/ci
+
+  Usage:
+    npa alias                Print the shell hook
+    npa alias --install      Add hook to shell profile (~/.zshrc or ~/.bashrc)
+    npa alias --uninstall    Remove hook from shell profile
+
+  The hook intercepts npm install/ci/add commands and runs npa scan first.
+  If issues are found, the install is blocked until resolved.
+
+  Examples:
+    npa alias                     Print hook for manual installation
+    npa alias --install           Auto-install to detected shell
+    eval "$(npa alias)"           Load hook in current session only
+`;
+  },
+
+  run({ rawArgs }) {
+    const install = rawArgs.includes('--install') || rawArgs.includes('-i');
+    const uninstall = rawArgs.includes('--uninstall') || rawArgs.includes('-u');
+
+    const { shell, hook, profilePath } = detectShell();
+
+    if (uninstall) {
+      return doUninstall(profilePath);
+    }
+
+    if (install) {
+      return doInstall(hook, profilePath);
+    }
+
+    // Print hook
+    process.stdout.write(hook + '\n');
+    output.log('');
+    output.log(output.dim(`  Add to your shell profile, or run: npa alias --install`));
+  },
+};
+
+function detectShell() {
+  if (process.platform === 'win32') {
+    return { shell: 'powershell', hook: POWERSHELL_HOOK, profilePath: null };
+  }
+
+  const userShell = process.env.SHELL || '';
+  if (userShell.includes('zsh')) {
+    return { shell: 'zsh', hook: BASH_HOOK, profilePath: path.join(os.homedir(), '.zshrc') };
+  }
+
+  return { shell: 'bash', hook: BASH_HOOK, profilePath: path.join(os.homedir(), '.bashrc') };
+}
+
+function doUninstall(profilePath) {
+  if (!profilePath) {
+    output.error('Auto-uninstall not supported for PowerShell. Remove manually from $PROFILE');
+    return;
+  }
+
+  if (!fs.existsSync(profilePath)) {
+    output.warn('No profile found at ' + profilePath);
+    return;
+  }
+
+  const content = fs.readFileSync(profilePath, 'utf8');
+  if (!content.includes('# npa npm hook')) {
+    output.warn('npa hook not found in ' + profilePath);
+    return;
+  }
+
+  const cleaned = content.replace(/\n*# npa npm hook\nnpm\(\)[^\n]+\n*/g, '\n');
+  fs.writeFileSync(profilePath, cleaned);
+  output.success(`Removed npa hook from ${profilePath}`);
+  output.log(output.dim('  Run: source ' + profilePath + ' (or restart your terminal)'));
+}
+
+function doInstall(hook, profilePath) {
+  if (!profilePath) {
+    output.error('Auto-install not supported for PowerShell. Copy the output manually to $PROFILE');
+    process.stdout.write('\n' + hook + '\n');
+    return;
+  }
+
+  const content = fs.existsSync(profilePath) ? fs.readFileSync(profilePath, 'utf8') : '';
+  if (content.includes('# npa npm hook')) {
+    output.warn('npa hook already installed in ' + profilePath);
+    return;
+  }
+
+  fs.appendFileSync(profilePath, '\n\n' + hook + '\n');
+  output.success(`Installed npa hook to ${profilePath}`);
+  output.log(output.dim('  Run: source ' + profilePath + ' (or restart your terminal)'));
+}

package/src/commands/ci.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const { scan } = require('../core/scanner');
+const { runAware, runNpm } = require('../utils/review');
+const output = require('../utils/output');
+
+module.exports = {
+  name: 'ci',
+  aliases: [],
+  description: 'Audit then run npm ci',
+
+  help() {
+    return `
+  npa ci — Audit dependencies then run npm ci
+
+  Usage:
+    npa ci [options]
+
+  Options:
+    --review, -r   Interactive mode: review and allow/deny scripts
+    --json        Output scan results as JSON
+    --no-dev      Skip devDependencies in scan
+    --verbose     Show detailed findings
+    -h, --help    Show this help
+
+  Examples:
+    npa ci            Clean install after audit
+    npa ci --review    Review scripts interactively
+`;
+  },
+
+  async run({ flags, config, cwd }) {
+    const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose });
+    const hasIssues = results.some(r => r.verdict !== 'OK');
+    const silent = config.silent && !hasIssues;
+
+    output.printScanHeader(silent);
+
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(toJsonReport(results), null, 2) + '\n');
+    } else {
+      printResults(results, silent);
+    }
+
+    const blocked = results.filter(r => r.verdict === 'BLOCK');
+
+    if (blocked.length > 0 && !flags.review) {
+      output.error(`${blocked.length} package(s) blocked due to obfuscated install scripts.`);
+      process.exit(1);
+    }
+
+    if (flags.review) {
+      const exit = await runAware({ results, command: 'ci', npmArgs: [], cwd });
+      process.exit(exit);
+    } else {
+      const exit = runNpm('ci', [], cwd);
+      process.exit(exit);
+    }
+  },
+};
+
+function printResults(results, silent = false) {
+  if (silent) return;
+  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 })),
+    })),
+  };
+}

package/src/commands/config.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { setGlobalConfig, getGlobalConfigPath, DEFAULT_CONFIG } = require('../utils/config');
+const output = require('../utils/output');
+
+module.exports = {
+  name: 'config',
+  aliases: ['c'],
+  description: 'View or modify npa configuration',
+
+  help() {
+    return `
+  npa config — View or modify npa configuration
+
+  Usage:
+    npa config get              Show all config values
+    npa config set <key> <val>  Set a config value
+
+  Config keys:
+    blockScore       Score threshold for hard block (default: ${DEFAULT_CONFIG.blockScore})
+    warnScore        Score threshold for warning (default: ${DEFAULT_CONFIG.warnScore})
+    registry         npm registry URL
+    timeout          HTTP timeout in ms (default: ${DEFAULT_CONFIG.timeout})
+    parallelFetches  Concurrent downloads (default: ${DEFAULT_CONFIG.parallelFetches})
+    skipScopes       Array of @scopes to skip (JSON)
+    skipPackages     Array of package names to skip (JSON)
+
+  Examples:
+    npa config get
+    npa config set blockScore 10
+    npa config set skipScopes '["@myorg"]'
+`;
+  },
+
+  async run({ args, config }) {
+    const subcommand = args[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   = args[1];
+      const value = args[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);
+  },
+};