devguard-scanner 0.1.0__py3-none-any.whl

devguard/analyzers/imports.py

@@ -0,0 +1,102 @@
+"""Static file-to-file references for multi-hop correlation (COR-003).
+
+Only literal relative paths are resolved; nothing is evaluated. Besides imports this records files that
+code reads (e.g. a loader that reads `./assets/x.woff` and evals it) because payloads are often stored
+in a second, innocent-looking file.
+"""
+
+from __future__ import annotations
+
+import re
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.core.models import Finding
+from devguard.core.safefs import normalize_rel
+
+_JS_PATTERNS = [
+    re.compile(r"""\brequire\s*\(\s*['"`](\.{1,2}/[^'"`\n]+)['"`]\s*\)"""),
+    re.compile(r"""\bimport\s+(?:[^'"`;]*?\s+from\s+)?['"`](\.{1,2}/[^'"`\n]+)['"`]"""),
+    re.compile(r"""\bimport\s*\(\s*['"`](\.{1,2}/[^'"`\n]+)['"`]\s*\)"""),
+    re.compile(r"""\bexport\s+[^'"`;]*?\s+from\s+['"`](\.{1,2}/[^'"`\n]+)['"`]"""),
+    re.compile(
+        r"""\b(?:readFileSync|readFile|createReadStream)\s*\(\s*(?:path\.(?:join|resolve)\(\s*__dirname\s*,\s*)?['"`](\.{0,2}/?[\w@][^'"`\n]*\.\w+)['"`]"""
+    ),
+]
+_PY_PATTERNS = [
+    re.compile(r"^\s*from\s+(\.+)([\w.]*)\s+import\s+([\w, ]+)", re.MULTILINE),
+    re.compile(r"""\b(?:open|run_path|exec_file)\s*\(\s*['"]([^'"\n]+\.\w+)['"]"""),
+]
+_SH_PATTERN = re.compile(
+    r"(?:^|[;&|(]\s*|\bthen\s+|\bdo\s+)(?:source|\.|bash|sh|zsh|node|python3?|pwsh|powershell)\s+['\"]?([\w./-]+\.\w+)",
+    re.MULTILINE,
+)
+_JS_EXTS = (
+    "",
+    ".js",
+    ".cjs",
+    ".mjs",
+    ".ts",
+    ".tsx",
+    ".jsx",
+    ".json",
+    "/index.js",
+    "/index.ts",
+    "/index.cjs",
+    "/index.mjs",
+)
+
+
+class ImportCollector:
+    name = "imports"
+
+    def applies(self, fv: FileView) -> bool:
+        return fv.text is not None and fv.lang in ("javascript", "python", "shell", "powershell", "batch")
+
+    def analyze(self, fv: FileView, ctx: AnalysisContext) -> list[Finding]:
+        assert fv.text is not None
+        text = fv.text[: ctx.config.limits.max_regex_text]
+        refs: set[str] = set()
+        if fv.lang == "javascript":
+            for pat in _JS_PATTERNS:
+                for m in pat.finditer(text):
+                    refs |= _resolve(ctx, fv.parent, m.group(1), _JS_EXTS)
+        elif fv.lang == "python":
+            for m in _PY_PATTERNS[0].finditer(text):
+                dots, mod, names = m.group(1), m.group(2), m.group(3)
+                base = fv.parent
+                for _ in range(len(dots) - 1):
+                    base = base.rsplit("/", 1)[0] if "/" in base else ""
+                mod_path = mod.replace(".", "/")
+                cands = [mod_path] if mod_path else [n.strip() for n in names.split(",")]
+                for c in cands:
+                    refs |= _resolve(ctx, base, c, (".py", "/__init__.py"))
+            for m in _PY_PATTERNS[1].finditer(text):
+                refs |= _resolve(ctx, fv.parent, m.group(1), ("",))
+        # Scripts usually run with the repository (or package) root as working directory, not their own dir.
+        sh_bases = [fv.parent, _repo_root_of(fv.rel), ""]
+        for m in _SH_PATTERN.finditer(text):
+            for base in sh_bases:
+                found = _resolve(ctx, base, m.group(1), ("",))
+                if found:
+                    refs |= found
+                    break
+        refs.discard(fv.rel)
+        if refs:
+            ctx.imports[fv.rel] = sorted(refs)
+        return []
+
+
+def _resolve(ctx: AnalysisContext, base: str, spec: str, exts: tuple[str, ...]) -> set[str]:
+    spec = spec.split("?", 1)[0]
+    for ext in exts:
+        cand = normalize_rel(f"{base}/{spec}{ext}" if base else f"{spec}{ext}")
+        if cand and ctx.inventory.exists(cand):
+            return {cand}
+    return set()
+
+
+def _repo_root_of(rel: str) -> str:
+    """Directory containing `.git` for files inside it (hooks), else ""."""
+    if "/.git/" in f"/{rel}":
+        return rel.split(".git/", 1)[0].rstrip("/")
+    return ""

