majiayu000/spellbook / skills/npm-supply-chain-check
npm-supply-chain-check
VerifiedDetect 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
| agents/openai.yaml | config | 257 B |
| references/shai-hulud-2026-iocs.json | config | 2.0 KB |
| scripts/scan_npm_supply_chain.pyexecutable | script | 19.4 KB |
| tests/test_scan_npm_supply_chain.py | script | 7.6 KB |
scripts/scan_npm_supply_chain.py
View on GitHub#!/usr/bin/env python3
"""Read-only scanner for known npm supply-chain compromise indicators."""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import re
import sys
from pathlib import Path
LOCKFILE_NAMES = {
"package-lock.json",
"npm-shrinkwrap.json",
"pnpm-lock.yaml",
"yarn.lock",
"bun.lock",
"bun.lockb",
}
DEPENDENCY_SECTIONS = {
"dependencies",
"devDependencies",
"optionalDependencies",
"peerDependencies",
}
SKIP_DIRS = {".git", ".hg", ".svn"}
DEEP_TEXT_SUFFIXES = {".js", ".mjs", ".cjs", ".json", ".yaml", ".yml"}
MAX_DEEP_FILE_BYTES = 5 * 1024 * 1024
def relative(path: Path, root: Path) -> str:
try:
return path.relative_to(root).as_posix()
except ValueError:
return path.as_posix()
def load_iocs(path: Path) -> dict[str, object]:
with path.open(encoding="utf-8") as handle:
data = json.load(handle)
if data.get("schema_version") != 1:
raise ValueError("IOC file must use schema_version 1")
for required in ("incident", "affected_packages", "files", "strings"):
if required not in data:
raise ValueError(f"IOC file is missing {required!r}")
return data
def affected_map(iocs: dict[str, object]) -> dict[str, set[str]]:
result: dict[str, set[str]] = {}
packages = iocs["affected_packages"]
if not isinstance(packages, list):
raise ValueError("affected_packages must be a list")
for entry in packages:
if not isinstance(entry, dict):
raise ValueError("affected package entries must be objects")
name = entry.get("name")
versions = entry.get("versions")
if not isinstance(name, str) or not isinstance(versions, list):
raise ValueError("affected package entries require name and versions")
if not all(isinstance(version, str) for version in versions):
raise ValueError(f"affected versions for {name} must be strings")
result[name] = set(versions)
return result
def file_ioc_map(iocs: dict[str, object]) -> dict[str, set[str]]:
result: dict[str, set[str]] = {}
entries = iocs["files"]
if not isinstance(entries, list):
raise ValueError("files must be a list")
for entry in entries:
if not isinstance(entry, dict):
raise ValueError("file IOC entries must be objects")
name = entry.get("name")
hashes = entry.get("sha256")
if not isinstance(name, str) or not isinstance(hashes, list):
raise ValueError("file IOC entries require name and sha256")
if not all(isinstance(digest, str) for digest in hashes):
raise ValueError(f"sha256 values for {name} must be strings")
result[name] = {digest.lower() for digest in hashes}
return result
def add_finding(
findings: list[dict[str, str]],
seen: set[tuple[str, str, str, str]],
*,
severity: str,
kind: str,
path: str,
evidence: str,
) -> None:
key = (severity, kind, path, evidence)
if key in seen:
return
seen.add(key)
findings.append(
{
"severity": severity,
"kind": kind,
"path": path,
"evidence": evidence,
}
)
def exact_version_hits(
package: str,
version: str,
affected: dict[str, set[str]],
) -> bool:
return package in affected and version in affected[package]
def dependency_spec_mentions(spec: object, bad_versions: set[str]) -> str | None:
if not isinstance(spec, str):
return None
for version in sorted(bad_versions):
if re.search(rf"(?<![0-9A-Za-z]){re.escape(version)}(?![0-9A-Za-z])", spec):
return version
return None
def scan_manifest(
path: Path,
root: Path,
affected: dict[str, set[str]],
preinstall_markers: list[str],
findings: list[dict[str, str]],
seen: set[tuple[str, str, str, str]],
warnings: list[str],
) -> None:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
warnings.append(f"could not parse {relative(path, root)}: {exc}")
return
if not isinstance(data, dict):
warnings.append(f"ignored non-object manifest {relative(path, root)}")
return
name = data.get("name")
version = data.get("version")
rel_path = relative(path, root)
if isinstance(name, str) and isinstance(version, str):
if exact_version_hits(name, version, affected):
installed = "node_modules" in path.parts
add_finding(
findings,
seen,
severity="critical" if installed else "high",
kind="installed_affected_package" if installed else "affected_package_manifest",
path=rel_path,
evidence=f"{name}@{version}",
)
for section in sorted(DEPENDENCY_SECTIONS):
dependencies = data.get(section)
if not isinstance(dependencies, dict):
continue
for package, spec in dependencies.items():
if not isinstance(package, str) or package not in affected:
continue
matched = dependency_spec_mentions(spec, affected[package])
if matched is not None:
add_finding(
findings,
seen,
severity="medium",
kind="affected_dependency_declaration",
path=rel_path,
evidence=f"{section}: {package} declares {spec!r} and references {matched}",
)
scripts = data.get("scripts")
preinstall = scripts.get("preinstall") if isinstance(scripts, dict) else None
if isinstance(preinstall, str):
for marker in preinstall_markers:
if marker.lower() in preinstall.lower():
add_finding(
findings,
seen,
severity="high",
kind="ioc_preinstall",
path=rel_path,
evidence=f"preinstall references {marker}",
)
def package_name_from_lock_path(lock_path: str) -> str | None:
marker = "node_modules/"
if marker not in lock_path:
return None
tail = lock_path.rsplit(marker, 1)[1]
parts = tail.split("/")
if not parts or not parts[0]:
return None
if parts[0].startswith("@") and len(parts) >= 2:
return f"{parts[0]}/{parts[1]}"
return parts[0]
def walk_package_lock_entries(data: dict[str, object]):
packages = data.get("packages")
if isinstance(packages, dict):
for lock_path, entry in packages.items():
if not isinstance(lock_path, str) or not isinstance(entry, dict):
continue
name = entry.get("name")
if not isinstance(name, str):
name = package_name_from_lock_path(lock_path)
version = entry.get("version")
if isinstance(name, str) and isinstance(version, str):
yield name, version
def recurse(dependencies: object):
if not isinstance(dependencies, dict):
return
for name, entry in dependencies.items():
if not isinstance(name, str) or not isinstance(entry, dict):
continue
version = entry.get("version")
if isinstance(version, str):
yield name, version
yield from recurse(entry.get("dependencies"))
yield from recurse(data.get("dependencies"))
def scan_json_lock(
path: Path,
root: Path,
affected: dict[str, set[str]],
findings: list[dict[str, str]],
seen: set[tuple[str, str, str, str]],
warnings: list[str],
) -> None:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
warnings.append(f"could not parse lockfile {relative(path, root)}: {exc}")
return
if not isinstance(data, dict):
warnings.append(f"ignored non-object lockfile {relative(path, root)}")
return
for package, version in walk_package_lock_entries(data):
if exact_version_hits(package, version, affected):
add_finding(
findings,
seen,
severity="high",
kind="affected_lockfile_version",
path=relative(path, root),
evidence=f"{package}@{version}",
)
def scan_text_lock(
path: Path,
root: Path,
affected: dict[str, set[str]],
findings: list[dict[str, str]],
seen: set[tuple[str, str, str, str]],
warnings: list[str],
) -> None:
if path.name == "bun.lockb":
warnings.append(
f"unsupported binary lockfile {relative(path, root)}; resolve it with Bun tooling"
)
return
try:
text = path.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as exc:
warnings.append(f"could not read lockfile {relative(path, root)}: {exc}")
return
blocks = re.split(r"\n\s*\n", text)
for package, versions in affected.items():
package_token = re.escape(package)
for version in versions:
direct = re.compile(
rf"(?<![0-9A-Za-z._/-])/?{package_token}@(?:npm:)?{re.escape(version)}"
)
hit = direct.search(text) is not None
if not hit and path.name == "pnpm-lock.yaml":
legacy_pnpm = re.compile(
rf"(?m)^\s*['\"]?/{package_token}/{re.escape(version)}"
rf"(?:_[^:'\"\s]+)?['\"]?:"
)
hit = legacy_pnpm.search(text) is not None
if not hit and path.name == "yarn.lock":
yarn_descriptor = re.compile(
rf"(?<![0-9A-Za-z._/-]){package_token}@"
)
yarn_version = re.compile(
rf"(?:^|\n)\s*version\s*(?::\s*|\s+['\"]){re.escape(version)}"
rf"(?:['\"])?\s*(?:\n|$)"
)
for block in blocks:
header = block.splitlines()[0] if block.splitlines() else ""
if yarn_descriptor.search(header) and yarn_version.search(block):
hit = True
break
if hit:
add_finding(
findings,
seen,
severity="high",
kind="affected_lockfile_version",
path=relative(path, root),
evidence=f"{package}@{version}",
)
def sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
while chunk := handle.read(1024 * 1024):
digest.update(chunk)
return digest.hexdigest()
def scan_ioc_file(
path: Path,
root: Path,
hashes: set[str],
findings: list[dict[str, str]],
seen: set[tuple[str, str, str, str]],
warnings: list[str],
) -> None:
rel_path = relative(path, root)
try:
digest = sha256(path)
except OSError as exc:
warnings.append(f"could not hash {rel_path}: {exc}")
return
if digest in hashes:
add_finding(
findings,
seen,
severity="critical",
kind="known_malicious_sha256",
path=rel_path,
evidence=f"sha256={digest}",
)
else:
severity = "high" if path.name.lower() in {"math_symbol.js", "math_init.js"} else "low"
add_finding(
findings,
seen,
severity=severity,
kind="ioc_filename_hash_mismatch",
path=rel_path,
evidence=f"filename matched but sha256={digest} is not in the baseline",
)
def scan_deep_strings(
path: Path,
root: Path,
string_iocs: list[tuple[str, str]],
findings: list[dict[str, str]],
seen: set[tuple[str, str, str, str]],
warnings: list[str],
) -> None:
try:
if path.stat().st_size > MAX_DEEP_FILE_BYTES:
return
text = path.read_text(encoding="utf-8", errors="ignore")
except OSError as exc:
warnings.append(f"could not inspect {relative(path, root)}: {exc}")
return
for kind, value in string_iocs:
if value in text:
add_finding(
findings,
seen,
severity="high",
kind=f"ioc_{kind}_string",
path=relative(path, root),
evidence=f"contains indicator {value!r}",
)
def build_result(target: Path, ioc_path: Path, deep: bool) -> dict[str, object]:
iocs = load_iocs(ioc_path)
affected = affected_map(iocs)
file_iocs = file_ioc_map(iocs)
preinstall_raw = iocs.get("preinstall_markers", [])
if not isinstance(preinstall_raw, list) or not all(
isinstance(value, str) for value in preinstall_raw
):
raise ValueError("preinstall_markers must be a list of strings")
preinstall_markers = list(preinstall_raw)
strings_raw = iocs["strings"]
if not isinstance(strings_raw, list):
raise ValueError("strings must be a list")
string_iocs: list[tuple[str, str]] = []
for entry in strings_raw:
if not isinstance(entry, dict):
raise ValueError("string IOC entries must be objects")
kind = entry.get("kind")
value = entry.get("value")
if not isinstance(kind, str) or not isinstance(value, str):
raise ValueError("string IOC entries require string kind and value")
string_iocs.append((kind, value))
findings: list[dict[str, str]] = []
seen: set[tuple[str, str, str, str]] = set()
warnings: list[str] = []
scanned = {"files": 0, "manifests": 0, "lockfiles": 0, "ioc_filenames": 0}
for dirpath, dirnames, filenames in os.walk(target, followlinks=False):
dirnames[:] = sorted(name for name in dirnames if name not in SKIP_DIRS)
current = Path(dirpath)
for filename in sorted(filenames):
path = current / filename
if path.is_symlink():
continue
scanned["files"] += 1
if filename == "package.json":
scanned["manifests"] += 1
scan_manifest(
path,
target,
affected,
preinstall_markers,
findings,
seen,
warnings,
)
if filename in LOCKFILE_NAMES:
scanned["lockfiles"] += 1
if filename in {"package-lock.json", "npm-shrinkwrap.json"}:
scan_json_lock(path, target, affected, findings, seen, warnings)
else:
scan_text_lock(path, target, affected, findings, seen, warnings)
if filename in file_iocs:
scanned["ioc_filenames"] += 1
scan_ioc_file(
path,
target,
file_iocs[filename],
findings,
seen,
warnings,
)
is_baseline = path.resolve() == ioc_path
if deep and not is_baseline and filename != "bun.lockb" and (
path.suffix.lower() in DEEP_TEXT_SUFFIXES or filename in LOCKFILE_NAMES
):
scan_deep_strings(path, target, string_iocs, findings, seen, warnings)
severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
findings.sort(
key=lambda item: (
severity_order.get(item["severity"], 9),
item["path"],
item["kind"],
item["evidence"],
)
)
incident = iocs["incident"]
if not isinstance(incident, dict):
raise ValueError("incident must be an object")
return {
"schema_version": 1,
"target": target.as_posix(),
"baseline": {
"name": incident.get("name"),
"updated_at": incident.get("updated_at"),
"source_url": incident.get("source_url"),
"ioc_file": ioc_path.as_posix(),
},
"result": "affected" if any(item["severity"] in {"critical", "high"} for item in findings)
else "suspicious" if findings
else "clean",
"findings": findings,
"warnings": sorted(set(warnings)),
"scanned": scanned,
"deep": deep,
"limits": [
"Results are limited to the target and bundled IOC baseline.",
"A dependency reference does not prove package installation or code execution.",
"No secret values are read or printed intentionally.",
],
}
def print_text(result: dict[str, object]) -> None:
baseline = result["baseline"]
scanned = result["scanned"]
if not isinstance(baseline, dict) or not isinstance(scanned, dict):
raise ValueError("invalid result structure")
print("# NPM Supply-Chain Check")
print(f"scope: {result['target']}")
print(f"baseline: {baseline.get('name')} ({baseline.get('updated_at')})")
print(f"result: {result['result']}")
print(
"scanned: "
f"{scanned.get('files')} files, {scanned.get('manifests')} manifests, "
f"{scanned.get('lockfiles')} lockfiles, {scanned.get('ioc_filenames')} IOC filenames"
)
print()
print("## Findings")
findings = result["findings"]
if not isinstance(findings, list) or not findings:
print("- none")
else:
for finding in findings:
if not isinstance(finding, dict):
continue
print(
f"- {str(finding.get('severity')).upper()} "
f"[{finding.get('kind')}] {finding.get('path')}: {finding.get('evidence')}"
)
print()
print("## Warnings")
warnings = result["warnings"]
if not isinstance(warnings, list) or not warnings:
print("- none")
else:
for warning in warnings:
print(f"- {warning}")
print()
print("## Limits")
limits = result["limits"]
if isinstance(limits, list):
for limit in limits:
print(f"- {limit}")
def parse_args() -> argparse.Namespace:
default_iocs = Path(__file__).resolve().parent.parent / "references" / "shai-hulud-2026-iocs.json"
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("target", nargs="?", default=".", help="directory to scan")
parser.add_argument(
"--ioc-file",
type=Path,
default=default_iocs,
help="reviewed schema_version 1 IOC JSON file",
)
parser.add_argument("--format", choices=("text", "json"), default="text")
parser.add_argument(
"--deep",
action="store_true",
help="also scan small JavaScript, JSON, YAML, and lockfiles for IOC strings",
)
return parser.parse_args()
def main() -> int:
args = parse_args()
target = Path(args.target).expanduser().resolve()
ioc_path = args.ioc_file.expanduser().resolve()
if not target.is_dir():
print(f"error: target is not a directory: {target}", file=sys.stderr)
return 2
try:
result = build_result(target, ioc_path, args.deep)
except (OSError, ValueError, json.JSONDecodeError) as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if args.format == "json":
print(json.dumps(result, indent=2, sort_keys=True))
else:
print_text(result)
return 1 if result["findings"] else 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |