codeguard-cli 2.0.0__py3-none-any.whl

codeguard/lang/javascript.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+"""JavaScript language support (tree-sitter)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import Language
+from .treesitter import TreeSitterSupport, _load_language
+
+if TYPE_CHECKING:
+    import tree_sitter
+
+
+class JavaScriptSupport(TreeSitterSupport):
+    language = Language.JAVASCRIPT
+    extensions = (".js", ".jsx", ".mjs", ".cjs")
+
+    def _ts_language(self) -> tree_sitter.Language:
+        return _load_language("tree_sitter_javascript", "language")

codeguard/lang/node.py

@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``SourceNode`` -- the uniform tree node handed to rules.
+
+A rule that targets a single language may reach through to the parser-native
+node via :attr:`SourceNode.native` -- an :class:`ast.AST` for Python, a
+``tree_sitter.Node`` for JavaScript / TypeScript.  Rules that span languages
+should stick to the wrapper's own API (:meth:`walk`, :meth:`children`,
+:meth:`child_by_field`, :meth:`text`, :attr:`kind`).
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterator
+from dataclasses import dataclass
+from functools import cached_property
+
+from .base import Language, Position
+
+
+def _is_ts_node(obj: object) -> bool:
+    """Duck-type a tree_sitter.Node without importing tree_sitter."""
+    return hasattr(obj, "type") and hasattr(obj, "start_point") and hasattr(obj, "children")
+
+
+@dataclass(frozen=True)
+class SourceNode:
+    """A read-only wrapper over one parser node."""
+
+    native: object
+    language: Language
+    source: str
+
+    # ------------------------------------------------------------------
+    # Identity
+    # ------------------------------------------------------------------
+
+    @cached_property
+    def kind(self) -> str:
+        """A normalized node-type name.
+
+        ``ast`` backend: the lower-cased class name (``"call"``, ``"assign"``).
+        tree-sitter backend: the grammar's node type (``"call_expression"``,
+        ``"member_expression"``).
+        """
+        if isinstance(self.native, ast.AST):
+            return type(self.native).__name__.lower()
+        if _is_ts_node(self.native):
+            return str(self.native.type)  # type: ignore[attr-defined]
+        return type(self.native).__name__
+
+    # ------------------------------------------------------------------
+    # Position (1-indexed line and column)
+    # ------------------------------------------------------------------
+
+    @cached_property
+    def start(self) -> Position:
+        node = self.native
+        if isinstance(node, ast.AST):
+            return Position(
+                line=max(getattr(node, "lineno", 1), 1),
+                col=getattr(node, "col_offset", 0) + 1,
+            )
+        if _is_ts_node(node):
+            row, col = node.start_point  # type: ignore[attr-defined]
+            return Position(line=row + 1, col=col + 1)
+        raise TypeError(f"start position unavailable for {node!r}")
+
+    @cached_property
+    def end(self) -> Position | None:
+        node = self.native
+        if isinstance(node, ast.AST):
+            line = getattr(node, "end_lineno", None)
+            col = getattr(node, "end_col_offset", None)
+            if line is None or col is None:
+                return None
+            return Position(line=max(line, 1), col=col + 1)
+        if _is_ts_node(node):
+            row, col = node.end_point  # type: ignore[attr-defined]
+            return Position(line=row + 1, col=col + 1)
+        return None
+
+    # ------------------------------------------------------------------
+    # Traversal
+    # ------------------------------------------------------------------
+
+    def _wrap(self, native: object) -> SourceNode:
+        return SourceNode(native=native, language=self.language, source=self.source)
+
+    def text(self) -> str:
+        """The source slice this node spans (best effort)."""
+        if isinstance(self.native, ast.AST):
+            segment = ast.get_source_segment(self.source, self.native)
+            return segment if segment is not None else ""
+        if _is_ts_node(self.native):
+            raw = self.native.text  # type: ignore[attr-defined]
+            return raw.decode("utf-8", "replace") if raw is not None else ""
+        return ""
+
+    def children(self) -> list[SourceNode]:
+        if isinstance(self.native, ast.AST):
+            return [self._wrap(c) for c in ast.iter_child_nodes(self.native)]
+        if _is_ts_node(self.native):
+            return [self._wrap(c) for c in self.native.children]  # type: ignore[attr-defined]
+        return []
+
+    def child_by_field(self, name: str) -> SourceNode | None:
+        """The named child (tree-sitter field), or ``None``.
+
+        For the ``ast`` backend, *name* is an attribute name; a list-valued
+        attribute yields its first element.
+        """
+        if _is_ts_node(self.native):
+            child = self.native.child_by_field_name(name)  # type: ignore[attr-defined]
+            return self._wrap(child) if child is not None else None
+        if isinstance(self.native, ast.AST):
+            value = getattr(self.native, name, None)
+            if isinstance(value, ast.AST):
+                return self._wrap(value)
+            if isinstance(value, list) and value and isinstance(value[0], ast.AST):
+                return self._wrap(value[0])
+        return None
+
+    def walk(self) -> Iterator[SourceNode]:
+        """Yield this node and every descendant, pre-order."""
+        if isinstance(self.native, ast.AST):
+            for n in ast.walk(self.native):
+                yield self._wrap(n)
+            return
+        if _is_ts_node(self.native):
+            stack = [self.native]
+            while stack:
+                node = stack.pop()
+                yield self._wrap(node)
+                stack.extend(reversed(node.children))  # type: ignore[attr-defined]
+            return
+        yield self

codeguard/lang/python_ast.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Python language support, backed by the standard library :mod:`ast`."""
+
+from __future__ import annotations
+
+import ast
+
+from .base import Language, LanguageSupport, ParseResult, SyntaxErrorInfo
+from .node import SourceNode
+
+
+class PythonAstSupport(LanguageSupport):
+    """Parse Python with :func:`ast.parse`."""
+
+    language = Language.PYTHON
+    extensions = (".py", ".pyi")
+    comment_prefixes = ("#",)
+
+    def parse(self, source: str, filename: str) -> ParseResult:
+        try:
+            tree = ast.parse(source, filename=filename)
+        except SyntaxError as exc:
+            return ParseResult(
+                root=None,
+                ok=False,
+                error=SyntaxErrorInfo(message=exc.msg, line=exc.lineno, col=exc.offset),
+            )
+        root = SourceNode(native=tree, language=Language.PYTHON, source=source)
+        return ParseResult(root=root, ok=True)

