devguard-scanner 0.1.0__py3-none-any.whl

devguard/analyzers/surfaces/npm.py

@@ -0,0 +1,304 @@
+"""npm / yarn / pnpm / bun: lifecycle scripts and package-manager config that executes code (TC-04.1, TC-04.2)."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+
+import yaml
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.command import resolve_ref
+from devguard.analyzers.surfaces.common import assess_and_trigger, load_jsonc
+from devguard.analyzers.surfaces.deps import package_json_dependency_findings
+from devguard.core.models import Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.rules.catalog import build_finding, rule
+
+R_LIFECYCLE = rule(
+    "DG-NPM-LIFECYCLE-001",
+    "Install-time lifecycle script",
+    "low",
+    "high",
+    "lifecycle",
+    "TC-04.1",
+    "package.json defines a script that npm/yarn/pnpm run automatically during install (preinstall, install, "
+    "postinstall, prepare). It runs with the user's privileges as soon as dependencies are installed.",
+    "Native modules and git-hook managers use install scripts legitimately.",
+    "Review the script and every file it runs before installing. Use `npm install --ignore-scripts` if unsure.",
+)
+R_NPMRC_EXEC = rule(
+    "DG-NPM-RC-EXEC-001",
+    "npm configuration executes code",
+    "high",
+    "high",
+    "lifecycle",
+    "TC-04.2",
+    "The project .npmrc sets an option that injects code or replaces the script shell "
+    "(node-options, script-shell, onload-script, init-module).",
+)
+R_REGISTRY = rule(
+    "DG-NPM-REGISTRY-001",
+    "Package registry overridden",
+    "low",
+    "medium",
+    "deps",
+    "TC-11.4",
+    "The project points the package manager at a non-default registry. Every package then comes from that "
+    "server, which can serve modified packages.",
+    "Companies use private registries (Artifactory, Verdaccio, GitHub Packages).",
+)
+R_YARNPATH = rule(
+    "DG-YARN-PATH-001",
+    "Repository supplies the Yarn executable",
+    "high",
+    "medium",
+    "lifecycle",
+    "TC-04.2",
+    "`yarnPath` makes every `yarn` command run a JavaScript file from this repository instead of the installed Yarn.",
+    "Yarn Berry projects commit `.yarn/releases/yarn-<version>.cjs` legitimately; any other path is unusual. "
+    "Compare a committed release with the official one for that version.",
+)
+R_YARN_PLUGIN = rule(
+    "DG-YARN-PLUGIN-001",
+    "Yarn loads a plugin from the repository",
+    "medium",
+    "medium",
+    "lifecycle",
+    "TC-04.2",
+    "`.yarnrc.yml` loads a plugin file from this repository; plugins run inside every yarn command.",
+    "Official plugins live in `.yarn/plugins/@yarnpkg/`.",
+)
+R_PNPMFILE = rule(
+    "DG-PNPM-HOOKS-001",
+    "pnpm hook file runs on every install",
+    "medium",
+    "high",
+    "lifecycle",
+    "TC-04.2",
+    "`.pnpmfile.cjs` is executed by pnpm during every install to rewrite package manifests.",
+)
+R_BUN_PRELOAD = rule(
+    "DG-BUN-PRELOAD-001",
+    "Bun preloads a repository script",
+    "medium",
+    "high",
+    "lifecycle",
+    "TC-04.2",
+    "`bunfig.toml` preloads a script before every `bun` run or test.",
+)
+
+LIFECYCLE = ("preinstall", "install", "postinstall", "preprepare", "prepare", "postprepare", "prepublish")
+_BENIGN_LIFECYCLE = re.compile(
+    r"^\s*(npx\s+)?(husky(\s+install)?(\s+\S+)?|node-gyp\s+rebuild|node-gyp-build|patch-package|tsc(\s+-[-\w]+(\s+\S+)?)*"
+    r"|ngcc|prebuild-install(\s+\|\|\s+node-gyp\s+rebuild)?|opencollective[-\s]postinstall.*|simple-git-hooks"
+    r"|lefthook\s+install|electron-builder\s+install-app-deps|svelte-kit\s+sync|nuxt\s+prepare|prisma\s+generate"
+    r"|is-ci\s+\|\|\s+husky(\s+install)?|lerna\s+bootstrap|npm\s+run\s+build)\s*$"
+)
+_DEFAULT_REGISTRIES = ("https://registry.npmjs.org", "https://registry.yarnpkg.com", "https://registry.npmmirror.com")
+_CANONICAL_YARN = re.compile(r"^\.yarn/releases/yarn-[\w.-]+\.c?js$")
+_CANONICAL_PLUGIN = re.compile(r"^\.yarn/plugins/@yarnpkg/plugin-[\w-]+\.c?js$")
+_RAW_IP_OR_HTTP = re.compile(r"^http://|^https?://(\d{1,3}\.){3}\d{1,3}")
+
+
+class NpmAnalyzer:
+    name = "npm"
+
+    def applies(self, fv: FileView) -> bool:
+        return (
+            fv.text is not None
+            and fv.name in ("package.json", ".npmrc", ".yarnrc.yml", ".yarnrc", ".pnpmfile.cjs", "bunfig.toml")
+            and not fv.record.vendored
+        )
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        if fv.name == "package.json":
+            return self._package_json(fv, ctx)
+        if fv.name == ".npmrc":
+            return self._npmrc(fv, ctx)
+        if fv.name == ".yarnrc.yml":
+            return self._yarnrc_yml(fv, ctx)
+        if fv.name == ".yarnrc":
+            return self._yarnrc_v1(fv, ctx)
+        if fv.name == ".pnpmfile.cjs":
+            ctx.add_trigger("pnpm-hooks", fv.rel, line=1, label=".pnpmfile.cjs", autorun=True, references=[fv.rel])
+            ctx.autoloaded.add(fv.rel)
+            return [build_finding(R_PNPMFILE.id, [fv.evidence_at_line(1)])]
+        return self._bunfig(fv, ctx)
+
+    def _package_json(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        out: list[Finding] = []
+        root = load_jsonc(fv, ctx, out)
+        if root is None or not isinstance(root.value, dict):
+            return out
+        base = [fv.parent]
+        scripts = root.get("scripts")
+        table: dict[str, str] = {}
+        for name, node in scripts.items() if scripts else []:
+            if not isinstance(node.value, str):
+                continue
+            table[name] = node.value
+            autorun = name in LIFECYCLE
+            if autorun:
+                benign = bool(_BENIGN_LIFECYCLE.match(node.value))
+                out.append(
+                    build_finding(
+                        R_LIFECYCLE.id,
+                        [fv.evidence_at_line(node.line)],
+                        severity=Severity.INFO if benign else None,
+                        detail=f"{name}: {make_excerpt(node.value, limit=160)}",
+                    )
+                )
+            out += assess_and_trigger(
+                ctx,
+                fv,
+                node.value,
+                node.line,
+                kind="npm-lifecycle" if autorun else "npm-script",
+                label=name,
+                autorun=autorun,
+                context=f"npm script {name!r}",
+                base_dirs=base,
+            )
+        ctx.npm_scripts[fv.parent] = table
+        out += package_json_dependency_findings(root, fv)
+        return out
+
+    def _npmrc(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        out: list[Finding] = []
+        for i, line in enumerate(fv.lines, 1):
+            s = line.strip()
+            if not s or s.startswith((";", "#")) or "=" not in s:
+                continue
+            key, value = (p.strip() for p in s.split("=", 1))
+            lkey = key.lower()
+            if lkey in ("node-options", "script-shell", "onload-script", "init-module", "shell"):
+                out.append(
+                    build_finding(
+                        R_NPMRC_EXEC.id, [fv.evidence_at_line(i)], detail=f"{key}={make_excerpt(value, limit=120)}"
+                    )
+                )
+                ref = resolve_ref(value.split()[-1] if value.split() else value, ctx.inventory, [fv.parent])
+                ctx.add_trigger(
+                    "npmrc",
+                    fv.rel,
+                    line=i,
+                    label=key,
+                    command=make_excerpt(value),
+                    autorun=True,
+                    references=[ref] if ref else [],
+                )
+            elif lkey == "registry" or lkey.endswith(":registry"):
+                out += _registry_finding(fv, i, key, value)
+        return out
+
+    def _yarnrc_yml(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        try:
+            data = yaml.safe_load(fv.text or "") or {}
+        except yaml.YAMLError as exc:
+            ctx.warn("npm", f"invalid YAML: {exc}", fv.rel)
+            return []
+        if not isinstance(data, dict):
+            return []
+        out: list[Finding] = []
+        yarn_path = data.get("yarnPath")
+        if isinstance(yarn_path, str):
+            out += self._yarn_path(fv, ctx, yarn_path, _line_of(fv, "yarnPath"))
+        for plugin in data.get("plugins") or []:
+            path = plugin.get("path") if isinstance(plugin, dict) else plugin if isinstance(plugin, str) else None
+            if not isinstance(path, str):
+                continue
+            line = _line_of(fv, path)
+            ref = resolve_ref(path, ctx.inventory, [fv.parent])
+            canonical = bool(_CANONICAL_PLUGIN.match(path))
+            out.append(
+                build_finding(
+                    R_YARN_PLUGIN.id,
+                    [fv.evidence_at_line(line)],
+                    severity=Severity.INFO if canonical else None,
+                    detail=f"Plugin: {path}",
+                )
+            )
+            ctx.add_trigger(
+                "yarn-plugin",
+                fv.rel,
+                line=line,
+                label=path,
+                autorun=True,
+                references=[ref] if ref and not canonical else [],
+            )
+        reg = data.get("npmRegistryServer")
+        if isinstance(reg, str):
+            out += _registry_finding(fv, _line_of(fv, "npmRegistryServer"), "npmRegistryServer", reg)
+        return out
+
+    def _yarnrc_v1(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        out: list[Finding] = []
+        for i, line in enumerate(fv.lines, 1):
+            m = re.match(r'^\s*(yarn-path|registry|"registry")\s+"?([^"\s]+)"?', line)
+            if not m:
+                continue
+            if m.group(1) == "yarn-path":
+                out += self._yarn_path(fv, ctx, m.group(2), i)
+            else:
+                out += _registry_finding(fv, i, "registry", m.group(2))
+        return out
+
+    def _yarn_path(self, fv: FileView, ctx: AnalysisContext, path: str, line: int | None) -> list[Finding]:
+        canonical = bool(_CANONICAL_YARN.match(path))
+        ref = resolve_ref(path, ctx.inventory, [fv.parent])
+        ctx.add_trigger(
+            "yarn-path",
+            fv.rel,
+            line=line,
+            label="yarnPath",
+            command=make_excerpt(path),
+            autorun=True,
+            references=[ref] if ref and not canonical else [],
+        )
+        return [
+            build_finding(
+                R_YARNPATH.id,
+                [fv.evidence_at_line(line)],
+                severity=Severity.INFO if canonical else None,
+                confidence=None,
+                detail=f"yarnPath: {make_excerpt(path, limit=120)}",
+            )
+        ]
+
+    def _bunfig(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        try:
+            data = tomllib.loads(fv.text or "")
+        except tomllib.TOMLDecodeError as exc:
+            ctx.warn("npm", f"invalid TOML: {exc}", fv.rel)
+            return []
+        out: list[Finding] = []
+        preloads: list[str] = []
+        for section in (data, data.get("test") or {}, data.get("run") or {}):
+            value = section.get("preload") if isinstance(section, dict) else None
+            preloads += [value] if isinstance(value, str) else [v for v in value or [] if isinstance(v, str)]
+        for p in preloads:
+            line = _line_of(fv, p)
+            ref = resolve_ref(p, ctx.inventory, [fv.parent])
+            out.append(build_finding(R_BUN_PRELOAD.id, [fv.evidence_at_line(line)], detail=f"Preload: {p}"))
+            ctx.add_trigger("bun-preload", fv.rel, line=line, label=p, autorun=True, references=[ref] if ref else [])
+        return out
+
+
+def _registry_finding(fv: FileView, line: int | None, key: str, value: str) -> list[Finding]:
+    v = value.strip().strip("\"'").rstrip("/")
+    if not v or v.startswith(_DEFAULT_REGISTRIES):
+        return []
+    sev = Severity.MEDIUM if _RAW_IP_OR_HTTP.match(v) else None
+    return [
+        build_finding(
+            R_REGISTRY.id, [fv.evidence_at_line(line)], severity=sev, detail=f"{key} = {make_excerpt(v, limit=120)}"
+        )
+    ]
+
+
+def _line_of(fv: FileView, needle: str) -> int | None:
+    for i, line in enumerate(fv.lines, 1):
+        if needle in line:
+            return i
+    return None

devguard/analyzers/surfaces/python_pkg.py

@@ -0,0 +1,138 @@
+"""Python packaging and interpreter auto-execution points (TC-04.3)."""
+
+from __future__ import annotations
+
+import tomllib
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.core.models import Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.core.safefs import normalize_rel
+from devguard.rules.catalog import build_finding, rule
+
+R_SETUP_PY = rule(
+    "DG-PY-SETUP-001",
+    "setup.py executes during installation",
+    "info",
+    "high",
+    "lifecycle",
+    "TC-04.3",
+    "setup.py is a Python program that runs when the package is built or installed from source. Its "
+    "contents are checked by the Python rules and linked to this trigger.",
+)
+R_PTH = rule(
+    "DG-PY-PTH-EXEC-001",
+    ".pth file executes code at interpreter start-up",
+    "high",
+    "medium",
+    "lifecycle",
+    "TC-04.3",
+    "Lines starting with `import` in a .pth file run every time Python starts if the file is placed in "
+    "site-packages. Committing such a file is unusual.",
+    "Some packages (e.g. coverage, editable installs) ship .pth hooks inside site-packages.",
+)
+R_STARTUP = rule(
+    "DG-PY-STARTUP-HOOK-001",
+    "Python start-up customization module",
+    "medium",
+    "medium",
+    "lifecycle",
+    "TC-04.3",
+    "sitecustomize.py / usercustomize.py are imported automatically by every Python process whose path "
+    "includes this directory.",
+)
+R_BACKEND = rule(
+    "DG-PY-INTREE-BACKEND-001",
+    "Build backend loaded from the repository",
+    "medium",
+    "medium",
+    "lifecycle",
+    "TC-04.3",
+    "pyproject.toml sets `backend-path`, so pip runs a build backend that lives inside this repository "
+    "when installing from source.",
+    "A few projects bootstrap their own backend this way.",
+)
+R_CONFTEST = rule(
+    "DG-PY-CONFTEST-001",
+    "pytest conftest.py runs during test collection",
+    "info",
+    "high",
+    "lifecycle",
+    "TC-04.3",
+    "conftest.py is imported automatically by pytest (and by IDE test discovery). Its contents are checked "
+    "by the Python rules and linked to this trigger.",
+)
+
+
+class PythonPackagingAnalyzer:
+    name = "python-packaging"
+
+    def applies(self, fv: FileView) -> bool:
+        if fv.text is None or fv.record.vendored:
+            return False
+        return fv.name in ("setup.py", "pyproject.toml", "sitecustomize.py", "usercustomize.py", "conftest.py") or (
+            fv.suffix == ".pth"
+        )
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        name = fv.name
+        if name == "setup.py":
+            ctx.add_trigger("python-setup", fv.rel, line=1, label="setup.py", autorun=True, references=[fv.rel])
+            return [build_finding(R_SETUP_PY.id, [fv.evidence_at_line(1)])]
+        if name == "conftest.py":
+            ctx.add_trigger("pytest-conftest", fv.rel, line=1, label="conftest.py", autorun=False, references=[fv.rel])
+            return [build_finding(R_CONFTEST.id, [fv.evidence_at_line(1)])]
+        if name in ("sitecustomize.py", "usercustomize.py"):
+            ctx.add_trigger("python-startup", fv.rel, line=1, label=name, autorun=True, references=[fv.rel])
+            ctx.autoloaded.add(fv.rel)
+            return [build_finding(R_STARTUP.id, [fv.evidence_at_line(1)])]
+        if fv.suffix == ".pth":
+            out: list[Finding] = []
+            for i, line in enumerate(fv.lines, 1):
+                if line.lstrip().startswith(("import ", "import\t")):
+                    in_site = "site-packages/" in fv.rel
+                    out.append(
+                        build_finding(R_PTH.id, [fv.evidence_at_line(i)], severity=Severity.MEDIUM if in_site else None)
+                    )
+                    ctx.add_trigger(
+                        "python-pth",
+                        fv.rel,
+                        line=i,
+                        label=fv.name,
+                        command=make_excerpt(line),
+                        autorun=True,
+                        references=[fv.rel],
+                    )
+                    break
+            return out
+        return self._pyproject(fv, ctx)
+
+    def _pyproject(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        try:
+            data = tomllib.loads(fv.text or "")
+        except tomllib.TOMLDecodeError as exc:
+            ctx.warn("python-packaging", f"invalid TOML: {exc}", fv.rel)
+            return []
+        bs = data.get("build-system") or {}
+        paths = bs.get("backend-path") if isinstance(bs, dict) else None
+        if not paths:
+            return []
+        line = next((i for i, ln in enumerate(fv.lines, 1) if "backend-path" in ln), None)
+        backend = str(bs.get("build-backend", ""))
+        refs = []
+        module = backend.split(":")[0].replace(".", "/")
+        for p in paths if isinstance(paths, list) else [paths]:
+            if not isinstance(p, str):
+                continue
+            for cand in (f"{p}/{module}.py", f"{p}/{module}/__init__.py"):
+                full = normalize_rel(f"{fv.parent}/{cand}" if fv.parent else cand)
+                if full and ctx.inventory.exists(full):
+                    refs.append(full)
+        ctx.add_trigger("python-backend", fv.rel, line=line, label=backend, autorun=True, references=refs)
+        return [
+            build_finding(
+                R_BACKEND.id,
+                [fv.evidence_at_line(line)],
+                detail=f"backend {make_excerpt(backend, limit=80)!r} from {paths!r}.",
+            )
+        ]