---
name: npm-security
description: 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:

```bash
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>
```

```bash
# 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
```

```bash
# 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

```bash
# 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`:

```ini
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