codeguard/lang/registry.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Registry of available :class:`~codeguard.lang.base.LanguageSupport` backends."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import Language, LanguageSupport
+from .javascript import JavaScriptSupport
+from .python_ast import PythonAstSupport
+from .typescript import TypeScriptSupport
+
+#: All registered language backends, keyed by :class:`Language`.
+LANGUAGES: dict[Language, LanguageSupport] = {
+    Language.PYTHON: PythonAstSupport(),
+    Language.JAVASCRIPT: JavaScriptSupport(),
+    Language.TYPESCRIPT: TypeScriptSupport(),
+}
+
+_EXTENSION_INDEX: dict[str, Language] = {
+    ext: lang for lang, support in LANGUAGES.items() for ext in support.extensions
+}
+
+
+def language_for_path(path: str | Path) -> Language | None:
+    """Return the language for *path* based on its extension, or ``None``."""
+    return _EXTENSION_INDEX.get(Path(path).suffix.lower())
+
+
+def support_for(language: Language) -> LanguageSupport:
+    """Return the backend for *language*.
+
+    Raises
+    ------
+    KeyError
+        If no backend is registered for *language*.
+    """
+    return LANGUAGES[language]

codeguard/lang/treesitter.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base class for tree-sitter-backed language support."""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from functools import cache
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .base import LanguageSupport, ParseResult, SyntaxErrorInfo
+from .node import SourceNode
+
+if TYPE_CHECKING:
+    import tree_sitter
+
+_QUERY_DIR = Path(__file__).parent / "queries"
+
+
+class TreeSitterSupport(LanguageSupport):
+    """Parse a language with tree-sitter.
+
+    Subclasses supply :meth:`_ts_language`.  The parser and any ``.scm`` queries
+    are created lazily and cached, so a scan that never touches this language
+    never imports ``tree_sitter``.
+    """
+
+    comment_prefixes = ("//", "/*")
+
+    def __init__(self) -> None:
+        self._parser: tree_sitter.Parser | None = None
+        self._queries: dict[str, Any] = {}
+
+    @abstractmethod
+    def _ts_language(self) -> tree_sitter.Language:
+        """Return the compiled tree-sitter grammar for this language."""
+
+    @property
+    def _parser_obj(self) -> tree_sitter.Parser:
+        if self._parser is None:
+            import tree_sitter
+
+            self._parser = tree_sitter.Parser(self._ts_language())
+        return self._parser
+
+    def parse(self, source: str, filename: str) -> ParseResult:
+        tree = self._parser_obj.parse(source.encode("utf-8"))
+        root = tree.root_node
+
+        # tree-sitter is error-recovering: a stray token deep in the file still
+        # yields a usable tree.  Only bail if nothing meaningful parsed.
+        meaningful = [c for c in root.children if c.type not in ("ERROR", "comment")]
+        if root.has_error and not meaningful:
+            err = _first_error(root)
+            return ParseResult(
+                root=None,
+                ok=False,
+                error=SyntaxErrorInfo(
+                    message="could not parse",
+                    line=(err.start_point[0] + 1) if err else None,
+                    col=(err.start_point[1] + 1) if err else None,
+                ),
+            )
+
+        node = SourceNode(native=root, language=self.language, source=source)
+        return ParseResult(root=node, ok=True)
+
+    def query(self, name: str) -> Any | None:
+        if name in self._queries:
+            return self._queries[name]
+        path = _QUERY_DIR / self.language.value / f"{name}.scm"
+        if not path.is_file():
+            self._queries[name] = None
+            return None
+        import tree_sitter
+
+        compiled = tree_sitter.Query(self._ts_language(), path.read_text(encoding="utf-8"))
+        self._queries[name] = compiled
+        return compiled
+
+
+def _first_error(node: tree_sitter.Node) -> tree_sitter.Node | None:
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        if n.is_error or n.is_missing:
+            return n
+        stack.extend(n.children)
+    return None
+
+
+@cache
+def _load_language(module_name: str, func_name: str) -> tree_sitter.Language:
+    import importlib
+
+    import tree_sitter
+
+    mod = importlib.import_module(module_name)
+    return tree_sitter.Language(getattr(mod, func_name)())

codeguard/lang/typescript.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""TypeScript language support (tree-sitter).
+
+The ``.tsx`` grammar is a superset that also parses ``.ts``; using it for both
+keeps things simple and still parses plain TypeScript correctly.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import Language
+from .treesitter import TreeSitterSupport, _load_language
+
+if TYPE_CHECKING:
+    import tree_sitter
+
+
+class TypeScriptSupport(TreeSitterSupport):
+    language = Language.TYPESCRIPT
+    extensions = (".ts", ".tsx", ".mts", ".cts")
+
+    def _ts_language(self) -> tree_sitter.Language:
+        return _load_language("tree_sitter_typescript", "language_tsx")

codeguard/py.typed

@@ -0,0 +1 @@
+# PEP 561 — this package ships inline type annotations

codeguard/rules/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+"""All CodeGuard rules — importing this module loads every built-in rule."""
+
+from . import javascript as _javascript  # noqa: F401
+from . import meta as _meta  # noqa: F401
+from . import security as _security  # noqa: F401

codeguard/rules/_jsnodes.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Small helpers for JavaScript / TypeScript rules over a tree-sitter tree.
+
+These operate on :class:`~codeguard.lang.node.SourceNode`, so a rule stays a few
+lines: walk the calls, read the callee text, check whether an argument is a
+literal.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from codeguard.lang.node import SourceNode
+
+_PUNCT = {"(", ")", ",", "[", "]", "{", "}", ";"}
+_SECRET_NAME = (
+    "password",
+    "passwd",
+    "pwd",
+    "passphrase",
+    "secret",
+    "apikey",
+    "api_key",
+    "accesskey",
+    "access_key",
+    "secretkey",
+    "secret_key",
+    "privatekey",
+    "private_key",
+    "token",
+    "auth_token",
+    "authtoken",
+    "client_secret",
+    "clientsecret",
+    "aws_secret",
+)
+
+
+def calls(root: SourceNode) -> Iterator[SourceNode]:
+    """Yield every ``call_expression`` node."""
+    for node in root.walk():
+        if node.kind == "call_expression":
+            yield node
+
+
+def new_expressions(root: SourceNode) -> Iterator[SourceNode]:
+    for node in root.walk():
+        if node.kind == "new_expression":
+            yield node
+
+
+def callee_text(call: SourceNode) -> str:
+    """The called expression as source text (``"eval"``, ``"cp.execSync"``)."""
+    fn = call.child_by_field("function") or call.child_by_field("constructor")
+    return fn.text() if fn else ""
+
+
+def arguments(call: SourceNode) -> list[SourceNode]:
+    """The argument nodes of a call, punctuation stripped."""
+    args_node = call.child_by_field("arguments")
+    if args_node is None:
+        return []
+    return [c for c in args_node.children() if c.kind not in _PUNCT]
+
+
+def is_literal(node: SourceNode) -> bool:
+    """True if *node* is a constant: a string / number / boolean literal, a
+    template string with no ``${}`` substitutions, or a ``+`` tree of those."""
+    kind = node.kind
+    if kind in ("string", "number", "true", "false", "regex"):
+        return True
+    if kind == "template_string":
+        return not any(d.kind == "template_substitution" for d in node.walk())
+    if kind in ("binary_expression", "parenthesized_expression"):
+        children = [c for c in node.children() if c.kind not in ("+", "(", ")")]
+        return bool(children) and all(is_literal(c) for c in children)
+    return False
+
+
+def looks_like_secret(name: str) -> bool:
+    low = name.lower()
+    return any(marker in low for marker in _SECRET_NAME)

codeguard/rules/_pyimports.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Resolve call targets through Python import aliases.
+
+Rules that match ``module.function(...)`` calls need to see through the ways an
+import can rename things::
+
+    import subprocess as sp        # sp.run(...)      -> ("subprocess", "run")
+    from subprocess import run     # run(...)         -> ("subprocess", "run")
+    from os import system as sh    # sh(...)          -> ("os", "system")
+
+:class:`ImportMap` builds these tables once per file; :meth:`ImportMap.resolve_call`
+maps a call node to a canonical ``(module, name)`` pair.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ImportMap:
+    """Import aliases in one module."""
+
+    #: local name -> canonical module  (``"sp"`` -> ``"subprocess"``)
+    module_aliases: dict[str, str] = field(default_factory=dict)
+    #: local name -> (canonical module, original attribute)
+    symbol_imports: dict[str, tuple[str, str]] = field(default_factory=dict)
+
+    @classmethod
+    def from_tree(cls, tree: ast.AST) -> ImportMap:
+        m = cls()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    top = alias.name.split(".")[0]
+                    m.module_aliases[alias.asname or alias.name] = alias.name
+                    m.module_aliases.setdefault(top, top)
+            elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+                for alias in node.names:
+                    local = alias.asname or alias.name
+                    m.symbol_imports[local] = (node.module, alias.name)
+        return m
+
+    def resolve_call(self, func: ast.expr) -> tuple[str | None, str | None]:
+        """Return the canonical ``(module, name)`` a call's *func* refers to.
+
+        - ``module.attr(...)`` -> ``(canonical_module, attr)``
+        - a bare name bound by ``from module import name`` -> ``(module, name)``
+        - any other bare name -> ``(None, name)``
+        - anything else -> ``(None, None)``
+        """
+        if isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+            base = self.module_aliases.get(func.value.id, func.value.id)
+            return base, func.attr
+        if isinstance(func, ast.Name):
+            if func.id in self.symbol_imports:
+                return self.symbol_imports[func.id]
+            return None, func.id
+        return None, None

codeguard/rules/javascript/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+"""JavaScript / TypeScript security rules (imported for side-effect)."""
+
+from . import cg_sec_101_dynamic_code as _101  # noqa: F401
+from . import cg_sec_102_child_process as _102  # noqa: F401
+from . import cg_sec_103_dom_xss as _103  # noqa: F401
+from . import cg_sec_104_react_dangerous_html as _104  # noqa: F401
+from . import cg_sec_105_hardcoded_secret as _105  # noqa: F401
+from . import cg_sec_106_weak_random as _106  # noqa: F401

codeguard/rules/javascript/cg_sec_101_dynamic_code.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CG-SEC-101 -- dynamic code execution in JavaScript / TypeScript.
+
+Flags:
+  - ``eval(x)`` where *x* is not a literal
+  - ``new Function(..., body)`` where an argument is not a literal
+  - ``setTimeout("...", n)`` / ``setInterval("...", n)`` -- passing a string to a
+    timer is an implicit ``eval``
+
+CWE-95 (CWE-94), OWASP A03:2021.  These are the classic "run a string as code"
+sinks; AI-generated code reaches for them for dynamic dispatch.
+"""
+
+from __future__ import annotations
+
+from codeguard.engine.context import RuleContext
+from codeguard.engine.finding import Category, Finding, Severity
+from codeguard.engine.registry import REGISTRY
+from codeguard.engine.rule import TreeSitterRule
+from codeguard.lang.base import Language
+from codeguard.lang.node import SourceNode
+from codeguard.rules._jsnodes import arguments, callee_text, calls, is_literal, new_expressions
+
+_JS_TS = frozenset({Language.JAVASCRIPT, Language.TYPESCRIPT})
+_TIMERS = frozenset({"setTimeout", "setInterval"})
+_FIX = (
+    "Do not execute strings as code. Use a lookup table of functions, dynamic "
+    "import(), or pass a function (not a string) to setTimeout/setInterval."
+)
+
+
+class DynamicCodeExecutionRule(TreeSitterRule):
+    id = "CG-SEC-101"
+    title = "Dynamic code execution (eval / Function / string timer)"
+    description = (
+        "A string is executed as code via eval(), new Function(), or a string "
+        "argument to setTimeout/setInterval. If any part of it is attacker-"
+        "controlled this is remote code execution."
+    )
+    severity = Severity.HIGH
+    category = Category.SECURITY
+    languages = _JS_TS
+    cwe = "CWE-95"
+    owasp = "A03:2021 - Injection"
+
+    def check_tree(self, root: SourceNode, ctx: RuleContext) -> list[Finding]:
+        findings: list[Finding] = []
+
+        for call in calls(root):
+            base = callee_text(call).rsplit(".", 1)[-1]
+            args = arguments(call)
+            if not args:
+                continue
+            if base == "eval" and not is_literal(args[0]):
+                findings.append(self._make_finding(node=call, ctx=ctx, fix_suggestion=_FIX))
+            elif base in _TIMERS and args[0].kind in ("string", "template_string"):
+                findings.append(
+                    self._make_finding(
+                        node=call,
+                        ctx=ctx,
+                        description=(
+                            f"{base}() is called with a string. The string is run through "
+                            "eval() when the timer fires. Pass a function instead."
+                        ),
+                        fix_suggestion=_FIX,
+                    )
+                )
+
+        for new_expr in new_expressions(root):
+            if callee_text(new_expr).rsplit(".", 1)[-1] != "Function":
+                continue
+            args = arguments(new_expr)
+            if args and not all(is_literal(a) for a in args):
+                findings.append(
+                    self._make_finding(
+                        node=new_expr,
+                        ctx=ctx,
+                        description=(
+                            "new Function() builds a function from a string body. If the "
+                            "body is attacker-controlled this is arbitrary code execution."
+                        ),
+                        fix_suggestion=_FIX,
+                    )
+                )
+
+        return findings
+
+
+REGISTRY.register(DynamicCodeExecutionRule())

