136 lines
3.6 KiB
Markdown
136 lines
3.6 KiB
Markdown
---
|
|
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
|