From 72a8f372902359ac606d7238dc59a744f73de67f Mon Sep 17 00:00:00 2001
From: pdmarf <135653545+pdmarf@users.noreply.github.com>
Date: Sat, 18 Apr 2026 16:32:34 +0100
Subject: [PATCH] Add check-npm-sudo-config docs and print audit log on setup

- README: add Scripts section explaining what check-npm-sudo-config.sh
  does, what it checks, and that it is audit-only
- setup.sh: print check-npm-sudo-config log to terminal after initial scan

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 36 ++++++++++++++++++++++++++++++++++++
 setup.sh  |  7 ++++++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 803df8e..677f348 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,42 @@
 
 A collection of security scripts versioned in this repository.
 
+## Scripts
+
+### check-npm-sudo-config.sh
+
+Audits npm configuration on a Linux VM to detect cases where npm is — or has
+been — configured to install packages into system-owned directories, which
+requires `sudo` and creates security risks.
+
+Running `sudo npm install -g` can deposit files owned by root inside your npm
+prefix or cache directory. This causes permission errors for non-root users,
+encourages further `sudo npm` use to work around them, and means malicious
+packages run with root privileges during installation.
+
+**This script is audit-only — it makes no changes.** It reports issues and
+prints recommended commands, but you must run those commands yourself.
+
+The script checks:
+
+1. **npm prefix** — flags if it points to `/usr` or `/usr/local` (system-wide, requires sudo)
+2. **~/.npmrc** — checks whether the prefix is explicitly pinned to a user directory
+3. **PATH** — confirms the npm prefix bin directory is in PATH
+4. **Root-owned files in the prefix** — evidence of past `sudo npm` usage
+5. **Shell history** — scans `.bash_history` / `.zsh_history` for `sudo npm` commands
+6. **npm cache ownership** — root-owned cache files cause EACCES errors
+7. **Node version manager** — detects nvm, fnm, or n; flags if n is present without N_PREFIX set
+
+If issues are found, it sends a Telegram alert and logs results to `logs/`.
+
+The correct fix is to configure npm to install global packages into a
+user-owned directory (e.g. `~/.npm-global`) so that `sudo` is never needed:
+
+```bash
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
 ## Claude Code Context
 
 This project is maintained with Claude Code. The working directory on macOS is:
diff --git a/setup.sh b/setup.sh
index 3540678..8065dbe 100755
--- a/setup.sh
+++ b/setup.sh
@@ -99,6 +99,11 @@ echo ""
 echo "Running initial security scan..."
 bash "$SCRIPT_DIR/npm-security-check.sh" >> "$SCRIPT_DIR/logs/npm-security-check-$(date +%Y%m%d).log" 2>&1 && echo "npm-security-check: done." || echo "npm-security-check: issues found — check Telegram."
 bash "$SCRIPT_DIR/check-nextjs-rce.sh" >> "$SCRIPT_DIR/logs/check-nextjs-rce-$(date +%Y%m%d).log" 2>&1 && echo "check-nextjs-rce: done." || echo "check-nextjs-rce: issues found — check Telegram."
-bash "$SCRIPT_DIR/check-npm-sudo-config.sh" >> "$SCRIPT_DIR/logs/check-npm-sudo-config-$(date +%Y%m%d).log" 2>&1 && echo "check-npm-sudo-config: done." || echo "check-npm-sudo-config: issues found — check Telegram."
+NPM_SUDO_LOG="$SCRIPT_DIR/logs/check-npm-sudo-config-$(date +%Y%m%d).log"
+bash "$SCRIPT_DIR/check-npm-sudo-config.sh" >> "$NPM_SUDO_LOG" 2>&1 && echo "check-npm-sudo-config: done." || echo "check-npm-sudo-config: issues found — check Telegram."
+echo ""
+echo "--- npm sudo config audit results ---"
+cat "$NPM_SUDO_LOG"
+echo "-------------------------------------"
 echo ""
 echo "Initial scan complete. Check Telegram for any alerts."