devguard/analyzers/jsonc.py

@@ -0,0 +1,221 @@
+"""Small JSONC parser (JSON + comments + trailing commas) that keeps line numbers and duplicate keys.
+
+Duplicate keys matter: VS Code uses the last value, so an attacker can put a harmless value first
+and a malicious one later (TC-01.6). Never evaluates anything; depth and size are bounded (SAFE-007).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class JsoncError(ValueError):
+    def __init__(self, message: str, line: int) -> None:
+        super().__init__(f"{message} (line {line})")
+        self.line = line
+
+
+@dataclass
+class Node:
+    value: Any  # dict[str, Node] | list[Node] | str | int | float | bool | None
+    line: int
+    duplicates: list[tuple[str, int, int]] = field(default_factory=list)  # (key, first line, dup line)
+
+    def get(self, key: str) -> Node | None:
+        if isinstance(self.value, dict):
+            return self.value.get(key)
+        return None
+
+    def items(self) -> list[tuple[str, Node]]:
+        return list(self.value.items()) if isinstance(self.value, dict) else []
+
+    def elements(self) -> list[Node]:
+        return list(self.value) if isinstance(self.value, list) else []
+
+    def list_at(self, key: str) -> list[Node]:
+        """Elements of the array under `key`, or [] if missing / not an array."""
+        child = self.get(key)
+        return child.elements() if child is not None else []
+
+    def str_value(self) -> str | None:
+        return self.value if isinstance(self.value, str) else None
+
+    def plain(self) -> Any:
+        if isinstance(self.value, dict):
+            return {k: v.plain() for k, v in self.value.items()}
+        if isinstance(self.value, list):
+            return [v.plain() for v in self.value]
+        return self.value
+
+
+MAX_DEPTH = 64
+_ESC = {'"': '"', "\\": "\\", "/": "/", "b": "\b", "f": "\f", "n": "\n", "r": "\r", "t": "\t"}
+
+
+class _Parser:
+    def __init__(self, text: str) -> None:
+        self.s = text
+        self.i = 0
+        self.line = 1
+        self.n = len(text)
+        self.duplicates: list[tuple[str, int, int]] = []
+
+    def error(self, msg: str) -> JsoncError:
+        return JsoncError(msg, self.line)
+
+    def ws(self) -> None:
+        s, n = self.s, self.n
+        while self.i < n:
+            c = s[self.i]
+            if c == "\n":
+                self.line += 1
+                self.i += 1
+            elif c in " \t\r\ufeff":
+                self.i += 1
+            elif s.startswith("//", self.i):
+                end = s.find("\n", self.i)
+                self.i = n if end == -1 else end
+            elif s.startswith("/*", self.i):
+                end = s.find("*/", self.i + 2)
+                if end == -1:
+                    raise self.error("unterminated comment")
+                self.line += s.count("\n", self.i, end)
+                self.i = end + 2
+            else:
+                break
+
+    def parse(self) -> Node:
+        self.ws()
+        node = self.value(0)
+        self.ws()
+        if self.i != self.n:
+            raise self.error("trailing content")
+        return node
+
+    def value(self, depth: int) -> Node:
+        if depth > MAX_DEPTH:
+            raise self.error("nesting too deep")
+        self.ws()
+        if self.i >= self.n:
+            raise self.error("unexpected end of input")
+        c = self.s[self.i]
+        line = self.line
+        if c == "{":
+            return self.obj(depth)
+        if c == "[":
+            return self.arr(depth)
+        if c == '"':
+            return Node(self.string(), line)
+        if self.s.startswith("true", self.i):
+            self.i += 4
+            return Node(True, line)
+        if self.s.startswith("false", self.i):
+            self.i += 5
+            return Node(False, line)
+        if self.s.startswith("null", self.i):
+            self.i += 4
+            return Node(None, line)
+        return Node(self.number(), line)
+
+    def obj(self, depth: int) -> Node:
+        node = Node({}, self.line)
+        key_lines: dict[str, int] = {}
+        self.i += 1
+        while True:
+            self.ws()
+            if self.i < self.n and self.s[self.i] == "}":
+                self.i += 1
+                return node
+            if self.i >= self.n or self.s[self.i] != '"':
+                raise self.error("expected string key")
+            key_line = self.line
+            key = self.string()
+            self.ws()
+            if self.i >= self.n or self.s[self.i] != ":":
+                raise self.error("expected ':'")
+            self.i += 1
+            val = self.value(depth + 1)
+            if key in key_lines:
+                self.duplicates.append((key, key_lines[key], key_line))
+            key_lines[key] = key_line
+            node.value[key] = val  # last one wins, like VS Code
+            self.ws()
+            if self.i < self.n and self.s[self.i] == ",":
+                self.i += 1
+                continue
+            if self.i < self.n and self.s[self.i] == "}":
+                self.i += 1
+                return node
+            raise self.error("expected ',' or '}'")
+
+    def arr(self, depth: int) -> Node:
+        node = Node([], self.line)
+        self.i += 1
+        while True:
+            self.ws()
+            if self.i < self.n and self.s[self.i] == "]":
+                self.i += 1
+                return node
+            node.value.append(self.value(depth + 1))
+            self.ws()
+            if self.i < self.n and self.s[self.i] == ",":
+                self.i += 1
+                continue
+            if self.i < self.n and self.s[self.i] == "]":
+                self.i += 1
+                return node
+            raise self.error("expected ',' or ']'")
+
+    def string(self) -> str:
+        self.i += 1
+        out: list[str] = []
+        s = self.s
+        while self.i < self.n:
+            c = s[self.i]
+            if c == '"':
+                self.i += 1
+                return "".join(out)
+            if c == "\\":
+                self.i += 1
+                if self.i >= self.n:
+                    break
+                e = s[self.i]
+                if e == "u":
+                    hexs = s[self.i + 1 : self.i + 5]
+                    try:
+                        out.append(chr(int(hexs, 16)))
+                    except ValueError as exc:
+                        raise self.error("bad \\u escape") from exc
+                    self.i += 5
+                    continue
+                out.append(_ESC.get(e, e))
+                self.i += 1
+                continue
+            if c == "\n":
+                self.line += 1
+            out.append(c)
+            self.i += 1
+        raise self.error("unterminated string")
+
+    def number(self) -> int | float:
+        start = self.i
+        while self.i < self.n and self.s[self.i] in "+-0123456789.eExXabcdefABCDEF":
+            self.i += 1
+        tok = self.s[start : self.i]
+        if not tok:
+            raise self.error(f"unexpected character {self.s[start]!r}")
+        try:
+            return int(tok)
+        except ValueError:
+            try:
+                return float(tok)
+            except ValueError as exc:
+                raise self.error(f"bad number {tok!r}") from exc
+
+
+def parse_jsonc(text: str) -> tuple[Node, list[tuple[str, int, int]]]:
+    """Parse JSONC. Returns (root node, duplicate keys as (key, first line, duplicate line))."""
+    p = _Parser(text)
+    root = p.parse()
+    return root, p.duplicates

devguard/analyzers/surfaces/ai_assistants.py

@@ -0,0 +1,318 @@
+"""AI coding-assistant configuration: hooks, MCP servers, permissions (TC-03).
+
+Instruction files (CLAUDE.md, AGENTS.md, .cursorrules, ...) are covered by the `ai-instructions`
+content-rule pack and by the hidden-Unicode analyzer, which treats them as high-risk.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from pathlib import PurePosixPath
+
+from devguard.analyzers.base import AnalysisContext, FileView
+from devguard.analyzers.jsonc import Node
+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_HOOK = rule(
+    "DG-AI-CLAUDE-HOOK-001",
+    "Claude Code project config runs shell commands",
+    "medium",
+    "high",
+    "ai-config",
+    "TC-03.1",
+    "Project-level Claude Code settings define hooks or helper commands (statusLine, apiKeyHelper) that "
+    "run shell commands automatically during agent sessions.",
+    "Teams use hooks for formatting and linting. Check every command and the scripts it calls.",
+    "Do not start an AI assistant session in this repository until the hook commands are reviewed.",
+)
+R_PERMS = rule(
+    "DG-AI-PERMISSIONS-001",
+    "Project config grants an AI assistant broad permissions",
+    "medium",
+    "high",
+    "ai-config",
+    "TC-03.1",
+    "The project's assistant settings pre-approve broad tool use (for example unrestricted Bash, "
+    "bypassPermissions mode, or auto-accept), so the assistant can run commands without asking.",
+)
+R_MCP_AUTO = rule(
+    "DG-AI-MCP-AUTOAPPROVE-001",
+    "Project auto-approves its own MCP servers",
+    "medium",
+    "high",
+    "ai-config",
+    "TC-03.2",
+    "The project settings enable the repository's MCP servers automatically, skipping the approval prompt.",
+)
+R_MCP_SERVER = rule(
+    "DG-AI-MCP-SERVER-001",
+    "Project defines an MCP server that starts a local command",
+    "low",
+    "high",
+    "ai-config",
+    "TC-03.2",
+    "An MCP configuration in the repository starts a program when the assistant loads the project. "
+    "MCP servers run with the user's privileges.",
+    "Many projects ship MCP configs for real tools; verify the command, package names, and versions.",
+)
+R_MCP_REMOTE = rule(
+    "DG-AI-MCP-REMOTE-001",
+    "Project connects the assistant to a remote MCP server",
+    "low",
+    "medium",
+    "ai-config",
+    "TC-03.2",
+    "An MCP configuration points the assistant at a remote server. Its tools and responses can steer "
+    "the assistant, and data from the session may be sent to it.",
+)
+
+MCP_CONFIG_FILES = (
+    ".mcp.json",
+    ".cursor/mcp.json",
+    ".vscode/mcp.json",
+    ".windsurf/mcp.json",
+    ".roo/mcp.json",
+    ".kiro/settings/mcp.json",
+    ".amazonq/mcp.json",
+    ".gemini/settings.json",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".codeium/windsurf/mcp_config.json",
+    "mcp.json",
+)
+
+INSTRUCTION_PATTERNS = (
+    "CLAUDE.md",
+    "CLAUDE.local.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    ".cursorrules",
+    ".windsurfrules",
+    ".clinerules",
+    "*.mdc",
+    "copilot-instructions.md",
+    "*.instructions.md",
+    "*.prompt.md",
+    "SKILL.md",
+)
+INSTRUCTION_DIRS = (
+    ".claude/",
+    ".cursor/rules/",
+    ".windsurf/rules/",
+    ".clinerules/",
+    ".github/instructions/",
+    ".github/prompts/",
+    ".roo/rules/",
+    ".kiro/steering/",
+)
+
+_BROAD_ALLOW = re.compile(
+    r"^(Bash|Bash\(\s*\*?\s*\)|Bash\(\s*(sh|bash|zsh|curl|wget|python3?|node|npx|"
+    r"powershell|pwsh)\s*(:\s*\*)?\s*\)|\*|WebFetch|mcp__\*)$"
+)
+_PUBLIC_HTTP = re.compile(r"^http://(?!localhost|127\.|\[::1\])", re.IGNORECASE)
+
+
+def is_ai_instruction_file(rel: str) -> bool:
+    name = PurePosixPath(rel).name
+    padded = f"/{rel}"
+    if any(fnmatch.fnmatchcase(name, p) for p in INSTRUCTION_PATTERNS):
+        return True
+    return any(f"/{d}" in padded for d in INSTRUCTION_DIRS) and name.endswith((".md", ".mdc", ".txt"))
+
+
+def _matches_config(rel: str) -> bool:
+    padded = f"/{rel}"
+    return any(padded.endswith("/" + c) for c in MCP_CONFIG_FILES)
+
+
+def mcp_servers_findings(
+    servers: Node, fv: FileView, ctx: AnalysisContext, base: list[str], *, client: str
+) -> list[Finding]:
+    out: list[Finding] = []
+    for name, server in servers.items():
+        if not isinstance(server.value, dict):
+            continue
+        label = make_excerpt(name, limit=60)
+        cmd = command_text(server.get("command"))
+        if cmd:
+            full = " ".join([cmd, *args_text(server.get("args"))])
+            out.append(
+                build_finding(
+                    R_MCP_SERVER.id,
+                    [fv.evidence_at_line(server.line)],
+                    detail=f"{client} server {label!r}: {make_excerpt(full, limit=160)}",
+                )
+            )
+            out += assess_and_trigger(
+                ctx,
+                fv,
+                full,
+                server.line,
+                kind="mcp-server",
+                label=name,
+                autorun=True,
+                context=f"MCP server {label!r} ({client})",
+                base_dirs=base,
+            )
+        for key in ("url", "serverUrl", "httpUrl"):
+            u = server.get(key)
+            if u is not None and isinstance(u.value, str):
+                sev = Severity.MEDIUM if _PUBLIC_HTTP.match(u.value) else None
+                out.append(
+                    build_finding(
+                        R_MCP_REMOTE.id,
+                        [fv.evidence_at_line(u.line)],
+                        severity=sev,
+                        detail=f"{client} server {label!r} → {make_excerpt(u.value, limit=120)}",
+                    )
+                )
+        if (env := server.get("env")) is not None:
+            out += env_findings(
+                ctx, fv, env_pairs_from_node(env), context=f"MCP server {label!r} env", autorun=True, base_dirs=base
+            )
+    return out
+
+
+class AIAssistantConfigAnalyzer:
+    name = "ai-assistant-config"
+
+    def applies(self, fv: FileView) -> bool:
+        return fv.text is not None and _matches_config(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)]
+        client = _client_name(fv.rel)
+        for key in ("mcpServers", "servers"):
+            if (servers := root.get(key)) is not None:
+                out += mcp_servers_findings(servers, fv, ctx, base, client=client)
+        if fv.rel.endswith((".claude/settings.json", ".claude/settings.local.json")):
+            out += self._claude(root, fv, ctx, base)
+        if fv.rel.endswith(".gemini/settings.json"):
+            out += self._gemini(root, fv)
+        return out
+
+    def _claude(self, root: Node, fv: FileView, ctx: AnalysisContext, base: list[str]) -> list[Finding]:
+        out: list[Finding] = []
+        hooks = root.get("hooks")
+        for event, groups in hooks.items() if hooks else []:
+            for group in groups.elements():
+                for h in group.list_at("hooks"):
+                    cmd = command_text(h.get("command"))
+                    if cmd:
+                        out += self._claude_command(fv, ctx, base, cmd, h.line, f"hook {event}")
+        for key in ("statusLine", "fileSuggestion"):
+            node = root.get(key)
+            if node is not None and (cmd := command_text(node.get("command"))):
+                out += self._claude_command(fv, ctx, base, cmd, node.line, key)
+        for key in ("apiKeyHelper", "awsAuthRefresh", "awsCredentialExport", "otelHeadersHelper"):
+            node = root.get(key)
+            if node is not None and (cmd := command_text(node)):
+                out += self._claude_command(fv, ctx, base, cmd, node.line, key)
+        perms = root.get("permissions")
+        if perms is not None:
+            allow = perms.get("allow")
+            broad = [
+                e.value
+                for e in (allow.elements() if allow else [])
+                if isinstance(e.value, str) and _BROAD_ALLOW.match(e.value.strip())
+            ]
+            if broad:
+                out.append(
+                    build_finding(
+                        R_PERMS.id,
+                        [fv.evidence_at_line(allow.line if allow else None)],
+                        detail=f"Allowed without prompting: {', '.join(broad[:8])}.",
+                    )
+                )
+            mode = perms.get("defaultMode")
+            if mode is not None and mode.value == "bypassPermissions":
+                out.append(
+                    build_finding(
+                        R_PERMS.id,
+                        [fv.evidence_at_line(mode.line)],
+                        severity=Severity.HIGH,
+                        detail="defaultMode is bypassPermissions.",
+                    )
+                )
+        for key in ("enableAllProjectMcpServers", "enabledMcpjsonServers"):
+            node = root.get(key)
+            if node is not None and node.value not in (False, None, []):
+                out.append(build_finding(R_MCP_AUTO.id, [fv.evidence_at_line(node.line)], detail=f"{key} is set."))
+        if (env := root.get("env")) is not None:
+            out += env_findings(
+                ctx, fv, env_pairs_from_node(env), context="Claude Code settings env", autorun=True, base_dirs=base
+            )
+        return out
+
+    def _claude_command(
+        self, fv: FileView, ctx: AnalysisContext, base: list[str], cmd: str, line: int | None, what: str
+    ) -> list[Finding]:
+        out = [build_finding(R_HOOK.id, [fv.evidence_at_line(line)], detail=f"{what}: {make_excerpt(cmd, limit=160)}")]
+        out += assess_and_trigger(
+            ctx,
+            fv,
+            cmd,
+            line,
+            kind="claude-hook",
+            label=what,
+            autorun=True,
+            context=f"Claude Code {what}",
+            base_dirs=base,
+        )
+        return out
+
+    def _gemini(self, root: Node, fv: FileView) -> list[Finding]:
+        out: list[Finding] = []
+        for key in ("autoAccept", "yolo"):
+            node = root.get(key)
+            if node is not None and node.value is True:
+                out.append(build_finding(R_PERMS.id, [fv.evidence_at_line(node.line)], detail=f"{key} is true."))
+        tools = root.get("tools")
+        if tools is not None and (allowed := tools.get("allowed")) is not None:
+            broad = [
+                e.value
+                for e in allowed.elements()
+                if isinstance(e.value, str) and re.match(r"^run_shell_command(\(\s*\))?$", e.value)
+            ]
+            if broad:
+                out.append(
+                    build_finding(
+                        R_PERMS.id,
+                        [fv.evidence_at_line(allowed.line)],
+                        detail=f"Allowed without prompting: {', '.join(broad)}.",
+                    )
+                )
+        return out
+
+
+def _client_name(rel: str) -> str:
+    for marker, name in (
+        (".cursor/", "Cursor"),
+        (".vscode/", "VS Code"),
+        (".gemini/", "Gemini CLI"),
+        (".windsurf/", "Windsurf"),
+        (".roo/", "Roo"),
+        (".kiro/", "Kiro"),
+        (".amazonq/", "Amazon Q"),
+        (".claude/", "Claude Code"),
+    ):
+        if marker in f"/{rel}":
+            return name
+    return "MCP client (.mcp.json)"