devguard-scanner 0.1.0__py3-none-any.whl

devguard/analyzers/surfaces/autoload.py

@@ -0,0 +1,142 @@
+"""Files that tools load automatically (TC-05) and commands that documentation tells the reader to run (TC-13).
+
+These analyzers mostly register triggers; correlation turns "trigger reaches dangerous code" into findings.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.command import analyze_command
+from devguard.core.models import Finding
+from devguard.core.redact import make_excerpt
+
+# Config-as-code: JS/TS/Python files imported by build tools, test runners, linters, or IDE extensions.
+CONFIG_AS_CODE = (
+    "eslint.config.*",
+    ".eslintrc.js",
+    ".eslintrc.cjs",
+    "prettier.config.*",
+    ".prettierrc.js",
+    ".prettierrc.cjs",
+    "babel.config.*",
+    ".babelrc.js",
+    "postcss.config.*",
+    "tailwind.config.*",
+    "next.config.*",
+    "vite.config.*",
+    "vitest.config.*",
+    "webpack.config.*",
+    "rollup.config.*",
+    "jest.config.*",
+    "playwright.config.*",
+    "nuxt.config.*",
+    "svelte.config.*",
+    "astro.config.*",
+    "remix.config.*",
+    "metro.config.*",
+    "craco.config.*",
+    "commitlint.config.*",
+    "lint-staged.config.*",
+    ".lintstagedrc.js",
+    ".lintstagedrc.cjs",
+    "stylelint.config.*",
+    ".stylelintrc.js",
+    "gatsby-config.*",
+    "gatsby-node.*",
+    "quasar.config.*",
+    "electron.vite.config.*",
+    "tsup.config.*",
+    "esbuild.config.*",
+    "karma.conf.js",
+    "protractor.conf.js",
+    "gulpfile.*",
+    "Gruntfile.*",
+    "*.storybook/main.*",
+    "*.storybook/preview.*",
+)
+_CODE_SUFFIXES = (".js", ".cjs", ".mjs", ".ts", ".cts", ".mts", ".jsx", ".tsx")
+
+_DOC_NAMES = re.compile(
+    r"^(readme|install|setup|contributing|getting[-_]started|quickstart|usage)([-_.].*)?\.(md|markdown|txt|rst)$",
+    re.IGNORECASE,
+)
+_FENCE = re.compile(r"^(```|~~~)\s*([\w+-]*)\s*$")
+_SHELL_FENCES = {"", "bash", "sh", "shell", "zsh", "console", "terminal", "powershell", "ps1", "pwsh", "cmd", "bat"}
+_INLINE = re.compile(r"`([^`\n]{3,240})`")
+_COMMANDISH = re.compile(
+    r"^\s*(\$\s+|>\s+|PS>\s+)?(npm|yarn|pnpm|bun|npx|node|deno|python3?|pip3?|uv|bash|sh|zsh|\./|source|\.\s|"
+    r"powershell|pwsh|make|docker|docker-compose|curl|wget|iwr|go\s+run|cargo\s+run|ruby|php)\b"
+)
+
+
+class AutoloadedConfigAnalyzer:
+    name = "config-as-code"
+
+    def applies(self, fv: FileView) -> bool:
+        if fv.record.vendored or fv.text is None:
+            return False
+        return _is_config_as_code(fv.rel) or "/.husky/" in f"/{fv.rel}"
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        if "/.husky/" in f"/{fv.rel}":
+            if not fv.name.startswith("_") and fv.name not in (".gitignore",):
+                ctx.add_trigger("husky-hook", fv.rel, line=1, label=fv.name, autorun=False, references=[fv.rel])
+            return []
+        ctx.autoloaded.add(fv.rel)
+        ctx.add_trigger("config-as-code", fv.rel, line=1, label=fv.name, autorun=True, references=[fv.rel])
+        return []
+
+
+def _is_config_as_code(rel: str) -> bool:
+    name = rel.rsplit("/", 1)[-1]
+    for pat in CONFIG_AS_CODE:
+        target = rel if "/" in pat else name
+        if fnmatch.fnmatchcase(target, pat) and name.endswith(_CODE_SUFFIXES):
+            return True
+    return False
+
+
+class DocInstructionAnalyzer:
+    """Registers commands from README-like files as manual triggers (no findings of its own)."""
+
+    name = "doc-instructions"
+
+    def applies(self, fv: FileView) -> bool:
+        return fv.text is not None and not fv.record.vendored and bool(_DOC_NAMES.match(fv.name))
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        in_fence = False
+        fence_lang = ""
+        count = 0
+        for i, line in enumerate(fv.lines, 1):
+            m = _FENCE.match(line.strip())
+            if m:
+                in_fence = not in_fence
+                fence_lang = m.group(2).lower() if in_fence else ""
+                continue
+            commands: list[str] = []
+            if in_fence and fence_lang in _SHELL_FENCES and _COMMANDISH.match(line):
+                commands.append(line)
+            elif not in_fence:
+                commands += [c for c in _INLINE.findall(line) if _COMMANDISH.match(c)]
+            for cmd in commands:
+                cmd = re.sub(r"^\s*(\$|>|PS>)\s+", "", cmd)
+                a = analyze_command(cmd, ctx.inventory, [fv.parent])
+                if a.references or a.npm_scripts:
+                    ctx.add_trigger(
+                        "doc-instruction",
+                        fv.rel,
+                        line=i,
+                        label=fv.name,
+                        command=make_excerpt(cmd),
+                        autorun=False,
+                        references=a.references,
+                        npm_scripts=a.npm_scripts,
+                    )
+                    count += 1
+                if count >= 50:
+                    return []
+        return []

devguard/analyzers/surfaces/common.py

@@ -0,0 +1,242 @@
+"""Helpers shared by surface analyzers."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from pathlib import PurePosixPath
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.command import analyze_command, command_findings
+from devguard.analyzers.jsonc import JsoncError, Node, parse_jsonc
+from devguard.core.models import Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.rules.catalog import build_finding, rule
+
+R_DUPKEY = rule(
+    "DG-JSONC-DUPKEY-001",
+    "Duplicate key in configuration file",
+    "medium",
+    "high",
+    "config",
+    "TC-01.6",
+    "A key appears twice in the same object. Tools such as VS Code use the last value, so a harmless "
+    "first value can hide a different effective one.",
+    "Usually an editing mistake.",
+)
+R_INVALID = rule(
+    "DG-JSONC-INVALID-001",
+    "Configuration file could not be parsed",
+    "info",
+    "high",
+    "config",
+    "TC-01.6",
+    "The file is not valid JSON/JSONC, so its structured checks were skipped. Tools may still read it "
+    "with a more lenient parser.",
+)
+
+
+def load_jsonc(fv: FileView, ctx: AnalysisContext, findings: list[Finding]) -> Node | None:
+    if fv.text is None:
+        return None
+    try:
+        root, dups = parse_jsonc(fv.text)
+    except JsoncError as exc:
+        findings.append(build_finding(R_INVALID.id, [fv.evidence_at_line(exc.line)], detail=str(exc)))
+        return None
+    for key, first, dup in dups:
+        findings.append(
+            build_finding(
+                R_DUPKEY.id,
+                [fv.evidence_at_line(first), fv.evidence_at_line(dup)],
+                detail=f"Key {make_excerpt(key, limit=80)!r} on lines {first} and {dup}.",
+            )
+        )
+    return root
+
+
+def command_text(node: Node | None) -> str | None:
+    """A command may be a string, an argv array, or (devcontainer) an object of named commands."""
+    if node is None:
+        return None
+    if isinstance(node.value, str):
+        return node.value
+    if isinstance(node.value, list):
+        parts = [str(n.value) for n in node.value if isinstance(n.value, (str, int, float))]
+        return shlex.join(parts) if parts else None
+    return None
+
+
+def args_text(node: Node | None) -> list[str]:
+    out: list[str] = []
+    for el in node.elements() if node else []:
+        if isinstance(el.value, str):
+            out.append(el.value)
+        elif isinstance(el.value, dict):
+            quoted = el.get("value")  # VS Code {"value": "...", "quoting": "..."} form
+            if quoted is not None and isinstance(quoted.value, str):
+                out.append(quoted.value)
+    return out
+
+
+def workspace_root_of(rel: str) -> str:
+    """Directory that `${workspaceFolder}` refers to for a file inside `.vscode/` (or next to it)."""
+    p = PurePosixPath(rel)
+    parent = p.parent
+    if parent.name in (".vscode", ".devcontainer", ".claude", ".cursor", ".gemini", ".windsurf", ".github"):
+        parent = parent.parent
+    s = str(parent)
+    return "" if s == "." else s
+
+
+def assess_and_trigger(
+    ctx: AnalysisContext,
+    fv: FileView,
+    command: str,
+    line: int | None,
+    *,
+    kind: str,
+    label: str,
+    autorun: bool,
+    context: str,
+    base_dirs: list[str],
+) -> list[Finding]:
+    a = analyze_command(command, ctx.inventory, base_dirs)
+    ctx.add_trigger(
+        kind,
+        fv.rel,
+        line=line,
+        label=label,
+        command=make_excerpt(command),
+        autorun=autorun,
+        references=a.references,
+        npm_scripts=a.npm_scripts,
+    )
+    return command_findings(a, fv, line, autorun=autorun, context=context)
+
+
+# --------------------------------------------------------------------------- environment variables
+
+R_ENV_INJECT = rule(
+    "DG-ENV-INJECTION-001",
+    "Environment variable injects code into processes",
+    "high",
+    "high",
+    "env",
+    "TC-10.3",
+    "The variable makes interpreters or the dynamic linker load extra code (for example NODE_OPTIONS=--require, "
+    "LD_PRELOAD, JAVA_TOOL_OPTIONS=-javaagent, BASH_ENV), so every matching process runs it.",
+    "Debugging setups occasionally use these; in a cloned project they are a strong warning sign.",
+)
+R_ENV_EXEC = rule(
+    "DG-ENV-EXEC-VAR-001",
+    "Environment variable sets an executable or command",
+    "medium",
+    "medium",
+    "env",
+    "TC-10.3",
+    "The variable tells a tool (git, ssh, the shell prompt) to run a command or program.",
+)
+
+_INJECTION_VARS: dict[str, re.Pattern[str] | None] = {
+    "NODE_OPTIONS": re.compile(r"(^|\s)(--require|-r|--import|--loader|--experimental-loader)\b"),
+    "LD_PRELOAD": None,
+    "LD_AUDIT": None,
+    "DYLD_INSERT_LIBRARIES": None,
+    "JAVA_TOOL_OPTIONS": re.compile(r"-javaagent|-agentpath|-agentlib"),
+    "_JAVA_OPTIONS": re.compile(r"-javaagent|-agentpath|-agentlib"),
+    "JDK_JAVA_OPTIONS": re.compile(r"-javaagent|-agentpath|-agentlib"),
+    "BASH_ENV": None,
+    "ENV": None,
+    "PROMPT_COMMAND": None,
+    "PERL5OPT": None,
+    "RUBYOPT": re.compile(r"-r"),
+    "PYTHONSTARTUP": None,
+    "ELECTRON_RUN_AS_NODE": None,
+}
+_EXEC_VARS = {
+    "GIT_SSH_COMMAND",
+    "GIT_SSH",
+    "GIT_ASKPASS",
+    "SSH_ASKPASS",
+    "GIT_EXTERNAL_DIFF",
+    "GIT_PAGER",
+    "GIT_EDITOR",
+    "EDITOR",
+    "VISUAL",
+    "PAGER",
+    "NODE_PATH",
+    "PYTHONPATH",
+    "PYTHONHOME",
+    "LD_LIBRARY_PATH",
+    "DYLD_LIBRARY_PATH",
+    "npm_config_script_shell",
+    "NPM_CONFIG_SCRIPT_SHELL",
+    "npm_config_node_options",
+}
+
+
+def env_findings(
+    ctx: AnalysisContext,
+    fv: FileView,
+    pairs: list[tuple[str, str, int | None]],
+    *,
+    context: str,
+    autorun: bool,
+    base_dirs: list[str],
+) -> list[Finding]:
+    out: list[Finding] = []
+    for name, value, line in pairs:
+        key = name.strip()
+        injection = key.upper() in _INJECTION_VARS
+        pattern = _INJECTION_VARS.get(key.upper())
+        if injection and value.strip() and (pattern is None or pattern.search(value)):
+            sev = Severity.HIGH.bump(1) if autorun else Severity.HIGH
+            out.append(
+                build_finding(
+                    R_ENV_INJECT.id,
+                    [fv.evidence_at_line(line)],
+                    severity=sev,
+                    detail=f"{key}={make_excerpt(value, limit=120)} ({context}).",
+                )
+            )
+            a = analyze_command(value, ctx.inventory, base_dirs)
+            ctx.add_trigger(
+                "env-injection",
+                fv.rel,
+                line=line,
+                label=key,
+                command=make_excerpt(value),
+                autorun=autorun,
+                references=a.references,
+            )
+        elif key in _EXEC_VARS and value.strip():
+            out.append(
+                build_finding(
+                    R_ENV_EXEC.id,
+                    [fv.evidence_at_line(line)],
+                    detail=f"{key}={make_excerpt(value, limit=120)} ({context}).",
+                )
+            )
+            out.extend(
+                assess_and_trigger(
+                    ctx,
+                    fv,
+                    value,
+                    line,
+                    kind="env-exec",
+                    label=key,
+                    autorun=autorun,
+                    context=f"{context}: {key}",
+                    base_dirs=base_dirs,
+                )
+            )
+    return out
+
+
+def env_pairs_from_node(node: Node | None) -> list[tuple[str, str, int | None]]:
+    pairs: list[tuple[str, str, int | None]] = []
+    for k, v in node.items() if node else []:
+        if isinstance(v.value, (str, int, float)):
+            pairs.append((k, str(v.value), v.line))
+    return pairs

