devguard-scanner 0.1.0__py3-none-any.whl

devguard/analyzers/surfaces/vscode.py

@@ -0,0 +1,515 @@
+"""VS Code family (VS Code, Cursor, Windsurf, VSCodium) workspace configuration (TC-01)."""
+
+from __future__ import annotations
+
+import fnmatch
+from functools import cache
+from importlib import resources
+from typing import Any
+
+import yaml
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.command import resolve_ref
+from devguard.analyzers.jsonc import Node
+from devguard.analyzers.surfaces.ai_assistants import mcp_servers_findings
+from devguard.analyzers.surfaces.common import (
+    args_text,
+    assess_and_trigger,
+    command_text,
+    env_findings,
+    env_pairs_from_node,
+    load_jsonc,
+    workspace_root_of,
+)
+from devguard.core.models import Finding, Severity
+from devguard.core.redact import make_excerpt
+from devguard.rules.catalog import build_finding, rule
+
+R_AUTORUN = rule(
+    "DG-VSC-TASK-AUTORUN-001",
+    "Task runs automatically when the folder is opened",
+    "medium",
+    "high",
+    "ide-autorun",
+    "TC-01.1",
+    'The task has `runOptions.runOn: "folderOpen"`, so VS Code runs it as soon as the folder is opened '
+    "in a trusted window. This is the most common delivery method of malicious 'interview' repositories.",
+    "Some projects start watchers or dev servers on open. Check the command and everything it references.",
+    "Do not open this folder in a trusted VS Code window until the task command is reviewed.",
+)
+R_HIDDEN_TASK = rule(
+    "DG-VSC-TASK-HIDDEN-001",
+    "Automatic task hides its terminal output",
+    "high",
+    "medium",
+    "ide-autorun",
+    "TC-01.1, TC-07.9",
+    "An automatically started task suppresses its terminal (reveal: never / echo: false / close: true), "
+    "so the user does not see what it runs.",
+)
+R_OSDIFF = rule(
+    "DG-VSC-TASK-OSDIFF-001",
+    "Task runs a different program per operating system",
+    "low",
+    "medium",
+    "ide-autorun",
+    "TC-01.1",
+    "The task's windows/linux/osx override runs a different program than the base command, which can "
+    "hide a platform-specific payload from reviewers on another OS.",
+    "Cross-platform tasks often switch between `.cmd` and `.sh` wrappers.",
+)
+R_SETTING_EXEC = rule(
+    "DG-VSC-SETTING-EXEC-001",
+    "Workspace setting points an extension at a program in the repository",
+    "high",
+    "medium",
+    "ide-autorun",
+    "TC-01.3",
+    "A workspace setting tells an extension to run an interpreter, language server, or tool that is "
+    "committed inside this repository. The extension starts it automatically when the workspace is trusted.",
+    "Usually such settings point to `.venv` or `node_modules`, which are not committed. A committed target is unusual.",
+)
+R_SETTING_CMD = rule(
+    "DG-VSC-SETTING-CMD-001",
+    "Workspace setting defines a command run by an extension",
+    "low",
+    "medium",
+    "ide-autorun",
+    "TC-01.3",
+    "A workspace setting overrides a command that an extension runs (for example rust-analyzer build "
+    "script or Jest command line).",
+)
+R_SETTING_AUTOTASKS = rule(
+    "DG-VSC-SETTING-AUTOTASKS-001",
+    "Workspace tries to allow automatic tasks",
+    "medium",
+    "high",
+    "ide-autorun",
+    "TC-01.1, TC-14.2",
+    "`task.allowAutomaticTasks` is set in workspace settings, an attempt to make folder-open tasks run "
+    "without a prompt. (Recent VS Code versions only honour it in user settings.)",
+)
+R_SETTING_TRUST = rule(
+    "DG-VSC-SETTING-TRUST-001",
+    "Workspace changes security-related settings",
+    "medium",
+    "high",
+    "ide-autorun",
+    "TC-14.2",
+    "Workspace settings touch workspace-trust or extension-security options. A project has no reason to change these.",
+)
+R_SETTING_HIDE = rule(
+    "DG-VSC-SETTING-HIDE-001",
+    "Workspace hides repository code files from the editor",
+    "medium",
+    "medium",
+    "ide-autorun",
+    "TC-01.3, TC-12.3",
+    "`files.exclude` or `search.exclude` hides code files that exist in this repository, so they do not "
+    "show up in the explorer or search. Attackers use this to hide payload files.",
+    "Generated code is sometimes hidden on purpose.",
+)
+R_EXT_RECOMMEND = rule(
+    "DG-VSC-EXT-RECOMMEND-001",
+    "Workspace recommends extensions",
+    "info",
+    "high",
+    "ide-autorun",
+    "TC-01.4",
+    "The workspace recommends installing extensions. Extensions run with full user privileges; verify "
+    "each publisher and ID (watch for look-alike names) before installing.",
+)
+R_LAUNCH_RUNTIME = rule(
+    "DG-VSC-LAUNCH-RUNTIME-001",
+    "Debug configuration uses a runtime committed in the repository",
+    "medium",
+    "medium",
+    "ide-config",
+    "TC-01.2",
+    "A launch configuration's `runtimeExecutable` points to a file inside the repository instead of an "
+    "installed runtime, so starting the debugger runs that file.",
+)
+
+_CODE_LANGS = {"javascript", "python", "shell", "powershell", "batch", "vbscript", "ruby", "php", "perl"}
+
+
+@cache
+def _settings_data() -> dict[str, Any]:
+    raw = resources.files("devguard.rules").joinpath("data/vscode_settings.yaml").read_text("utf-8")
+    return yaml.safe_load(raw)
+
+
+def _is_exec_key(key: str) -> bool:
+    d = _settings_data()
+    return key in d["executable_keys"] or any(key.endswith(s) for s in d["executable_suffixes"])
+
+
+def _is_cmd_key(key: str) -> bool:
+    d = _settings_data()
+    return key in d["command_keys"] or any(key.endswith(s) for s in d["command_suffixes"])
+
+
+class VSCodeAnalyzer:
+    name = "vscode"
+
+    def applies(self, fv: FileView) -> bool:
+        if fv.text is None:
+            return False
+        rel = fv.rel
+        return fv.suffix == ".code-workspace" or (
+            "/.vscode/" in f"/{rel}" and fv.name in ("tasks.json", "launch.json", "settings.json", "extensions.json")
+        )
+
+    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)]
+        if fv.suffix == ".code-workspace":
+            base = [fv.parent]
+            for folder in root.list_at("folders"):
+                path = folder.get("path")
+                if path is not None and isinstance(path.value, str):
+                    base.append(f"{fv.parent}/{path.value}" if fv.parent else path.value)
+            if (s := root.get("settings")) is not None:
+                out += self._settings(s, fv, ctx, base)
+            if (t := root.get("tasks")) is not None:
+                out += self._tasks(t, fv, ctx, base)
+            if (lc := root.get("launch")) is not None:
+                out += self._launch(lc, fv, ctx, base)
+            if (e := root.get("extensions")) is not None:
+                out += self._extensions(e, fv)
+            return out
+        if fv.name == "tasks.json":
+            out += self._tasks(root, fv, ctx, base)
+        elif fv.name == "launch.json":
+            out += self._launch(root, fv, ctx, base)
+        elif fv.name == "settings.json":
+            out += self._settings(root, fv, ctx, base)
+        elif fv.name == "extensions.json":
+            out += self._extensions(root, fv)
+        return out
+
+    # ------------------------------------------------------------------ tasks
+    def _tasks(self, root: Node, fv: FileView, ctx: AnalysisContext, base: list[str]) -> list[Finding]:
+        out: list[Finding] = []
+        tasks = root.list_at("tasks")
+        by_label: dict[str, Node] = {}
+        for t in tasks:
+            label_of = t.get("label")
+            if label_of is not None and isinstance(label_of.value, str):
+                by_label[label_of.value] = t
+        autorun: set[int] = set()
+        pending = [t for t in tasks if _run_on(t) == "folderOpen"]
+        while pending:
+            t = pending.pop()
+            if id(t) in autorun:
+                continue
+            autorun.add(id(t))
+            deps = t.get("dependsOn")
+            dep_labels = (
+                [deps.value]
+                if deps and isinstance(deps.value, str)
+                else [d.value for d in (deps.elements() if deps else []) if isinstance(d.value, str)]
+            )
+            pending.extend(by_label[d] for d in dep_labels if d in by_label)
+
+        for idx, t in enumerate(tasks):
+            is_auto = id(t) in autorun
+            label_node = t.get("label")
+            label = label_node.value if label_node and isinstance(label_node.value, str) else f"task #{idx + 1}"
+            commands = _task_commands(t)
+            if is_auto:
+                shown = "; ".join(make_excerpt(c, limit=120) for _, c, _ in commands) or "(no command)"
+                direct = _run_on(t) == "folderOpen"
+                out.append(
+                    build_finding(
+                        R_AUTORUN.id,
+                        [fv.evidence_at_line(t.line)],
+                        detail=f"Task {make_excerpt(label, limit=80)!r}"
+                        f"{'' if direct else ' (dependency of a folder-open task)'} runs: {shown}.",
+                    )
+                )
+                if _hides_output(t):
+                    out.append(
+                        build_finding(
+                            R_HIDDEN_TASK.id,
+                            [fv.evidence_at_line(t.line)],
+                            detail=f"Task {make_excerpt(label, limit=80)!r}.",
+                        )
+                    )
+            base_prog = _program(commands[0][1]) if commands and commands[0][0] == "base" else None
+            for scope, cmd, line in commands:
+                if scope != "base" and base_prog and _program(cmd) != base_prog:
+                    out.append(
+                        build_finding(
+                            R_OSDIFF.id,
+                            [fv.evidence_at_line(line)],
+                            severity=Severity.MEDIUM if is_auto else None,
+                            detail=f"Base program {base_prog!r}, {scope} program {_program(cmd)!r}.",
+                        )
+                    )
+                out += assess_and_trigger(
+                    ctx,
+                    fv,
+                    cmd,
+                    line,
+                    kind="vscode-task",
+                    label=label,
+                    autorun=is_auto,
+                    context=f"VS Code task {make_excerpt(label, limit=60)!r} ({scope})",
+                    base_dirs=base,
+                )
+            opts = t.get("options")
+            if opts is not None and (env := opts.get("env")) is not None:
+                out += env_findings(
+                    ctx, fv, env_pairs_from_node(env), context=f"task {label!r} env", autorun=is_auto, base_dirs=base
+                )
+        return out
+
+    # ------------------------------------------------------------------ launch
+    def _launch(self, root: Node, fv: FileView, ctx: AnalysisContext, base: list[str]) -> list[Finding]:
+        out: list[Finding] = []
+        configs = root.list_at("configurations")
+        for c in configs:
+            name_node = c.get("name")
+            name = name_node.value if name_node and isinstance(name_node.value, str) else "debug config"
+            runtime = c.get("runtimeExecutable")
+            if runtime is not None and isinstance(runtime.value, str):
+                ref = resolve_ref(runtime.value, ctx.inventory, base)
+                if ref:
+                    out.append(
+                        build_finding(
+                            R_LAUNCH_RUNTIME.id, [fv.evidence_at_line(runtime.line)], detail=f"{name!r} uses {ref}."
+                        )
+                    )
+                cmd = " ".join([runtime.value, *args_text(c.get("runtimeArgs"))])
+                out += assess_and_trigger(
+                    ctx,
+                    fv,
+                    cmd,
+                    runtime.line,
+                    kind="vscode-launch",
+                    label=name,
+                    autorun=False,
+                    context=f"debug configuration {name!r}",
+                    base_dirs=base,
+                )
+            program = c.get("program")
+            if program is not None and isinstance(program.value, str):
+                ref = resolve_ref(program.value, ctx.inventory, base)
+                ctx.add_trigger(
+                    "vscode-launch",
+                    fv.rel,
+                    line=program.line,
+                    label=name,
+                    command=make_excerpt(program.value),
+                    autorun=False,
+                    references=[ref] if ref else [],
+                )
+            if (env := c.get("env")) is not None:
+                out += env_findings(
+                    ctx,
+                    fv,
+                    env_pairs_from_node(env),
+                    context=f"debug configuration {name!r}",
+                    autorun=False,
+                    base_dirs=base,
+                )
+        return out
+
+    # ------------------------------------------------------------------ settings
+    def _settings(self, root: Node, fv: FileView, ctx: AnalysisContext, base: list[str]) -> list[Finding]:
+        out: list[Finding] = []
+        for key, node in _flatten_settings(root):
+            if key == "task.allowAutomaticTasks" and node.value in ("on", True):
+                out.append(build_finding(R_SETTING_AUTOTASKS.id, [fv.evidence_at_line(node.line)]))
+            elif key.startswith(
+                (
+                    "security.workspace.trust",
+                    "extensions.verifySignature",
+                    "extensions.autoUpdate",
+                    "chat.tools.autoApprove",
+                    "chat.tools.global.autoApprove",
+                )
+            ):
+                out.append(
+                    build_finding(R_SETTING_TRUST.id, [fv.evidence_at_line(node.line)], detail=f"Setting {key!r}.")
+                )
+            elif key in ("files.exclude", "search.exclude", "explorer.excludeGitIgnore"):
+                out += self._hidden_files(key, node, fv, ctx)
+            elif key.startswith("terminal.integrated.env."):
+                out += env_findings(
+                    ctx, fv, env_pairs_from_node(node), context=f"setting {key}", autorun=False, base_dirs=base
+                )
+            elif key.startswith("terminal.integrated.profiles."):
+                for pname, prof in node.items():
+                    path = prof.get("path")
+                    cmd_parts = []
+                    if path is not None:
+                        cmd_parts.append(command_text(path) or "")
+                    cmd_parts += args_text(prof.get("args"))
+                    if any(cmd_parts):
+                        out += assess_and_trigger(
+                            ctx,
+                            fv,
+                            " ".join(cmd_parts),
+                            prof.line,
+                            kind="vscode-terminal",
+                            label=pname,
+                            autorun=False,
+                            context=f"terminal profile {pname!r}",
+                            base_dirs=base,
+                        )
+            elif key == "mcp" and (servers := node.get("servers")) is not None:
+                out += mcp_servers_findings(servers, fv, ctx, base, client="VS Code settings")
+            elif _is_cmd_key(key):
+                cmd = command_text(node)
+                if cmd:
+                    out.append(
+                        build_finding(
+                            R_SETTING_CMD.id,
+                            [fv.evidence_at_line(node.line)],
+                            detail=f"{key} = {make_excerpt(cmd, limit=120)}",
+                        )
+                    )
+                    out += assess_and_trigger(
+                        ctx,
+                        fv,
+                        cmd,
+                        node.line,
+                        kind="vscode-setting",
+                        label=key,
+                        autorun=True,
+                        context=f"setting {key}",
+                        base_dirs=base,
+                    )
+            elif _is_exec_key(key):
+                out += self._exec_setting(key, node, fv, ctx, base)
+        return out
+
+    def _exec_setting(self, key: str, node: Node, fv: FileView, ctx: AnalysisContext, base: list[str]) -> list[Finding]:
+        values: list[tuple[str, int]] = []
+        if isinstance(node.value, str):
+            values.append((node.value, node.line))
+        elif isinstance(node.value, list):
+            values += [(e.value, e.line) for e in node.elements() if isinstance(e.value, str)]
+        elif isinstance(node.value, dict):
+            values += [(v.value, v.line) for _, v in node.items() if isinstance(v.value, str)]
+        out: list[Finding] = []
+        for value, line in values:
+            ref = resolve_ref(value, ctx.inventory, base)
+            if ref is None:
+                continue
+            out.append(build_finding(R_SETTING_EXEC.id, [fv.evidence_at_line(line)], detail=f"{key} → {ref}."))
+            ctx.add_trigger(
+                "vscode-setting-exec",
+                fv.rel,
+                line=line,
+                label=key,
+                command=make_excerpt(value),
+                autorun=True,
+                references=[ref],
+            )
+        return out
+
+    def _hidden_files(self, key: str, node: Node, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        benign = set(_settings_data()["benign_exclude_patterns"])
+        out: list[Finding] = []
+        for pattern, val in node.items():
+            if val.value is not True or pattern in benign:
+                continue
+            glob = pattern.replace("**/", "*").replace("/**", "/*")
+            hidden = [
+                r.rel
+                for r in ctx.inventory.files
+                if (fnmatch.fnmatchcase(r.rel, glob) or fnmatch.fnmatchcase(r.rel, glob + "/*"))
+                and _looks_like_code_path(r.rel)
+            ]
+            if hidden:
+                shown = ", ".join(hidden[:5]) + (" …" if len(hidden) > 5 else "")
+                out.append(
+                    build_finding(
+                        R_SETTING_HIDE.id,
+                        [fv.evidence_at_line(val.line)],
+                        detail=f"{key} pattern {pattern!r} hides: {shown}.",
+                    )
+                )
+        return out
+
+    # ------------------------------------------------------------------ extensions
+    def _extensions(self, root: Node, fv: FileView) -> list[Finding]:
+        recs = root.get("recommendations")
+        ids = [e.value for e in (recs.elements() if recs else []) if isinstance(e.value, str)]
+        if not ids:
+            return []
+        shown = ", ".join(make_excerpt(i, limit=80) for i in ids[:15])
+        return [
+            build_finding(
+                R_EXT_RECOMMEND.id, [fv.evidence_at_line(recs.line if recs else None)], detail=f"Recommended: {shown}."
+            )
+        ]
+
+
+def _run_on(task: Node) -> str | None:
+    ro = task.get("runOptions")
+    run_on = ro.get("runOn") if ro is not None else None
+    return run_on.value if run_on is not None and isinstance(run_on.value, str) else None
+
+
+def _hides_output(task: Node) -> bool:
+    pres = task.get("presentation")
+    if pres is None:
+        return False
+    reveal = pres.get("reveal")
+    echo = pres.get("echo")
+    close = pres.get("close")
+    return (
+        (reveal is not None and reveal.value == "never")
+        or (echo is not None and echo.value is False)
+        or (close is not None and close.value is True)
+    )
+
+
+def _task_commands(task: Node) -> list[tuple[str, str, int]]:
+    out: list[tuple[str, str, int]] = []
+    ttype = task.get("type")
+    if ttype is not None and ttype.value == "npm":
+        script = task.get("script")
+        if script is not None and isinstance(script.value, str):
+            out.append(("base", f"npm run {script.value}", script.line))
+    for scope, node in [("base", task), *[(o, task.get(o)) for o in ("windows", "linux", "osx")]]:
+        if node is None:
+            continue
+        cmd_node = node.get("command")
+        cmd = command_text(cmd_node)
+        if cmd is None:
+            continue
+        full = " ".join([cmd, *args_text(node.get("args"))])
+        out.append((scope, full, cmd_node.line if cmd_node else node.line))
+    return out
+
+
+def _program(cmd: str) -> str:
+    first = cmd.strip().split()[0] if cmd.strip() else ""
+    return first.rsplit("/", 1)[-1].rsplit("\\", 1)[-1].lower()
+
+
+def _flatten_settings(root: Node) -> list[tuple[str, Node]]:
+    out: list[tuple[str, Node]] = []
+    for key, node in root.items():
+        if key.startswith("[") and key.endswith("]"):  # language-specific block
+            out.extend(_flatten_settings(node))
+        else:
+            out.append((key, node))
+    return out
+
+
+def _looks_like_code_path(rel: str) -> bool:
+    from devguard.core.filetype import language_for
+
+    return language_for(rel, None) in _CODE_LANGS or rel.endswith(
+        (".exe", ".dll", ".so", ".dylib", ".woff", ".woff2", ".ttf")
+    )