np-audit 1.3.0 → 1.5.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,11 @@
+![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)
+[![npm package size](https://img.shields.io/npm/unpacked-size/np-audit)](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`.
@@ -32,34 +40,59 @@ Real-world examples include:
 - **[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)
+- **[SAP CAP / cds-dbs (2025)](https://community.sap.com/t5/technology-blog-posts-by-sap/cap-developers-call-to-action-to-mitigate-and-apply-solution-provided-in/ba-p/14387683)** — compromised npm package targeting SAP developers
 
 **`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` |
+| Signal                         | Example                                    |
+| ------------------------------ | ------------------------------------------ |
+| `eval()` / `new Function()`    | `eval(atob("aGVsbG8="))`                   |
+| Indirect eval                  | `(0, eval)(x)`, `globalThis['ev'+'al'](x)` |
+| Function constructor prototype | `({}).constructor.constructor("…")()`      |
+| `setTimeout` with string arg   | `setTimeout('alert(1)', 100)`              |
+| Obfuscator.io patterns         | `var _0x3f2a = [...]`                      |
+| High-entropy strings           | Encrypted/compressed payloads              |
+| Split-literal high entropy     | `'aB' + 'cD' + 'eF' + …` (concat chain)    |
+| Hex / Unicode escape density   | `\x68\x65\x6c\x6c\x6f`, `\u0068\u0065…`    |
 | `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 |
+| Decimal char-code arrays       | `[101,118,97,108,...]` (printable ASCII)   |
+| Base64 / hex decode + exec     | `Buffer.from(x,'base64'\|'hex')` + `eval`  |
+| Shell spawning                 | `require('child_process').exec(...)`       |
+| `worker_threads`               | `new Worker(...)`, eval-class surface      |
+| Concealed `require`            | `require('child' + '_process')`            |
+| Dynamic `require` / `import`   | `require(variable)`, `import(expr)`        |
+| Large hex literal arrays       | `[0x1a, 0x2b, 0x3c, ...]` × 20+            |
+| `process.env` access           | Token/credential harvesting                |
+| Outbound network calls         | `https`/`http`/`net`/`dns`/`tls`/`dgram`/`http2`, `node:` prefix, dynamic `import()` |
+| Missing referenced script      | Command references file not in tarball     |
+| Oversized require graph        | Postinstall reaches >50 files or >5 MB     |
+
+### Coverage beyond the entry script
+
+`npa` doesn't just inspect the single file named in the lifecycle command. It:
+
+- Splits chained commands (`&&`, `||`, `;`, `|`) and analyses each segment, so `node setup.js && node payload.js` no longer hides the second invocation.
+- Handles `node -e "…"`, `sh -c "…"`, `python -c "…"` by analysing the inline code rather than just the wrapper command.
+- Reads shell scripts (`sh ./install.sh`), Python scripts, and shebang-invoked files — not only `node` targets.
+- Follows internal `require('./…')` and `import './…'` chains across the package (with cycle detection and per-package caps), so payloads hidden in helper files like `lib/helper.js` are caught.
+- Records dynamic `require(variable)` / `import(expr)` calls as findings, since they can't be resolved statically.
+- Scans the project's **own** `package.json` lifecycle scripts by default, catching PRs and supply-chain attacks that target the repository itself. Opt out with `scanSelf: false` in `.npmauditor.json`.
+- Inspects **all** lifecycle scripts npm may run, not only `preinstall`/`install`/`postinstall`: also `prepare`, `preprepare`, `postprepare`, and `prepublish`.
 
 ---
 
 ## 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:
@@ -74,24 +107,29 @@ npa --version
 
 ### 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 |
+| Command                        | Alias       | Description                        |
+| ------------------------------ | ----------- | ---------------------------------- |
+| `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` | 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
 
-| 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 |
+| Flag        | Alias | Works with              | Description                                      |
+| ----------- | ----- | ----------------------- | ------------------------------------------------ |
+| `--review`  | `-r`  | `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`
 
@@ -118,23 +156,23 @@ npa s --no-dev       # skip devDependencies
 npa s --verbose      # show fetch progress
 ```
 
-### Interactive `--aware` mode
+### Interactive `--review` mode
 
 Review each install script yourself and decide which to allow:
 
 ```bash
-npa i --aware        # or: npa i -a
-npa ci --aware
+npa i --review        # or: npa i -r
+npa ci --review
 ```
 
 ```
-  npa --aware mode
+  npa --review 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)
+   ▶ [✗ deny ] evil-sdk@1.0.0       postinstall: install.js          DANGER (score: 9)
      [✓ allow] @scope/pkg@2.1.0     postinstall: install.js          WARN (score: 5)
 
   2 allowed  1 denied
@@ -159,26 +197,64 @@ 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 DANGER (score: 9)
+[npa] Scan found issues. Run 'npa install --review' for interactive mode.
+```
+
+To remove the hook:
+
+```bash
+npa alias --uninstall
+```
+
 #### 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 |
+| 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          |
+| `silent`          | `false`                      | Suppress output when no issues found    |
+| `scanSelf`        | `true`                       | Also scan the current project's own `package.json` lifecycle scripts |
 
 ---
 
 ## Exit codes
 
-| Code | Meaning |
-|---|---|
-| `0` | All packages clean or only warnings |
-| `1` | One or more packages blocked |
+| Code | Meaning                             |
+| ---- | ----------------------------------- |
+| `0`  | All packages clean or only warnings |
+| `1`  | One or more packages blocked        |
 
 ---
 
@@ -187,10 +263,13 @@ Config is stored in `~/.npmauditor.json` (global) and can be overridden per proj
 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
+4. **Parse the lifecycle command** — split on `&&` / `||` / `;` / `|`, classify each segment by interpreter (`node`, `sh`, `python`, `bun`, …), and treat `node -e` / `sh -c` arguments as inline code
+5. **Walk the require/import graph** from each entry script — following internal `./` / `../` paths, with cycle detection and per-package caps (50 files / 5 MB)
+6. **Analyze** every reached file statically across all lifecycle scripts (`preinstall`, `install`, `postinstall`, `prepare`, `preprepare`, `postprepare`, `prepublish`) — never execute
+7. **Also scan the current project's own** `package.json` lifecycle scripts (unless `scanSelf: false`)
+8. **Score** findings (0–10 per signal), classify as DANGER / WARN / OK based on config thresholds
+9. **Report** results to terminal or `--json` — each finding is tagged with the file it came from
+10. **Proceed** — run npm normally, or in `--review` mode let you selectively allow scripts
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "np-audit",
-  "version": "1.3.0",
+  "version": "1.5.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,34 @@
 '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 { checkForUpdate } = require('./utils/updateChecker');
+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})
@@ -35,12 +38,14 @@ const HELP = `
     parallelFetches  Concurrent downloads (default: ${DEFAULT_CONFIG.parallelFetches})
     skipScopes       Array of @scopes to skip
     skipPackages     Array of package names to skip
+    maxTarballSize   Max unpacked tarball size (default: ${DEFAULT_CONFIG.maxTarballSize})
 `;
+}
 
 function parseArgs(argv) {
   const args  = argv.slice(2);
   const flags = {
-    aware:   false,
+    review:  false,
     json:    false,
     noDev:   false,
     verbose: false,
@@ -48,11 +53,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 +73,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 commandIndex = args.indexOf(command);
+  if (commandIndex !== -1) {
+    rawArgs.push(...args.slice(commandIndex + 1));
   }
-
-  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 })),
-    })),
-  };
+  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,22 +91,38 @@ 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);
+  }
+
+  // Fire update check only for scan/install/ci commands (non-blocking)
+  const UPDATE_COMMANDS = ['scan', 's', 'install', 'i', 'ci'];
+  const updatePromise = (UPDATE_COMMANDS.includes(command) && !flags.json && !config.silent)
+    ? checkForUpdate(config, VERSION)
+    : Promise.resolve(null);
+
+  await cmd.run({ args, rawArgs, flags, config, cwd });
+
+  // Print update notice after command output
+  const latestVersion = await updatePromise;
+  if (latestVersion) {
+    output.log('');
+    output.log(output.dim(`  Update available: ${VERSION} → ${latestVersion} — run "npm i -g np-audit" to update`));
   }
 }