npm Supply Chain Security
bodadotsh/npm-security-best-practices
Applies safer package manager defaults and dependency vetting to JavaScript and TypeScript projects to reduce supply-chain attack risk.
Scans a repository, its lockfiles and node_modules for known malicious npm package versions and install-time indicators, using a read-only Python scanner.
Install npm Supply Chain Check
$ npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install majiayu000/spellbook npm-supply-chain-check --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/majiayu000/spellbook.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/npm-supply-chain-check .claude/skills/npm-supply-chain-check && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "npm-supply-chain-check" agent skill from https://github.com/majiayu000/spellbook/tree/main/skills/npm-supply-chain-check into .claude/skills/npm-supply-chain-check/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "npm-supply-chain-check", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/majiayu000/spellbook/tree/main/skills/npm-supply-chain-checkType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install majiayu000/spellbook npm-supply-chain-check --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/majiayu000/spellbook.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/npm-supply-chain-check .agents/skills/npm-supply-chain-check && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "npm-supply-chain-check" agent skill from https://github.com/majiayu000/spellbook/tree/main/skills/npm-supply-chain-check into .agents/skills/npm-supply-chain-check/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "npm-supply-chain-check", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install majiayu000/spellbook npm-supply-chain-check --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/majiayu000/spellbook.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/npm-supply-chain-check .cursor/skills/npm-supply-chain-check && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "npm-supply-chain-check" agent skill from https://github.com/majiayu000/spellbook/tree/main/skills/npm-supply-chain-check into .cursor/skills/npm-supply-chain-check/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "npm-supply-chain-check", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/majiayu000/spellbook.git --path skills/npm-supply-chain-check--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install majiayu000/spellbook npm-supply-chain-check --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/majiayu000/spellbook.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/npm-supply-chain-check .gemini/skills/npm-supply-chain-check && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "npm-supply-chain-check" agent skill from https://github.com/majiayu000/spellbook/tree/main/skills/npm-supply-chain-check into .gemini/skills/npm-supply-chain-check/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "npm-supply-chain-check", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install majiayu000/spellbook npm-supply-chain-checkInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/majiayu000/spellbook.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/npm-supply-chain-check .github/skills/npm-supply-chain-check && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "npm-supply-chain-check" agent skill from https://github.com/majiayu000/spellbook/tree/main/skills/npm-supply-chain-check into .github/skills/npm-supply-chain-check/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "npm-supply-chain-check", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install majiayu000/spellbook npm-supply-chain-check --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/majiayu000/spellbook.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/npm-supply-chain-check .opencode/skills/npm-supply-chain-check && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "npm-supply-chain-check" agent skill from https://github.com/majiayu000/spellbook/tree/main/skills/npm-supply-chain-check into .opencode/skills/npm-supply-chain-check/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "npm-supply-chain-check", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
npm-supply-chain-check- GitHub stars
- 287
- Token cost
- ~1.5k tokens
- SKILL.md length
- 700 words
- Files
- 5 (incl. scripts, references)
- Skills in repo
- 97
- Repo updated
- First seen
- Licence
- MIT
At a glance
Scans a repository, its lockfiles and node_modules for known malicious npm package versions and install-time indicators, using a read-only Python scanner.
- Works in 4 steps: Fix the scan boundary → Check intelligence freshness → Run the deterministic scanner → …
- A new npm compromise is in the news and you need to know if a project is affected
- SKILL.md covers Workflow, Operating Contract, Gotchas and Report, plus 1 more section
- Runs Python scripts from its folder; calls python3
What it does
A deterministic, read-only scan decides whether a JavaScript project was exposed to a known npm supply-chain compromise. The agent fixes the scan boundary first, defaulting to the current repository only, and does not widen to your home directory, other worktrees, global package caches or CI systems without being asked. It never reads or prints secret values.
The bundled script scripts/scan_npm_supply_chain.py prints text or JSON, and a --deep option also searches source and built JavaScript for network and campaign strings. Exit code 0 means nothing was found in scope, 1 means affected versions or suspicious indicators turned up, and 2 means the target or indicator data was invalid. A dated baseline in references/shai-hulud-2026-iocs.json is treated as a minimum, so active incidents call for checking current advisories too.
Results are sorted by how much they prove. A bad version in a manifest or lockfile is only an exposure candidate, a copy under node_modules suggests malicious content may have been present, and a matching hash is a high-confidence hit. No findings is not proof of a clean machine, and credential theft is never claimed from a lockfile match alone. It is not a general CVE or licence audit.
When your agent uses it
- A new npm compromise is in the news and you need to know if a project is affected
- A package has a suspicious preinstall script or credential-stealing behavior
- Checking lockfiles and node_modules after a dependency update you do not trust
Example prompts
- “Check this repo for packages from the Shai-Hulud incident and tell me what the lockfile shows.”
- “Run the npm supply chain scan with --deep on ./apps/web and summarize the findings.”
- “Look for compromised keyv and cacheable versions in the lockfiles under ./services.”
Requirements
- Python 3
- A local checkout of the project to scan
Workflow steps
4 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit ed52af7. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 1 file in scripts/ (Python), which the agent can run.
Shell commands in SKILL.md call:
python3
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
npm Supply Chain Check loads about 1.5k tokens when it runs, and up to ~2k if it reads all its reference files. Until then it costs about 107 tokens; SKILL.md has 700 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.
SKILL.md
The full file from majiayu000/spellbook at commit ed52af7, republished under its MIT licence (© majiayu000). 700 words, ~1,530 tokens.
Download SKILL.mdSave it as
.claude/skills/npm-supply-chain-check/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.- name
- npm-supply-chain-check
- description
- Detect known malicious npm package versions and install-time supply-chain indicators in repositories, lockfiles, and node_modules. Use when a user mentions an npm compromise, Shai-Hulud, the Keyv/cacheable incident, suspicious preinstall scripts, credential-stealing packages, or asks whether a JavaScript project was exposed to a package supply-chain attack. Do not use as a general CVE or license audit.
NPM Supply Chain Check
Run an evidence-bounded, read-only scan. Distinguish a dependency reference from proof that malicious code executed, and never read or print secret values.
Workflow
1. Fix the scan boundary
Resolve the exact repository or directory first. Default to the current repository only. Do not silently expand a repo scan to the user's home directory, all worktrees, global package caches, or CI systems.
2. Check intelligence freshness
Read references/shai-hulud-2026-iocs.json when investigating that incident.
It is a dated minimum baseline, not a complete list of every affected community
package. For an active incident, also check current primary sources such as the
npm registry and maintainer/security advisories before declaring a version safe.
Do not modify the bundled baseline during an ordinary scan.
3. Run the deterministic scanner
From this skill directory:
python3 scripts/scan_npm_supply_chain.py <target> --format textUse JSON when another tool will consume the result:
python3 scripts/scan_npm_supply_chain.py <target> --format jsonAdd --deep only when source and built JavaScript files should also be searched
for network and campaign strings. Deep mode still reports paths and indicators,
not surrounding file contents.
Exit codes are machine-checkable:
0: scan completed and found no indicators in the checked scope.1: one or more affected versions or suspicious indicators were found.2: the scan could not complete because its target or IOC data was invalid.
4. Classify the evidence
| Evidence | Meaning |
|---|---|
| Affected version in a manifest or lockfile | Exposure candidate; it does not prove installation or execution. |
Affected version under node_modules | Malicious package content may have been present locally. |
| Known malicious SHA-256 | High-confidence local artifact match. |
| IOC preinstall command or campaign/network string | Strong suspicious-content evidence; inspect provenance and timing. |
| IOC filename with a different hash | Triage lead only; filenames such as setup.mjs can be legitimate. |
| No findings | No known indicators in this scope and baseline; not proof of a clean machine. |
Correlate positive results with installation timestamps, CI run history, package manager logs, and the incident exposure window. Do not claim credential theft solely from a lockfile match.
Show full SKILL.md (378 more words)Show less
Operating Contract
Direct actions: Run read-only local scans, inspect public advisories and registry metadata, and report exact package, version, path, indicator, scope, and confidence. For a positive result, recommend pausing installs and affected CI jobs, isolating suspect runners or machines, preserving logs, and rotating potentially exposed credentials from a known-clean device.
Escalate before: Ask for explicit authorization before any action that would:
- delete
node_modules, caches, logs, or suspicious files; - reinstall dependencies or regenerate lockfiles;
- revoke or rotate npm, GitHub, cloud, Kubernetes, Vault, payment, or chat tokens;
- upload local artifacts or secret-bearing logs to a third party.
Those actions change evidence or external state and require explicit user authorization. If asked to remediate, make a reversible evidence copy or record hashes first and name the exact target before changing it.
Evidence-backed pushback: When a user proposes only upgrading or reinstalling after strong local execution evidence, explain that package replacement does not revoke credentials that may already have been copied. Ground that warning in the scanner finding and the credential classes targeted by the current incident source.
Feedback loop: When a new affected package, version, hash, or stable IOC is confirmed by a credible source, update the JSON baseline and add a regression fixture before treating the detector as current.
Gotchas
- npm unpublishing prevents new downloads but does not remove local installs, package-manager caches, container layers, or CI artifacts.
- Valid npm provenance proves how a package was published, not that the source repository or maintainer account was uncompromised.
- Floating declarations such as
latestdo not prove which historical version was installed. Prefer lockfiles, installed manifests, and install logs. - Transitive packages may be absent from the root
package.json; scan the lockfile andnode_moduleswhen available. - Binary
bun.lockbfiles are reported as unsupported rather than silently treated as clean. Use a text lockfile or Bun tooling to resolve exact versions. - The bundled IOC list is intentionally source-attributed and dated. Extend it through a reviewed data update, not an invented fallback.
Report
Return:
## NPM Supply-Chain Check
- scope: <absolute target>
- baseline: <incident and updated_at>
- result: clean | suspicious | affected | incomplete
- confidence: low | medium | high
## Findings
- <severity> <path> - <package/version or IOC and what it proves>
## Limits
- <missing lockfile, unsupported binary lock, stale baseline, or unchecked external scope>
## Next Actions
1. <smallest safe action>The check is done only when a fresh scanner result is available, all warnings are surfaced, and conclusions stay within the scanned target and IOC baseline.
Resources
scripts/scan_npm_supply_chain.py: read-only repository, lockfile,node_modules, preinstall, filename, hash, and optional deep-string scanner.references/shai-hulud-2026-iocs.json: dated machine-readable baseline for the August 2026 Keyv/cacheable Shai-Hulud incident.
© majiayu000, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 4 other files (scripts, references) in skills/npm-supply-chain-check of majiayu000/spellbook.
- SKILL.md
- agents/openai.yaml
- references/shai-hulud-2026-iocs.json
- scripts/scan_npm_supply_chain.py
- tests/test_scan_npm_supply_chain.py
Open the folder on GitHubat commit ed52af7
Compare with similar skills
npm Supply Chain Check next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| npm Supply Chain Check this skillmajiayu000/spellbook | 287 | — | ~1.5k | Automated safety check: Pass | MIT | |
| npm Supply Chain Securitybodadotsh/npm-security-best-practices | 858 | — | ~1k | Automated safety check: Warn | MIT | |
| Security Analysismicrosoft/haste | 107 | — | ~1k | Automated safety check: Pass | MIT | |
| Tracing Transitive Vulnerabilitiesjeremylongshore/tons-of-skills-marketplace | 2.8k | — | ~2.2k | Automated safety check: Notes | MIT | |
| Dependency Auditbriiirussell/cybersecurity-skills | 413 | — | ~3.2k | Automated safety check: Warn | MIT | |
| CodeQL Security Scantrailofbits/skills | 7.5k | — | ~4.6k | Automated safety check: Notes | CC-BY-SA-4.0 |
Similar skills
- Official
Security Analysis
microsoft/haste
Dependabot and security analysis skill for HASTE. An agent skill from microsoft/haste.
Tracing Transitive Vulnerabilities
jeremylongshore/tons-of-skills-marketplace
Build a dependency-tree map of a project (npm or Python) and trace the path from each known-vulnerable transitive package back to one or more direct dependencies.
Dependency Audit
briiirussell/cybersecurity-skills
Audit project dependencies, frameworks, languages, and dev tools for known vulnerabilities, CVEs, and security anti-patterns.
- Official
CodeQL Security Scan
trailofbits/skills
Scans a codebase for vulnerabilities with CodeQL's data flow and taint tracking in run-all or important-only modes, including data extensions for project-specific sources and sinks.
Vulners API Python SDK
vulnersCom/api
A skill your agent uses when modifying, testing, documenting, or reviewing the Vulners Python SDK.
More from majiayu000/spellbook
All 97 skills in this repoSkill Ecosystem Doctor
majiayu000/spellbook
Audits and repairs how coding-agent Skills are owned, copied and exposed across runtimes, from canonical sources to quarantine and retirement.
AGENTS.md Scaffold
majiayu000/spellbook
Scans a repository for real evidence and proposes, or on request writes, a small stack of root and scoped AGENTS.md files with validation commands and generated-file boundaries.
Product Demo Builder
majiayu000/spellbook
Plans, produces or diagnoses evidence-backed product demo videos: script, capture plan, pacing checks and verified final media built on real product behavior.
Flowguard Task Guard
majiayu000/spellbook
Single entry point that routes long or ambiguous agent tasks, checks live state, bounds autonomous loops and leaves a resumable handoff.
Product Manager Toolkit
majiayu000/spellbook
Product management helpers: a RICE scoring script, an interview transcript analyzer and PRD templates for prioritizing features, synthesizing research and writing requirements.
Repo Agent Context Audit
majiayu000/spellbook
Audits a repository's agent-readable context, from AGENTS.md and CLAUDE.md to skills and PRODUCT or TECH specs, and recommends the smallest useful improvements.
Related
Works with
Categories
Questions about npm Supply Chain Check
What does npm Supply Chain Check do?
Scans a repository, its lockfiles and node_modules for known malicious npm package versions and install-time indicators, using a read-only Python scanner. A deterministic, read-only scan decides whether a JavaScript project was exposed to a known npm supply-chain compromise. The agent fixes the scan boundary first, defaulting to the current repository only, and does not widen to your home directory, other worktrees, global package caches or CI systems without being asked.
When should I use npm Supply Chain Check?
npm Supply Chain Check fits situations like: A new npm compromise is in the news and you need to know if a project is affected; A package has a suspicious preinstall script or credential-stealing behavior; checking lockfiles and node_modules after a dependency update you do not trust.
How do I install npm Supply Chain Check in Claude Code?
Run `npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a claude-code`. Or copy the skill folder (skills/npm-supply-chain-check in majiayu000/spellbook) into .claude/skills/npm-supply-chain-check in your project. Claude Code loads it when a task matches its description.
How do I install npm Supply Chain Check in Codex?
Run `npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a codex`. Or copy the skill folder (skills/npm-supply-chain-check in majiayu000/spellbook) into .agents/skills/npm-supply-chain-check in your project. Codex loads it when a task matches its description.
Can I use npm Supply Chain Check in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add majiayu000/spellbook --skill npm-supply-chain-check -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/npm-supply-chain-check, .gemini/skills/npm-supply-chain-check, .github/skills/npm-supply-chain-check and .opencode/skills/npm-supply-chain-check in your project.
What does npm Supply Chain Check need to run?
Going by SKILL.md and its folder, npm Supply Chain Check needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3; A local checkout of the project to scan.
Does npm Supply Chain Check access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is npm Supply Chain Check safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.
What licence does npm Supply Chain Check use?
npm Supply Chain Check is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does npm Supply Chain Check use?
About 1.5k tokens (SKILL.md is roughly 6.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 518 tokens, read only when the agent opens those files.
What are the alternatives to npm Supply Chain Check?
Skills that share tags, products or a category with npm Supply Chain Check: npm Supply Chain Security (bodadotsh/npm-security-best-practices, 858 stars), Security Analysis (microsoft/haste, 107 stars), Tracing Transitive Vulnerabilities (jeremylongshore/tons-of-skills-marketplace, 2.8k stars) and Dependency Audit (briiirussell/cybersecurity-skills, 413 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains npm Supply Chain Check?
majiayu000 (a GitHub user) maintains it in majiayu000/spellbook, which has 287 GitHub stars. The repository holds 97 skills in this directory. The repository was last updated on October 8, 2026.
Source: majiayu000/spellbook on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.