codeguard/rules/javascript/cg_sec_102_child_process.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CG-SEC-102 -- shell command injection via child_process.
+
+``child_process.exec`` / ``execSync`` run their argument through ``/bin/sh``.
+With a non-literal command that is CWE-78.  ``execFile`` / ``spawn`` /
+``spawnSync`` do not use a shell (unless ``shell: true``) and are the fix.
+"""
+
+from __future__ import annotations
+
+from codeguard.engine.context import RuleContext
+from codeguard.engine.finding import Category, Finding, Severity
+from codeguard.engine.registry import REGISTRY
+from codeguard.engine.rule import TreeSitterRule
+from codeguard.lang.base import Language
+from codeguard.lang.node import SourceNode
+from codeguard.rules._jsnodes import arguments, callee_text, calls, is_literal
+
+_JS_TS = frozenset({Language.JAVASCRIPT, Language.TYPESCRIPT})
+_SHELL_FUNCS = frozenset({"exec", "execSync"})
+_FIX = (
+    "Use execFile() / spawn() with an argument array and no shell: "
+    "execFile('git', ['checkout', branch]). If a shell is unavoidable, validate "
+    "every interpolated value."
+)
+
+
+class ChildProcessShellRule(TreeSitterRule):
+    id = "CG-SEC-102"
+    title = "child_process.exec with a dynamic command"
+    description = (
+        "child_process.exec / execSync run the command through a shell. If the "
+        "command string is not a literal and any part is attacker-controlled, "
+        "this is shell command injection."
+    )
+    severity = Severity.HIGH
+    category = Category.SECURITY
+    languages = _JS_TS
+    cwe = "CWE-78"
+    owasp = "A03:2021 - Injection"
+
+    def check_tree(self, root: SourceNode, ctx: RuleContext) -> list[Finding]:
+        findings: list[Finding] = []
+        for call in calls(root):
+            callee = callee_text(call)
+            base = callee.rsplit(".", 1)[-1]
+            if base not in _SHELL_FUNCS:
+                continue
+            # A bare exec() that isn't a member access is probably unrelated.
+            if base == callee and "." not in callee:
+                continue
+            args = arguments(call)
+            if args and not is_literal(args[0]):
+                findings.append(self._make_finding(node=call, ctx=ctx, fix_suggestion=_FIX))
+        return findings
+
+
+REGISTRY.register(ChildProcessShellRule())