Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /microsoft_agent-governance-toolkit /scripts /check_install_scripts.py
| #!/usr/bin/env python3 | |
| # Copyright (c) Microsoft Corporation. | |
| # Licensed under the MIT License. | |
| """Block PRs that introduce npm dependencies with install-time scripts. | |
| Install-time scripts (``preinstall`` / ``install`` / ``postinstall``) are | |
| the primary payload-delivery vector for npm supply-chain attacks: malware | |
| runs *as part of* ``npm install``, before any code review or runtime check. | |
| This scanner refuses adoption of any npm package whose latest version | |
| declares any of those scripts unless the package is on the allow-list. | |
| Two manifest sources are inspected: | |
| 1. ``package.json`` adds — parsed structurally via ``git show <ref>:<path>`` | |
| and JSON-loaded at both base and HEAD. We flag pkg→ver pairs that are | |
| *new at HEAD* (added or version-bumped). This is immune to the | |
| ``++ b/<path>`` diff-line injection class because we never look at the | |
| raw diff stream for this surface. | |
| 2. ``package-lock.json`` / ``npm-shrinkwrap.json`` — closes the | |
| first-iteration bypass: a PR could ship a transitive dep only in the | |
| lockfile while leaving ``package.json`` untouched. We walk every entry | |
| in ``packages`` (npm v7+ lockfile v2/v3) and ``dependencies`` (legacy | |
| v1) and diff base→HEAD. Nested ``node_modules/foo/node_modules/bar`` | |
| keys are correctly unwrapped via ``rsplit("node_modules/", 1)[-1]`` so | |
| the deep entry is *not* silently skipped (which was C5 in the red-team | |
| pass). | |
| Defensive contracts: | |
| * We never trust the lockfile's ``hasInstallScript`` flag as a *skip* | |
| signal. Attackers control lockfile contents end-to-end; the previous | |
| ``if hint is False: continue`` was C4 — a one-line bypass where a hostile | |
| PR could mark its malware package ``hasInstallScript: false`` and never | |
| hit the registry. We always query the registry for every new/bumped | |
| candidate. The lockfile's hint may be *reported* alongside the finding | |
| for context, but it is never used to short-circuit. | |
| * A network failure on a *changed* dependency is fail-closed (recorded as | |
| a finding, returns exit 1). The previous warn-and-pass was a timing | |
| bypass against transient registry outages. | |
| * A wall-clock budget (``--total-deadline-sec``, default 120) caps the | |
| candidate loop. Unscanned candidates after expiry become findings. | |
| * Package and version strings are validated against strict character | |
| classes before being interpolated into the registry URL. All URL | |
| segments are also passed through ``urllib.parse.quote`` so a future | |
| relaxation of the regex cannot silently introduce a traversal. | |
| Usage:: | |
| python scripts/check_install_scripts.py | |
| python scripts/check_install_scripts.py --base origin/main | |
| python scripts/check_install_scripts.py --allow esbuild --allow puppeteer | |
| """ | |
| from __future__ import annotations | |
| import argparse | |
| import sys | |
| from pathlib import PurePosixPath | |
| import _supply_chain_common as common | |
| DEFAULT_MAX_DEPS = 100 | |
| DEFAULT_DEADLINE_SEC = 120 | |
| LIFECYCLE_KEYS = ("preinstall", "install", "postinstall") | |
| ALLOWLIST: frozenset[str] = frozenset({ | |
| "esbuild", | |
| "puppeteer", | |
| "puppeteer-core", | |
| "playwright", | |
| "@playwright/test", | |
| "@playwright/browser-chromium", | |
| "@playwright/browser-firefox", | |
| "@playwright/browser-webkit", | |
| "node-gyp", | |
| "deasync", | |
| "node-sass", | |
| "sass-embedded", | |
| }) | |
| MANIFEST_BASENAMES = ["package.json", "package-lock.json", "npm-shrinkwrap.json"] | |
| def _basename(path: str) -> str: | |
| return PurePosixPath(path.replace("\\", "/")).name | |
| # --------------------------- structural manifest extraction --------------------------- | |
| def _extract_pkgjson_pairs(tree: dict | None) -> dict[str, str]: | |
| """Return the merged exact-pin dep map from a package.json. | |
| Range specifiers (``^``, ``~``, ``workspace:``, ``git+``, etc.) are | |
| filtered out — we can't verify the resolved version from the manifest | |
| alone, and they'll be visible in the lockfile sweep if they actually | |
| resolve to something new. | |
| """ | |
| if not isinstance(tree, dict): | |
| return {} | |
| out: dict[str, str] = {} | |
| for section in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"): | |
| block = tree.get(section) | |
| if not isinstance(block, dict): | |
| continue | |
| for name, ver in block.items(): | |
| if not isinstance(name, str) or not isinstance(ver, str): | |
| continue | |
| ver = ver.strip() | |
| if not ver or any(ver.startswith(p) for p in ( | |
| "workspace:", "file:", "link:", "git+", "github:", "http:", "https:", | |
| "^", "~", ">", "<", "=", "*", | |
| )): | |
| continue | |
| if not common.is_safe_name(name) or not common.is_safe_version(ver): | |
| continue | |
| out[name] = ver | |
| return out | |
| def _unwrap_lockfile_path(key: str) -> str | None: | |
| """Strip nested ``node_modules/x/node_modules/y`` prefixes. | |
| Returns ``"y"`` from ``"node_modules/x/node_modules/y"``, ``"x"`` from | |
| ``"node_modules/x"``, and ``None`` for the workspace root entry | |
| (``""``) or unrecognised shapes. The previous ``if "/node_modules/" in | |
| name: continue`` was the C5 bypass — a transitive package buried at | |
| depth 2+ would be silently dropped. | |
| """ | |
| if not key: | |
| return None | |
| if "node_modules/" not in key: | |
| return None | |
| tail = key.rsplit("node_modules/", 1)[-1] | |
| tail = tail.strip("/") | |
| if not tail: | |
| return None | |
| return tail | |
| def _extract_lockfile_pairs(tree: dict | None) -> dict[tuple[str, str], bool | None]: | |
| """Return ``{(pkg, ver): hasInstallScript_hint}``. | |
| The hint is *informational only* — we always query the registry. It's | |
| reported alongside the finding so reviewers can spot lockfiles that | |
| declare ``hasInstallScript: false`` while the registry says otherwise | |
| (a strong tampering signal). | |
| """ | |
| if not isinstance(tree, dict): | |
| return {} | |
| out: dict[tuple[str, str], bool | None] = {} | |
| # npm v7+ lockfile v2/v3 | |
| packages = tree.get("packages") | |
| if isinstance(packages, dict): | |
| for raw_key, meta in packages.items(): | |
| if not isinstance(raw_key, str) or not isinstance(meta, dict): | |
| continue | |
| name = _unwrap_lockfile_path(raw_key) | |
| if not name: | |
| # The root workspace entry sometimes carries a ``name`` field | |
| # but we don't treat the root as a candidate dep. | |
| continue | |
| ver = meta.get("version") | |
| if not isinstance(ver, str): | |
| continue | |
| ver = ver.strip() | |
| if not common.is_safe_name(name) or not common.is_safe_version(ver): | |
| continue | |
| hint = meta.get("hasInstallScript") | |
| hint = hint if isinstance(hint, bool) else None | |
| # Multiple entries can resolve to the same (name, version); keep | |
| # the *first* hint we see — but if we ever see a True hint, | |
| # surface it (defensive: don't let a later False overwrite True). | |
| existing = out.get((name, ver)) | |
| if existing is True: | |
| continue | |
| out[(name, ver)] = hint | |
| # legacy v1 | |
| deps = tree.get("dependencies") | |
| if isinstance(deps, dict): | |
| _walk_legacy_deps(deps, out) | |
| return out | |
| def _walk_legacy_deps(node: dict, out: dict[tuple[str, str], bool | None]) -> None: | |
| """Recursively walk the legacy v1 ``dependencies`` tree.""" | |
| for name, meta in node.items(): | |
| if not isinstance(name, str) or not isinstance(meta, dict): | |
| continue | |
| ver = meta.get("version") | |
| if isinstance(ver, str) and common.is_safe_name(name) and common.is_safe_version(ver.strip()): | |
| ver = ver.strip() | |
| existing = out.get((name, ver)) | |
| if existing is not True: | |
| out[(name, ver)] = None # v1 doesn't carry the hint | |
| nested = meta.get("dependencies") | |
| if isinstance(nested, dict): | |
| _walk_legacy_deps(nested, out) | |
| # --------------------------- candidate collection --------------------------- | |
| def collect_candidates(base: str) -> list[tuple[str, str, bool | None, str]]: | |
| """Return ``(pkg, ver, hint, source_path)`` tuples for new/bumped npm deps. | |
| De-duplicated on ``(pkg, ver)`` so the same triplet appearing in | |
| multiple manifests only spends one registry call. | |
| """ | |
| by_key: dict[tuple[str, str], tuple[bool | None, str]] = {} | |
| paths = common.changed_manifests(base, MANIFEST_BASENAMES) | |
| for path in paths: | |
| bn = _basename(path) | |
| if bn == "package.json": | |
| base_map = _extract_pkgjson_pairs(common.load_json_at(base, path)) | |
| head_map = _extract_pkgjson_pairs(common.load_json_at("HEAD", path)) | |
| for name, ver in head_map.items(): | |
| if base_map.get(name) == ver: | |
| continue | |
| if (name, ver) in by_key: | |
| continue | |
| by_key[(name, ver)] = (None, path) | |
| elif bn in ("package-lock.json", "npm-shrinkwrap.json"): | |
| base_map = _extract_lockfile_pairs(common.load_json_at(base, path)) | |
| head_map = _extract_lockfile_pairs(common.load_json_at("HEAD", path)) | |
| for (name, ver), hint in head_map.items(): | |
| if (name, ver) in base_map: | |
| continue | |
| if (name, ver) in by_key: | |
| # Prefer a more specific hint (True wins over None/False). | |
| prev_hint, prev_path = by_key[(name, ver)] | |
| if prev_hint is True or hint is None: | |
| continue | |
| by_key[(name, ver)] = (hint, path) | |
| return [(n, v, h, p) for (n, v), (h, p) in by_key.items()] | |
| # --------------------------- registry probe --------------------------- | |
| def fetch_install_scripts(package: str, version: str) -> dict[str, str] | None: | |
| """Return the lifecycle script map for ``package@version``, or ``{}``. | |
| Returns ``None`` only on transient errors (timeout / 5xx / network). | |
| Raises ``LookupError`` on 404 (the version does not exist — typosquat | |
| or unpublished signal). An empty dict means the package has no | |
| lifecycle scripts. | |
| """ | |
| if not common.is_safe_name(package) or not common.is_safe_version(version): | |
| raise LookupError(f"unsafe package/version syntax: {package!r}@{version!r}") | |
| url = f"https://registry.npmjs.org/{common.safe_url_path(package)}/{common.safe_url_path(version)}" | |
| data = common.fetch_json(url) | |
| if data is None: | |
| return None | |
| scripts = data.get("scripts") if isinstance(data, dict) else None | |
| if not isinstance(scripts, dict): | |
| return {} | |
| return {k: v for k, v in scripts.items() if k in LIFECYCLE_KEYS and isinstance(v, str) and v.strip()} | |
| # --------------------------- CLI / main --------------------------- | |
| def _build_parser() -> argparse.ArgumentParser: | |
| p = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0]) | |
| p.add_argument("--base", default="origin/main", | |
| help="Git ref to diff against (default: origin/main)") | |
| p.add_argument("--strict", action="store_true", | |
| help="Treat findings as errors (exit 1). Default warns " | |
| "and exits 0 — workflows should opt into --strict.") | |
| p.add_argument("--max-deps", type=int, default=DEFAULT_MAX_DEPS, | |
| help=f"Refuse to inspect more than this many candidates " | |
| f"(default: {DEFAULT_MAX_DEPS}). ``--max-deps 0`` " | |
| f"disables the cap.") | |
| p.add_argument("--total-deadline-sec", type=int, default=DEFAULT_DEADLINE_SEC, | |
| help=f"Wall-clock budget in seconds (default: {DEFAULT_DEADLINE_SEC}). " | |
| f"Unscanned candidates after expiry become findings.") | |
| p.add_argument("--allow", action="append", default=[], | |
| help="Package name to allow even if it has install scripts " | |
| "(in addition to the built-in allow-list)") | |
| p.add_argument("--explicit", action="append", default=[], | |
| metavar="PKG@VERSION", | |
| help="Skip diff parsing and check exactly these versions") | |
| return p | |
| def main_with_args(argv: list[str]) -> int: | |
| args = _build_parser().parse_args(argv) | |
| allow = set(ALLOWLIST) | {a.strip() for a in args.allow if a.strip()} | |
| candidates: list[tuple[str, str, bool | None, str]] = [] | |
| if args.explicit: | |
| for spec in args.explicit: | |
| try: | |
| pkg, ver = spec.rsplit("@", 1) | |
| except ValueError: | |
| print(f"::error::bad --explicit spec {spec!r}, expected PKG@VERSION", | |
| file=sys.stderr) | |
| return 2 | |
| candidates.append((pkg, ver, None, "(explicit)")) | |
| else: | |
| candidates = collect_candidates(args.base) | |
| if not candidates: | |
| print("OK: no new npm dependencies to check for install scripts.") | |
| return 0 | |
| if args.max_deps > 0 and len(candidates) > args.max_deps: | |
| print( | |
| f"::error::PR adds {len(candidates)} npm dependency candidates, " | |
| f"exceeding --max-deps={args.max_deps}. Refusing to scan: split the " | |
| "PR or pass --max-deps=N explicitly.", | |
| file=sys.stderr, | |
| ) | |
| return 2 | |
| deadline = common.Deadline(budget_seconds=args.total_deadline_sec) | |
| findings: list[str] = [] | |
| print( | |
| f"Checking {len(candidates)} npm package(s) for install-time scripts " | |
| f"(wall-clock budget {args.total_deadline_sec}s)..." | |
| ) | |
| for i, (pkg, ver, hint, source) in enumerate(candidates): | |
| if deadline.expired(): | |
| common.emit_deadline_warning("check_install_scripts", deadline) | |
| unscanned = candidates[i:] | |
| for u_pkg, u_ver, _u_hint, u_src in unscanned: | |
| findings.append( | |
| f" DEADLINE-UNSCANNED: {u_pkg}@{u_ver} could not be verified " | |
| f"before the wall-clock budget expired [{u_src}]" | |
| ) | |
| break | |
| if pkg in allow: | |
| print(f" SKIP (allow-list): {pkg}@{ver} [{source}]") | |
| continue | |
| if not common.is_safe_name(pkg) or not common.is_safe_version(ver): | |
| findings.append( | |
| f" REJECTED: {pkg}@{ver} has unsafe name/version syntax [{source}]" | |
| ) | |
| continue | |
| try: | |
| scripts = fetch_install_scripts(pkg, ver) | |
| except LookupError as e: | |
| findings.append( | |
| f" HARD FAIL: {pkg}@{ver} not found in npm registry — {e} [{source}]" | |
| ) | |
| continue | |
| if scripts is None: | |
| findings.append( | |
| f" UNVERIFIED: {pkg}@{ver} — npm registry transient failure [{source}]" | |
| ) | |
| continue | |
| if scripts: | |
| keys = ", ".join(sorted(scripts.keys())) | |
| hint_note = "" | |
| if hint is False: | |
| hint_note = " (LOCKFILE LIED: hasInstallScript=false but registry disagrees)" | |
| elif hint is True: | |
| hint_note = " (lockfile hint: hasInstallScript=true)" | |
| findings.append( | |
| f" INSTALL-SCRIPT: {pkg}@{ver} declares {keys}{hint_note} [{source}]" | |
| ) | |
| else: | |
| print(f" OK: {pkg}@{ver} declares no install-time scripts") | |
| if findings: | |
| print() | |
| print("Install-script scan FAILED — newly-introduced npm packages run code at install time:") | |
| print() | |
| for f in findings: | |
| print(f) | |
| print() | |
| print("Install-time scripts (preinstall/install/postinstall) are the primary payload") | |
| print("delivery vector for npm supply-chain attacks. Options:") | |
| print(" - Pick an alternative package without install scripts.") | |
| print(" - If the package is well-known and trusted, add it via --allow.") | |
| print(" - Pin to a previous version that did not declare install scripts.") | |
| return 1 if args.strict else 0 | |
| print() | |
| print("OK: all new npm packages are install-script-free.") | |
| return 0 | |
| def main() -> int: | |
| return main_with_args(sys.argv[1:]) | |
| if __name__ == "__main__": | |
| sys.exit(main()) | |
Xet Storage Details
- Size:
- 16.3 kB
- Xet hash:
- af7a5e221121893add02db27f132394161f110b18af5aeba47ac88a7ba127960
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.