pi-config/skills/npm-security/SKILL.md

name, description

name	description
npm-security	Securely install npm/pip/git packages by scanning with SafeDep Vet, checking with npq, and wrapping installs with Socket Firewall

npm Security Checklist

This skill ensures every package install follows your security guardrails.

Prerequisites

Three tools must be installed globally:

npm install -g @safedep/vet @socketsecurity/cli npq

• vet — SafeDep Vet: scans local code for multi-language malware signatures
• sfw — Socket Firewall: wraps npm/pip installs with runtime scanning
• npq — checks package names against typosquatting lists

Verify they're available before proceeding with any install. If missing, inform the user.

---

Workflow by Install Type

npm install (registry package)

1.  vet scan package <name> > /dev/null 2>&1 || echo "VET_CHECK_FAILED"
2.  npq check <name> --json > /tmp/npq_report.json
3.  If either flags the package → STOP, show findings, ask user via ask_user_question
4.  If clear → sfw npm install <name>

# Step 1 — Vet the package metadata
vet scan package "$PKG" --format json 2>&1

# Step 2 — npq typosquatting check
npq check "$PKG" --json

# Step 3 — Install wrapped in Socket Firewall
sfw npm install "$PKG"

git clone / direct download

Vet can scan the local directory after cloning. There's no runtime guard here.

1.  git clone <url>
2.  cd <repo>
3.  vet scan -D . --format json --filter "package.malware == true" > /tmp/vet_report.json
4.  If malware found → STOP, show findings to user
5.  If clean → proceed

# After clone, scan the directory
vet scan -D . --format json --filter "package.malware == true" > /tmp/vet_report.json

# Check for suspicious patterns too
vet scan -D . --format json --filter "package.suspicious == true" >> /tmp/vet_report.json

# If either has findings, warn the user

pip / uv install

# Socket wraps pip too
sfw pip install -r requirements.txt
sfw uv pip install <package>

pi install (npm source)

pi install npm:<package> eventually calls npm install. The sfw wrapper won't intercept Pi's internal npm calls directly, so use the manual pre-check:

1.  vet scan package <name>
2.  npq check <name>
3.  If clear → tell user "safe to pi install npm:<name>"

pi install (git source)

1.  After Pi clones it (check ~/.pi/agent/git/), vet scan that directory
2.  Show user the results

---

Checking npmrc Security Settings

Periodically verify these are in ~/.npmrc:

min-release-age=7
ignore-scripts=true
allow-git=root

If missing, inform the user and offer to add them.

---

When Something Flags

• STOP — do not continue with the install
• Read the flagged findings
• Present them to the user via ask_user_question with the findings attached
• Let the user decide: proceed anyway, investigate further, or abort

---

Commands Reference

Tool	Purpose	Key Command
vet	Malware scan (local dir)	vet scan -D . --format json
vet	Package metadata scan	vet scan package <name> --format json
npq	Typosquatting check	npq check <name> --json
sfw	Safe npm install	sfw npm install <name>
sfw	Safe pip install	sfw pip install <name>

Limitations

• vet cannot scan packages that haven't been downloaded yet (npm metadata scan is lighter)
• sfw only intercepts when used explicitly (sfw npm install), not plain npm install
• Pi's internal package manager may not respect sfw — pre-checks are essential
• nix packages go through Nix's own trust model, not these tools