devguard-scanner 0.1.0__py3-none-any.whl

devguard/analyzers/surfaces/devcontainer.py

@@ -0,0 +1,195 @@
+"""Dev Container configuration (TC-04.12)."""
+
+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 (
+    assess_and_trigger,
+    command_text,
+    env_findings,
+    env_pairs_from_node,
+    load_jsonc,
+    workspace_root_of,
+)
+from devguard.core.models import Finding
+from devguard.core.redact import make_excerpt
+from devguard.rules.catalog import build_finding, rule
+
+R_HOST_CMD = rule(
+    "DG-DEVC-HOST-CMD-001",
+    "Dev container runs a command on the host",
+    "high",
+    "high",
+    "ide-autorun",
+    "TC-04.12",
+    "`initializeCommand` runs on the developer's machine (not inside the container) whenever the dev "
+    "container is built or opened.",
+    "Rarely needed; used for things like creating a host directory before mounting it.",
+    "Read the command before choosing 'Reopen in Container'.",
+)
+R_LIFECYCLE = rule(
+    "DG-DEVC-LIFECYCLE-001",
+    "Dev container lifecycle command",
+    "low",
+    "high",
+    "ide-autorun",
+    "TC-04.12",
+    "The dev container runs this command automatically (postCreate/postStart/postAttach...). It runs inside "
+    "the container, which typically has your workspace and forwarded credentials mounted.",
+)
+R_PRIVILEGED = rule(
+    "DG-DEVC-PRIVILEGED-001",
+    "Dev container gets host-level access",
+    "high",
+    "high",
+    "ide-autorun",
+    "TC-04.12, TC-04.11",
+    "The container is privileged, joins host namespaces, or mounts sensitive host paths (Docker socket, home "
+    "directory, SSH keys, root filesystem), which lets code inside it take over the host.",
+    "Docker-in-Docker setups mount the Docker socket on purpose.",
+)
+R_FEATURE = rule(
+    "DG-DEVC-FEATURE-001",
+    "Dev container feature from an unfamiliar source",
+    "low",
+    "low",
+    "ide-autorun",
+    "TC-04.12",
+    "A dev container feature (an install script that runs as root during the build) comes from outside the "
+    "official devcontainers registry.",
+)
+
+LIFECYCLE_KEYS = (
+    "onCreateCommand",
+    "updateContentCommand",
+    "postCreateCommand",
+    "postStartCommand",
+    "postAttachCommand",
+)
+_PRIV_ARGS = re.compile(
+    r"^--privileged$|^--(cap-add)(=|$)|^--(network|net|pid|ipc|uts|userns)=host$|^--security-opt(=|$)"
+)
+_SENSITIVE_MOUNT = re.compile(
+    r"docker\.sock|\$\{localEnv:(HOME|USERPROFILE)\}(/(\.ssh|\.aws|\.kube|\.gnupg|\.config|\.docker))?[,\s]|"
+    r"\$\{localEnv:(HOME|USERPROFILE)\}/?(,|$)|source=/(,|$)|source=/etc\b|/\.ssh\b|/\.aws\b|/\.kube\b",
+)
+_OFFICIAL_FEATURES = ("ghcr.io/devcontainers/", "ghcr.io/devcontainers-contrib/", "ghcr.io/devcontainers-extra/")
+
+
+class DevcontainerAnalyzer:
+    name = "devcontainer"
+
+    def applies(self, fv: FileView) -> bool:
+        return fv.text is not None and (
+            fv.name == ".devcontainer.json" or (fv.name == "devcontainer.json" and "/.devcontainer/" in f"/{fv.rel}")
+        )
+
+    def analyze(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 = [workspace_root_of(fv.rel), fv.parent]
+        init = root.get("initializeCommand")
+        for label, cmd, line in _commands(init):
+            out.append(
+                build_finding(
+                    R_HOST_CMD.id, [fv.evidence_at_line(line)], detail=f"{label}: {make_excerpt(cmd, limit=160)}"
+                )
+            )
+            out += assess_and_trigger(
+                ctx,
+                fv,
+                cmd,
+                line,
+                kind="devcontainer-host",
+                label=label,
+                autorun=True,
+                context="devcontainer initializeCommand (host)",
+                base_dirs=base,
+            )
+        for key in LIFECYCLE_KEYS:
+            for label, cmd, line in _commands(root.get(key), key):
+                out.append(
+                    build_finding(
+                        R_LIFECYCLE.id, [fv.evidence_at_line(line)], detail=f"{label}: {make_excerpt(cmd, limit=160)}"
+                    )
+                )
+                out += assess_and_trigger(
+                    ctx,
+                    fv,
+                    cmd,
+                    line,
+                    kind="devcontainer",
+                    label=label,
+                    autorun=True,
+                    context=f"devcontainer {key}",
+                    base_dirs=base,
+                )
+        out += self._privileges(root, fv)
+        feats = root.get("features")
+        for fid, node in feats.items() if feats else []:
+            if "/" in fid and not fid.startswith(_OFFICIAL_FEATURES) and not fid.startswith("./"):
+                out.append(
+                    build_finding(
+                        R_FEATURE.id,
+                        [fv.evidence_at_line(node.line)],
+                        detail=f"Feature: {make_excerpt(fid, limit=120)}",
+                    )
+                )
+        for key in ("containerEnv", "remoteEnv"):
+            if (env := root.get(key)) is not None:
+                out += env_findings(
+                    ctx, fv, env_pairs_from_node(env), context=f"devcontainer {key}", autorun=True, base_dirs=base
+                )
+        return out
+
+    def _privileges(self, root: Node, fv: FileView) -> list[Finding]:
+        out: list[Finding] = []
+        priv = root.get("privileged")
+        if priv is not None and priv.value is True:
+            out.append(build_finding(R_PRIVILEGED.id, [fv.evidence_at_line(priv.line)], detail="privileged: true"))
+        cap = root.get("capAdd")
+        if cap is not None and any(e.value in ("SYS_ADMIN", "ALL", "SYS_PTRACE") for e in cap.elements()):
+            out.append(build_finding(R_PRIVILEGED.id, [fv.evidence_at_line(cap.line)], detail="capAdd"))
+        run_args = root.get("runArgs")
+        for e in run_args.elements() if run_args else []:
+            if isinstance(e.value, str) and (_PRIV_ARGS.match(e.value) or _SENSITIVE_MOUNT.search(e.value + ",")):
+                out.append(
+                    build_finding(
+                        R_PRIVILEGED.id,
+                        [fv.evidence_at_line(e.line)],
+                        detail=f"runArgs: {make_excerpt(e.value, limit=120)}",
+                    )
+                )
+        mounts = root.get("mounts")
+        for e in mounts.elements() if mounts else []:
+            text = (
+                e.value
+                if isinstance(e.value, str)
+                else ",".join(f"{k}={v.value}" for k, v in e.items() if isinstance(v.value, str))
+            )
+            if text and _SENSITIVE_MOUNT.search(text + ","):
+                out.append(
+                    build_finding(
+                        R_PRIVILEGED.id, [fv.evidence_at_line(e.line)], detail=f"mount: {make_excerpt(text, limit=160)}"
+                    )
+                )
+        return out
+
+
+def _commands(node: Node | None, key: str = "initializeCommand") -> list[tuple[str, str, int]]:
+    if node is None:
+        return []
+    if isinstance(node.value, dict):  # {"name": "cmd" | [...]} commands run in parallel
+        out = []
+        for name, sub in node.items():
+            cmd = command_text(sub)
+            if cmd:
+                out.append((f"{key}.{name}", cmd, sub.line))
+        return out
+    cmd = command_text(node)
+    return [(key, cmd, node.line)] if cmd else []

devguard/analyzers/surfaces/env.py

@@ -0,0 +1,53 @@
+"""Shell/environment auto-loaders: .envrc (direnv), .env files (TC-10)."""
+
+from __future__ import annotations
+
+import re
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.surfaces.common import env_findings
+from devguard.core.models import Finding
+from devguard.rules.catalog import build_finding, rule
+
+R_DIRENV = rule(
+    "DG-ENV-DIRENV-001",
+    "direnv file runs shell code on directory entry",
+    "low",
+    "high",
+    "trigger",
+    "TC-10.1",
+    "`.envrc` is executed by direnv every time a shell enters this directory (once allowed). Its contents "
+    "are checked by the shell rules.",
+    "direnv is a common, legitimate tool; review the file before running `direnv allow`.",
+)
+
+_ASSIGN = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$")
+
+
+def _unquote(v: str) -> str:
+    v = v.strip()
+    if len(v) >= 2 and v[0] == v[-1] and v[0] in "'\"":
+        return v[1:-1]
+    return v.split(" #", 1)[0].strip()
+
+
+class EnvAnalyzer:
+    name = "env-loaders"
+
+    def applies(self, fv: FileView) -> bool:
+        return fv.text is not None and (fv.name == ".envrc" or fv.name.startswith(".env"))
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        out: list[Finding] = []
+        base = [fv.parent]
+        if fv.name == ".envrc":
+            out.append(build_finding(R_DIRENV.id, [fv.evidence_at_line(1)]))
+            ctx.add_trigger("direnv", fv.rel, line=1, label=".envrc", autorun=True, references=[fv.rel])
+            ctx.autoloaded.add(fv.rel)
+        pairs: list[tuple[str, str, int | None]] = []
+        for i, line in enumerate(fv.lines, 1):
+            m = _ASSIGN.match(line)
+            if m:
+                pairs.append((m.group(1), _unquote(m.group(2)), i))
+        out.extend(env_findings(ctx, fv, pairs, context=fv.name, autorun=fv.name == ".envrc", base_dirs=base))
+        return out

devguard/analyzers/surfaces/git.py

@@ -0,0 +1,236 @@
+"""Git-level execution points (TC-06): .git/config, pre-populated hooks, .gitmodules, .gitattributes."""
+
+from __future__ import annotations
+
+import re
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.surfaces.common import assess_and_trigger
+from devguard.core.models import Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.rules.catalog import build_finding, rule
+
+R_CONFIG_EXEC = rule(
+    "DG-GIT-CONFIG-EXEC-001",
+    "Repository git config runs a program",
+    "high",
+    "high",
+    "vcs",
+    "TC-06.1",
+    "The repository's own .git/config sets an option that makes git run a program (fsmonitor, hooksPath, "
+    "sshCommand, pager, editor, filter/diff drivers, credential helper, alias with '!'). A normal clone never "
+    "contains this; it appears when a repository is shipped as an archive or a prepared folder.",
+    "Developers set these locally for their own tooling; a repository received from someone else should not.",
+    "Do not run git commands (or open the folder in an editor with git integration) until this is removed.",
+)
+R_FSMONITOR = rule(
+    "DG-GIT-FSMONITOR-001",
+    "git fsmonitor hook runs on every git status",
+    "critical",
+    "high",
+    "vcs",
+    "TC-06.1",
+    "`core.fsmonitor` names a program that git executes on almost every command, including the `git status` "
+    "that IDEs and shell prompts run automatically when you open or cd into the folder.",
+)
+R_HOOK = rule(
+    "DG-GIT-HOOK-001",
+    "Pre-populated git hook",
+    "high",
+    "high",
+    "vcs",
+    "TC-06.2",
+    "The repository contains an active git hook. Cloning never copies hooks, so this one was planted in an "
+    "archive or prepared folder and will run on commit/checkout/merge.",
+)
+R_SUBMODULE = rule(
+    "DG-GIT-SUBMODULE-001",
+    "Suspicious git submodule definition",
+    "high",
+    "medium",
+    "vcs",
+    "TC-06.4",
+    "A .gitmodules entry uses an unusual URL scheme, an option-like value, or a path that escapes the "
+    "repository; these patterns have been used to exploit git itself.",
+)
+R_ATTRIBUTES = rule(
+    "DG-GIT-ATTRIBUTES-DRIVER-001",
+    ".gitattributes references a filter or diff driver",
+    "info",
+    "medium",
+    "vcs",
+    "TC-06.3",
+    "Files are assigned a filter/diff/merge driver. Drivers only run if configured in git config; this is "
+    "dangerous only together with a repository-provided config.",
+)
+
+_EXEC_KEYS = {
+    "core.hookspath",
+    "core.sshcommand",
+    "core.pager",
+    "core.editor",
+    "core.gitproxy",
+    "core.askpass",
+    "sequence.editor",
+    "gpg.program",
+    "gpg.ssh.program",
+    "gpg.x509.program",
+    "uploadpack.packobjectshook",
+    "diff.external",
+    "credential.helper",
+    "include.path",
+    "core.attributesfile",
+    "core.excludesfile",
+}
+_SECTION = re.compile(r'^\s*\[\s*([A-Za-z0-9.-]+)(?:\s+"((?:[^"\\]|\\.)*)")?\s*\]\s*(.*)$')
+_KV = re.compile(r"^\s*([A-Za-z][A-Za-z0-9-]*)\s*(?:=\s*(.*))?$")
+_SAMPLE_HOOK = re.compile(r"\.sample$")
+
+
+def _git_value(raw: str) -> str:
+    raw = raw.strip()
+    if raw.startswith('"') and raw.endswith('"') and len(raw) >= 2:
+        return raw[1:-1].replace('\\"', '"').replace("\\\\", "\\")
+    return re.split(r"\s[;#]", raw, maxsplit=1)[0].strip()
+
+
+class GitAnalyzer:
+    name = "git"
+
+    def applies(self, fv: FileView) -> bool:
+        rel = f"/{fv.rel}"
+        return (
+            rel.endswith("/.git/config")
+            or ("/.git/hooks/" in rel and not _SAMPLE_HOOK.search(rel))
+            or fv.name in (".gitmodules", ".gitattributes")
+        )
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        rel = f"/{fv.rel}"
+        if "/.git/hooks/" in rel:
+            hook = fv.name
+            ctx.add_trigger("git-hook", fv.rel, line=1, label=hook, autorun=True, references=[fv.rel])
+            return [build_finding(R_HOOK.id, [fv.evidence_at_line(1 if fv.text else None)], detail=f"Hook: {hook}")]
+        if fv.text is None:
+            return []
+        if rel.endswith("/.git/config"):
+            return self._config(fv, ctx)
+        if fv.name == ".gitmodules":
+            return self._submodules(fv)
+        return self._attributes(fv)
+
+    def _config(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        out: list[Finding] = []
+        repo_root = fv.rel.rsplit(".git/config", 1)[0].rstrip("/")
+        section, subsection = "", ""
+        for i, line in enumerate(fv.lines, 1):
+            s = line.strip()
+            if not s or s.startswith(("#", ";")):
+                continue
+            m = _SECTION.match(s)
+            if m:
+                section, subsection = m.group(1).lower(), (m.group(2) or "")
+                s = m.group(3).strip()
+                if not s:
+                    continue
+            kv = _KV.match(s)
+            if not kv:
+                continue
+            key, value = kv.group(1).lower(), _git_value(kv.group(2) or "true")
+            full = f"{section}.{key}"
+            name = f"{section}.{subsection}.{key}" if subsection else full
+            is_exec = (
+                full in _EXEC_KEYS
+                or (section in ("filter",) and key in ("clean", "smudge", "process"))
+                or (section == "diff" and key in ("textconv", "command"))
+                or (section == "merge" and key == "driver")
+                or (section == "alias" and value.startswith("!"))
+                or (section == "url" and key in ("insteadof", "pushinsteadof"))
+                or section == "includeif"
+            )
+            if full == "core.fsmonitor":
+                if value.lower() in ("true", "false", "0", "1", ""):
+                    continue
+                out.append(
+                    build_finding(
+                        R_FSMONITOR.id,
+                        [fv.evidence_at_line(i)],
+                        detail=f"core.fsmonitor = {make_excerpt(value, limit=160)}",
+                    )
+                )
+                out += assess_and_trigger(
+                    ctx,
+                    fv,
+                    value,
+                    i,
+                    kind="git-fsmonitor",
+                    label=name,
+                    autorun=True,
+                    context="git core.fsmonitor",
+                    base_dirs=[repo_root],
+                )
+                continue
+            if not is_exec:
+                continue
+            sev = Severity.LOW if section == "url" else None
+            out.append(
+                build_finding(
+                    R_CONFIG_EXEC.id,
+                    [fv.evidence_at_line(i)],
+                    severity=sev,
+                    detail=f"{name} = {make_excerpt(value, limit=160)}",
+                )
+            )
+            if section != "url":
+                autorun = full in ("core.hookspath", "core.pager", "include.path") or section in ("filter",)
+                out += assess_and_trigger(
+                    ctx,
+                    fv,
+                    value.lstrip("!"),
+                    i,
+                    kind="git-config",
+                    label=name,
+                    autorun=autorun,
+                    context=f"git config {name}",
+                    base_dirs=[repo_root],
+                )
+        return out
+
+    def _submodules(self, fv: FileView) -> list[Finding]:
+        out: list[Finding] = []
+        count = 0
+        for i, line in enumerate(fv.lines, 1):
+            kv = _KV.match(line.strip())
+            if not kv:
+                continue
+            key, value = kv.group(1).lower(), _git_value(kv.group(2) or "")
+            if key == "url":
+                count += 1
+                if re.match(r"^(ext::|fd::|file://|-)", value) or value.startswith("--"):
+                    out.append(
+                        build_finding(
+                            R_SUBMODULE.id, [fv.evidence_at_line(i)], detail=f"url = {make_excerpt(value, limit=120)}"
+                        )
+                    )
+            elif key in ("path", "update", "branch"):
+                if (
+                    value.startswith("-")
+                    or ".." in value.split("/")
+                    or value.startswith(".git")
+                    or (key == "update" and value.startswith("!"))
+                ):
+                    out.append(
+                        build_finding(
+                            R_SUBMODULE.id,
+                            [fv.evidence_at_line(i)],
+                            severity=Severity.CRITICAL if key == "update" else None,
+                            detail=f"{key} = {make_excerpt(value, limit=120)}",
+                        )
+                    )
+        return out
+
+    def _attributes(self, fv: FileView) -> list[Finding]:
+        for i, line in enumerate(fv.lines, 1):
+            if re.search(r"\b(filter|diff|merge)=(?!lfs\b)[\w-]+", line) and not line.lstrip().startswith("#"):
+                return [build_finding(R_ATTRIBUTES.id, [fv.evidence_at_line(i)])]
+        return []