devguard/analyzers/surfaces/deps.py

@@ -0,0 +1,159 @@
+"""Dependency sources: off-registry, VCS, URL, and file dependencies in manifests and lockfiles (DEP-001, DEP-002)."""
+
+from __future__ import annotations
+
+import re
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.jsonc import Node
+from devguard.analyzers.surfaces.common import load_jsonc
+from devguard.core.models import Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.rules.catalog import build_finding, rule
+
+R_NONREGISTRY = rule(
+    "DG-DEP-NONREGISTRY-001",
+    "Dependency installed from outside the package registry",
+    "low",
+    "medium",
+    "deps",
+    "TC-11.3",
+    "A dependency is fetched from a Git repository, URL, or local path instead of the registry. Its code is "
+    "not covered by registry malware scanning and can change at any time.",
+    "Monorepos (file:/workspace:) and forks pinned to a commit are common.",
+)
+R_LOCK_OFFREG = rule(
+    "DG-DEP-LOCK-OFFREGISTRY-001",
+    "Lockfile resolves packages from an unexpected host",
+    "medium",
+    "medium",
+    "deps",
+    "TC-11.3, TC-11.5",
+    "The lockfile downloads packages from a host other than the public registry. A tampered lockfile can "
+    "silently swap a dependency for a malicious tarball.",
+    "Private registries and mirrors appear here legitimately.",
+)
+R_PIP_INDEX = rule(
+    "DG-DEP-PIP-INDEX-001",
+    "pip package index overridden",
+    "medium",
+    "medium",
+    "deps",
+    "TC-11.4",
+    "The requirements file changes where pip downloads packages from (--index-url / --extra-index-url / "
+    "--trusted-host). `--extra-index-url` in particular enables dependency-confusion attacks.",
+    "Companies use private indexes.",
+)
+
+_NPM_SPEC_OFFREG = re.compile(r"^(git\+|git:|github:|gitlab:|bitbucket:|https?://|file:|link:|[\w.-]+/[\w.-]+(#.*)?$)")
+_OK_HOSTS = (
+    "https://registry.npmjs.org/",
+    "https://registry.yarnpkg.com/",
+    "https://pypi.org/",
+    "https://files.pythonhosted.org/",
+    "https://registry.npmmirror.com/",
+)
+_RAW_IP = re.compile(r"^(https?|git)\+?\w*://(\d{1,3}\.){3}\d{1,3}")
+
+
+def package_json_dependency_findings(root: Node, fv: FileView) -> list[Finding]:
+    out: list[Finding] = []
+    for section in ("dependencies", "devDependencies", "optionalDependencies", "peerDependencies"):
+        deps = root.get(section)
+        for name, spec in deps.items() if deps else []:
+            if not isinstance(spec.value, str):
+                continue
+            v = spec.value.strip()
+            if v.startswith(("workspace:", "npm:", "link:")) or (v.startswith("file:") and ".." not in v):
+                continue
+            if _NPM_SPEC_OFFREG.match(v):
+                sev = Severity.MEDIUM if _RAW_IP.match(v) or v.startswith("http://") else None
+                out.append(
+                    build_finding(
+                        R_NONREGISTRY.id,
+                        [fv.evidence_at_line(spec.line)],
+                        severity=sev,
+                        detail=f"{section}: {make_excerpt(name, limit=60)} → {make_excerpt(v, limit=120)}",
+                    )
+                )
+    return out
+
+
+class LockfileAnalyzer:
+    name = "lockfiles"
+
+    _RESOLVED = re.compile(r'"?(resolved|tarball)"?\s*[:=]?\s*"?((?:https?|git\+[\w]+|git|ssh)://[^"\s,]+)')
+
+    def applies(self, fv: FileView) -> bool:
+        return (
+            fv.text is not None
+            and not fv.record.vendored
+            and (
+                fv.name in ("package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml", "bun.lock")
+                or (fv.name.startswith("requirements") and fv.suffix in (".txt", ".in"))
+            )
+        )
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        if fv.name.startswith("requirements"):
+            return self._requirements(fv)
+        if fv.name in ("package-lock.json", "npm-shrinkwrap.json"):
+            out: list[Finding] = []
+            root = load_jsonc(fv, ctx, out)
+            if root is None:
+                return out
+            hosts: dict[str, int] = {}
+            packages = root.get("packages")
+            for _, pkg in packages.items() if packages else []:
+                r = pkg.get("resolved")
+                if r is not None and isinstance(r.value, str) and not r.value.startswith(_OK_HOSTS):
+                    hosts.setdefault(r.value, r.line)
+            return out + self._report(fv, hosts)
+        hosts = {}
+        for i, line in enumerate(fv.lines, 1):
+            for m in self._RESOLVED.finditer(line):
+                url = m.group(2)
+                if not url.startswith(_OK_HOSTS):
+                    hosts.setdefault(url, i)
+        return self._report(fv, hosts)
+
+    def _report(self, fv: FileView, urls: dict[str, int]) -> list[Finding]:
+        by_host: dict[str, tuple[int, list[str]]] = {}
+        for url, line in urls.items():
+            host = re.sub(r"^[\w+]+://", "", url).split("/", 1)[0]
+            entry = by_host.setdefault(host, (line, []))
+            entry[1].append(url)
+        out = []
+        for host, (line, list_) in sorted(by_host.items()):
+            sev = (
+                Severity.HIGH
+                if re.match(r"^(\d{1,3}\.){3}\d{1,3}", host) or any(u.startswith("http://") for u in list_)
+                else None
+            )
+            out.append(
+                build_finding(
+                    R_LOCK_OFFREG.id,
+                    [fv.evidence_at_line(line)],
+                    severity=sev,
+                    detail=f"{len(list_)} package(s) from {make_excerpt(host, limit=80)}.",
+                )
+            )
+        return out
+
+    def _requirements(self, fv: FileView) -> list[Finding]:
+        out: list[Finding] = []
+        for i, line in enumerate(fv.lines, 1):
+            s = line.strip()
+            if re.match(r"^(-i|--index-url|--extra-index-url|--trusted-host|-f|--find-links)\b", s):
+                value = s.split(None, 1)[1] if " " in s else s.split("=", 1)[-1]
+                if value.strip().rstrip("/").startswith("https://pypi.org/simple"):
+                    continue
+                sev = Severity.HIGH if "extra-index-url" in s and _RAW_IP.match(value.strip()) else None
+                out.append(build_finding(R_PIP_INDEX.id, [fv.evidence_at_line(i)], severity=sev))
+            elif re.search(r"(^|@\s*)(git\+|https?://|file:)", s) and not s.startswith("#"):
+                out.append(
+                    build_finding(
+                        R_NONREGISTRY.id, [fv.evidence_at_line(i)], detail=f"requirement: {make_excerpt(s, limit=120)}"
+                    )
+                )
+        return out