codeguard-cli 2.0.0__py3-none-any.whl

codeguard/engine/rule.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Abstract base classes for CodeGuard rules."""
+
+from __future__ import annotations
+
+import ast
+from abc import ABC, abstractmethod
+
+from codeguard.lang.base import Language
+from codeguard.lang.node import SourceNode
+
+from .context import RuleContext
+from .finding import Category, Finding, Location, Severity
+
+
+class Rule(ABC):
+    """Abstract base class that every CodeGuard rule implements.
+
+    Each rule detects exactly one concern.  Rules are self-contained: they
+    receive a :class:`~codeguard.engine.context.RuleContext` and return findings.
+    They have no knowledge of other rules and no persistent state.
+
+    To add a new rule, see CONTRIBUTING.md § "Adding a rule".
+
+    Class attributes
+    ----------------
+    id:
+        Stable rule identifier, e.g. ``CG-SEC-001``.  Defined on the class,
+        never on instances.  Never renumber or reuse an ID.
+    title:
+        Short (<= 80 char) human-readable title.
+    description:
+        Full explanation for developers who've never encountered this issue.
+    severity:
+        Default severity.  Override per-finding when needed.
+    category:
+        Broad category -- security, quality, performance, ai-smell.
+    languages:
+        The set of languages this rule can analyse.  The runner skips a rule
+        for any file whose language is not in this set.
+    cwe:
+        Primary CWE identifier, e.g. ``"CWE-89"``.  ``None`` if not applicable.
+    owasp:
+        OWASP category, e.g. ``"A03:2021 - Injection"``.  ``None`` if not applicable.
+    help_uri:
+        Link to the rule's documentation page.  ``None`` falls back to a
+        conventional URL derived from the rule ID.
+    wants_dataflow:
+        Opt in to the intraprocedural taint pass (a later milestone).  Ignored
+        today.
+    """
+
+    id: str
+    title: str
+    description: str
+    severity: Severity
+    category: Category
+    languages: frozenset[Language]
+    cwe: str | None = None
+    owasp: str | None = None
+    help_uri: str | None = None
+    wants_dataflow: bool = False
+
+    @abstractmethod
+    def analyze(self, ctx: RuleContext) -> list[Finding]:
+        """Analyse the file described by *ctx* and return findings.
+
+        Returns
+        -------
+        list[Finding]
+            Empty list means no findings.  Never return ``None``.
+        """
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(id={self.id!r})"
+
+
+class AstRule(Rule):
+    """Base class for Python rules that work directly on a :mod:`ast` tree.
+
+    Subclasses implement :meth:`check_ast` with the same signature CodeGuard
+    rules have always used.  This class adapts it to the language-aware
+    :meth:`Rule.analyze` protocol and centralises the 0-indexed to 1-indexed
+    column conversion in :meth:`_make_finding`.
+    """
+
+    languages = frozenset({Language.PYTHON})
+
+    def analyze(self, ctx: RuleContext) -> list[Finding]:
+        return self.check_ast(ctx.python_ast, ctx.source, ctx.filename)
+
+    @abstractmethod
+    def check_ast(self, tree: ast.AST, source: str, filename: str) -> list[Finding]:
+        """Analyse *tree* and return findings.
+
+        Parameters
+        ----------
+        tree:
+            ``ast.AST`` for the file.  Do **not** re-parse; use what you're given.
+        source:
+            Raw source text, available for line-level context if needed.
+        filename:
+            File path string -- used when constructing :class:`Location`.
+        """
+
+    # ------------------------------------------------------------------
+    # Helper for rule implementations
+    # ------------------------------------------------------------------
+
+    def _make_finding(
+        self,
+        *,
+        node: ast.AST,
+        filename: str,
+        description: str | None = None,
+        fix_suggestion: str | None = None,
+        confidence: float = 1.0,
+        severity: Severity | None = None,
+    ) -> Finding:
+        """Build a :class:`Finding` from an AST *node*.
+
+        Pulls ``lineno`` / ``col_offset`` / ``end_lineno`` / ``end_col_offset``
+        from *node* and converts the 0-indexed AST columns to CodeGuard's
+        1-indexed :class:`Location` columns.
+        """
+        line: int = getattr(node, "lineno", 1)
+        col: int = getattr(node, "col_offset", 0)
+        end_line: int | None = getattr(node, "end_lineno", None)
+        end_col: int | None = getattr(node, "end_col_offset", None)
+
+        return Finding(
+            rule_id=self.id,
+            title=self.title,
+            description=description or self.description,
+            severity=severity if severity is not None else self.severity,
+            category=self.category,
+            location=Location(
+                file=filename,
+                line=max(line, 1),
+                col=col + 1,
+                end_line=end_line,
+                end_col=None if end_col is None else end_col + 1,
+            ),
+            cwe=self.cwe,
+            owasp=self.owasp,
+            fix_suggestion=fix_suggestion,
+            confidence=confidence,
+        )
+
+
+class TreeSitterRule(Rule):
+    """Base class for rules over a tree-sitter tree (JavaScript / TypeScript).
+
+    Subclasses set ``languages`` and implement :meth:`check_tree`, working with
+    the uniform :class:`~codeguard.lang.node.SourceNode` API.
+    """
+
+    def analyze(self, ctx: RuleContext) -> list[Finding]:
+        return self.check_tree(ctx.root, ctx)
+
+    @abstractmethod
+    def check_tree(self, root: SourceNode, ctx: RuleContext) -> list[Finding]:
+        """Analyse *root* (the file's tree) and return findings."""
+
+    def _make_finding(
+        self,
+        *,
+        node: SourceNode,
+        ctx: RuleContext,
+        description: str | None = None,
+        fix_suggestion: str | None = None,
+        confidence: float = 1.0,
+        severity: Severity | None = None,
+    ) -> Finding:
+        """Build a :class:`Finding` from a :class:`SourceNode` (already 1-indexed)."""
+        start = node.start
+        end = node.end
+        return Finding(
+            rule_id=self.id,
+            title=self.title,
+            description=description or self.description,
+            severity=severity if severity is not None else self.severity,
+            category=self.category,
+            location=Location(
+                file=ctx.filename,
+                line=start.line,
+                col=start.col,
+                end_line=end.line if end else None,
+                end_col=end.col if end else None,
+            ),
+            cwe=self.cwe,
+            owasp=self.owasp,
+            fix_suggestion=fix_suggestion,
+            confidence=confidence,
+        )

codeguard/engine/runner.py

@@ -0,0 +1,267 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Analysis runner -- executes registered rules against source files.
+
+The runner is the only component that knows about both the registry and the
+file system.  Rules know nothing about files; the runner knows nothing about
+what rules detect.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable
+from datetime import date
+from pathlib import Path
+
+from codeguard.lang.base import Language
+from codeguard.lang.registry import language_for_path, support_for
+
+from . import fingerprint as _fp
+from .context import RuleContext
+from .finding import Category, Finding, Location
+from .registry import REGISTRY, RuleRegistry
+from .rule import Rule
+from .suppressions import META_EXPIRED, META_MISSING_REASON, SuppressionSet
+
+
+class AnalysisRunner:
+    """Runs registered rules against source code.
+
+    Parameters
+    ----------
+    registry:
+        Which rule registry to use.  Defaults to the module-level
+        :data:`~codeguard.engine.registry.REGISTRY` singleton.
+    rule_ids:
+        When provided, only rules whose IDs are in this collection are run.
+    """
+
+    def __init__(
+        self,
+        registry: RuleRegistry | None = None,
+        rule_ids: list[str] | None = None,
+        *,
+        now: date | None = None,
+    ) -> None:
+        self._registry = registry if registry is not None else REGISTRY
+        self._filter: set[str] | None = set(rule_ids) if rule_ids is not None else None
+        #: Date used for `until=` suppression expiry (default: today, per run).
+        self._now = now
+
+    @property
+    def _active_rules(self) -> list[Rule]:
+        if self._filter is None:
+            return self._registry.all()
+        return [r for r in self._registry.all() if r.id in self._filter]
+
+    def _rules_for(self, language: Language) -> list[Rule]:
+        return [r for r in self._active_rules if language in r.languages]
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        source: str,
+        filename: str = "<stdin>",
+        *,
+        language: Language | None = None,
+        now: date | None = None,
+    ) -> list[Finding]:
+        """Analyse *source* text and return findings, suppressions applied.
+
+        Findings are sorted by ``(location.line, rule_id)`` and carry a
+        fingerprint.  Suppressed findings are **included** with
+        ``suppressed=True``.  *now* (default today) dates ``until=`` expiry.
+
+        Parameters
+        ----------
+        source:
+            Raw source code.
+        filename:
+            Used in :class:`~codeguard.engine.finding.Location` and to detect
+            the language when *language* is not given.
+        language:
+            Force a language instead of detecting from *filename*.  Defaults to
+            Python for ``"<stdin>"``.
+
+        Raises
+        ------
+        SyntaxError
+            If *source* is not valid for its language.  :meth:`run_file` handles
+            this gracefully.
+        ValueError
+            If the language cannot be determined.
+        """
+        lang = language or language_for_path(filename) or Language.PYTHON
+        support = support_for(lang)
+
+        parsed = support.parse(source, filename)
+        if not parsed.ok or parsed.root is None:
+            err = parsed.error
+            raise SyntaxError(
+                (err.message if err else "parse error"),
+                (filename, err.line if err else None, err.col if err else None, None),
+            )
+
+        ctx = RuleContext(
+            filename=filename,
+            source=source,
+            language=lang,
+            lang=support,
+            root=parsed.root,  # type: ignore[arg-type]
+        )
+        today = now or self._now or date.today()
+        suppset = SuppressionSet.parse(source)
+        rel = _fp.relative_path(filename)
+        py_tree = ctx.python_ast if lang is Language.PYTHON else None
+        enabled_ids = {r.id for r in self._active_rules}
+
+        def _fingerprinted(f: Finding) -> Finding:
+            scope = _fp.python_scope(py_tree, f.location.line) if py_tree is not None else ""
+            return f.with_fingerprint(
+                _fp.compute(f.rule_id, rel, source, f.location.line, scope=scope)
+            )
+
+        findings: list[Finding] = []
+        meta_lines: dict[str, set[int]] = {META_MISSING_REASON: set(), META_EXPIRED: set()}
+
+        for rule in self._rules_for(lang):
+            for finding in rule.analyze(ctx):
+                line = finding.location.line
+                verdict = suppset.outcome(finding.rule_id, line, today)
+                if verdict is not None:
+                    kind, supp = verdict
+                    if kind == "suppress":
+                        finding = finding.as_suppressed()
+                        if supp.reason is None:
+                            meta_lines[META_MISSING_REASON].add(supp.line)
+                    elif kind == "expired":
+                        meta_lines[META_EXPIRED].add(supp.line)
+                findings.append(_fingerprinted(finding))
+
+        findings.extend(
+            self._meta_findings(meta_lines, suppset, filename, source, rel, py_tree, enabled_ids)
+        )
+
+        findings.sort(key=lambda f: (f.location.line, f.location.col, f.rule_id))
+        return findings
+
+    def _meta_findings(
+        self,
+        meta_lines: dict[str, set[int]],
+        suppset: SuppressionSet,
+        filename: str,
+        source: str,
+        rel: str,
+        py_tree: object,
+        enabled_ids: set[str],
+    ) -> list[Finding]:
+        out: list[Finding] = []
+        for meta_id, lines in meta_lines.items():
+            if meta_id not in enabled_ids or meta_id not in self._registry:
+                continue
+            rule = self._registry.get(meta_id)
+            assert rule is not None
+            for line in sorted(lines):
+                f = Finding(
+                    rule_id=meta_id,
+                    title=rule.title,
+                    description=rule.description,
+                    severity=rule.severity,
+                    category=Category.META,
+                    location=Location(file=filename, line=line, col=1),
+                    fix_suggestion=None,
+                )
+                # a `# codeguard: ignore[CG-META-001]` on the same line still works
+                if suppset.outcome(meta_id, line, date.max):
+                    f = f.as_suppressed()
+                scope = _fp.python_scope(py_tree, line) if py_tree is not None else ""  # type: ignore[arg-type]
+                out.append(f.with_fingerprint(_fp.compute(meta_id, rel, source, line, scope=scope)))
+        return out
+
+    def run_file(self, path: Path) -> list[Finding]:
+        """Analyse a single file on disk.
+
+        Returns an empty list (and warns) for an unsupported extension, an
+        unreadable file, or a syntax error, rather than raising.
+        """
+        lang = language_for_path(path)
+        if lang is None:
+            return []
+
+        try:
+            source = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            warnings.warn(f"Cannot read {path}: {exc}", stacklevel=2)
+            return []
+
+        try:
+            return self.run(source, filename=str(path), language=lang)
+        except SyntaxError as exc:
+            warnings.warn(
+                f"Skipping {path}: syntax error on line {exc.lineno} -- {exc.msg}",
+                SyntaxWarning,
+                stacklevel=2,
+            )
+            return []
+
+    def run_files(self, paths: Iterable[Path], *, jobs: int = 1) -> list[Finding]:
+        """Analyse an explicit list of files, optionally in parallel.
+
+        *jobs* > 1 fans the files out across a process pool; the output is
+        identical to a sequential run (findings are re-sorted after the join).
+        """
+        files = list(paths)
+        findings: list[Finding] = []
+
+        if jobs and jobs > 1 and len(files) > 1:
+            from concurrent.futures import ProcessPoolExecutor
+
+            filter_ids = sorted(self._filter) if self._filter is not None else None
+            now_iso = self._now.isoformat() if self._now is not None else None
+            with ProcessPoolExecutor(
+                max_workers=jobs,
+                initializer=_init_worker,
+                initargs=(filter_ids, now_iso),
+            ) as pool:
+                for result in pool.map(_scan_one, (str(p) for p in files)):
+                    findings.extend(result)
+        else:
+            for fp in files:
+                findings.extend(self.run_file(fp))
+
+        findings.sort(key=lambda f: (f.location.file, f.location.line, f.location.col, f.rule_id))
+        return findings
+
+    def run_path(self, path: Path, *, jobs: int = 1) -> list[Finding]:
+        """Analyse a file, or a directory (discovery defaults, recursive)."""
+        if path.is_file():
+            return self.run_file(path)
+
+        from .discovery import discover
+
+        return self.run_files(discover([path]), jobs=jobs)
+
+
+# ---------------------------------------------------------------------------
+# Process-pool workers (module level so they pickle)
+# ---------------------------------------------------------------------------
+
+_WORKER_RUNNER: AnalysisRunner | None = None
+
+
+def _init_worker(rule_ids: list[str] | None, now_iso: str | None) -> None:
+    global _WORKER_RUNNER
+    import codeguard.rules  # noqa: F401  -- register built-in rules in the child
+
+    now = date.fromisoformat(now_iso) if now_iso else None
+    _WORKER_RUNNER = AnalysisRunner(rule_ids=rule_ids, now=now)
+
+
+def _scan_one(path_str: str) -> list[Finding]:
+    assert _WORKER_RUNNER is not None  # set by _init_worker
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return _WORKER_RUNNER.run_file(Path(path_str))

codeguard/engine/suppressions.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Inline and file-level suppression comments.
+
+    # codeguard: ignore[CG-SEC-001] reason: the value is a constant
+    # codeguard: ignore[CG-SEC-001] reason: validated upstream  until=2026-12-31
+    # codeguard: ignore-file[CG-SEC-002] reason: this module generates fixtures
+
+The comment leader is ``#`` for Python, ``//`` for JavaScript / TypeScript.
+
+Every suppression should carry a ``reason:``.  One without a reason still
+suppresses, but the runner also raises **CG-META-001**.  An expired
+``until=`` suppression stops suppressing and raises **CG-META-002**.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import date
+
+META_MISSING_REASON = "CG-META-001"
+META_EXPIRED = "CG-META-002"
+
+_KEYWORD = r"(ignore|ignore-file|disable)"
+_LINE_RE = re.compile(rf"(?:#|//)\s*codeguard:\s*{_KEYWORD}\[([^\]]+)\](?P<rest>.*)$")
+_UNTIL_RE = re.compile(r"until=(\d{4}-\d{2}-\d{2})")
+_REASON_RE = re.compile(r"reason:\s*(?P<reason>.*?)(?:\s+until=\d{4}-\d{2}-\d{2}|\s*$)")
+
+
+@dataclass(frozen=True)
+class Suppression:
+    """One parsed suppression comment."""
+
+    rule_ids: frozenset[str]
+    reason: str | None
+    until: date | None
+    file_level: bool
+    line: int  # 1-indexed line of the comment (== target line for inline)
+    raw: str
+
+    def covers(self, rule_id: str) -> bool:
+        return rule_id in self.rule_ids
+
+    def is_expired(self, today: date) -> bool:
+        return self.until is not None and today > self.until
+
+
+@dataclass
+class SuppressionSet:
+    """All suppressions found in one source file."""
+
+    inline: dict[int, list[Suppression]] = field(default_factory=dict)
+    file_level: list[Suppression] = field(default_factory=list)
+
+    @classmethod
+    def parse(cls, source: str) -> SuppressionSet:
+        out = cls()
+        for lineno, text in enumerate(source.splitlines(), start=1):
+            match = _LINE_RE.search(text)
+            if not match:
+                continue
+            keyword, ids_raw = match.group(1), match.group(2)
+            rest = match.group("rest")
+            until = None
+            if (u := _UNTIL_RE.search(rest)) is not None:
+                try:
+                    until = date.fromisoformat(u.group(1))
+                except ValueError:
+                    until = None
+            reason = None
+            if (r := _REASON_RE.search(rest)) is not None:
+                candidate = r.group("reason").strip()
+                reason = candidate or None
+            supp = Suppression(
+                rule_ids=frozenset(i.strip() for i in ids_raw.split(",") if i.strip()),
+                reason=reason,
+                until=until,
+                file_level=keyword in ("ignore-file", "disable"),
+                line=lineno,
+                raw=text.strip(),
+            )
+            if supp.file_level:
+                out.file_level.append(supp)
+            else:
+                out.inline.setdefault(lineno, []).append(supp)
+        return out
+
+    def all(self) -> list[Suppression]:
+        return [s for group in self.inline.values() for s in group] + self.file_level
+
+    def _candidates(self, rule_id: str, line: int) -> list[Suppression]:
+        found = [s for s in self.inline.get(line, []) if s.covers(rule_id)]
+        found += [s for s in self.file_level if s.covers(rule_id)]
+        return found
+
+    def outcome(self, rule_id: str, line: int, today: date) -> tuple[str, Suppression] | None:
+        """Decide what a finding's suppression comment does.
+
+        - ``("suppress", s)``  -- an active suppression applies
+        - ``("expired", s)``   -- only an expired suppression applies (does NOT suppress)
+        - ``None``             -- no suppression comment covers this finding
+        """
+        candidates = self._candidates(rule_id, line)
+        if not candidates:
+            return None
+        active = [s for s in candidates if not s.is_expired(today)]
+        if active:
+            return "suppress", active[0]
+        return "expired", candidates[0]

codeguard/lang/__init__.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Language support layer.
+
+Each :class:`~codeguard.lang.base.LanguageSupport` implementation wraps a parser
+for one language and hands rules a uniform :class:`~codeguard.lang.node.SourceNode`.
+Rules declare which languages they target; the runner only invokes a rule for a
+file whose language is in that set.
+
+Python is backed by the standard library :mod:`ast`.  JavaScript and TypeScript
+(added in a later milestone) are backed by tree-sitter.
+"""
+
+from __future__ import annotations
+
+from .base import Language, LanguageSupport, ParseResult, Position, SyntaxErrorInfo
+from .javascript import JavaScriptSupport
+from .node import SourceNode
+from .python_ast import PythonAstSupport
+from .registry import LANGUAGES, language_for_path, support_for
+from .treesitter import TreeSitterSupport
+from .typescript import TypeScriptSupport
+
+__all__ = [
+    "LANGUAGES",
+    "JavaScriptSupport",
+    "Language",
+    "LanguageSupport",
+    "ParseResult",
+    "Position",
+    "PythonAstSupport",
+    "SourceNode",
+    "SyntaxErrorInfo",
+    "TreeSitterSupport",
+    "TypeScriptSupport",
+    "language_for_path",
+    "support_for",
+]

codeguard/lang/base.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Core types for the language support layer."""
+
+from __future__ import annotations
+
+import enum
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+class Language(str, enum.Enum):
+    """A source language CodeGuard can parse."""
+
+    PYTHON = "python"
+    JAVASCRIPT = "javascript"
+    TYPESCRIPT = "typescript"
+
+
+@dataclass(frozen=True)
+class Position:
+    """A 1-indexed ``(line, col)`` position.
+
+    Both coordinates are 1-indexed to match editors, SARIF, and CodeGuard's
+    :class:`~codeguard.engine.finding.Location`.  Parser-native offsets (``ast``
+    and tree-sitter are both 0-indexed for columns) are converted at the
+    boundary — rules never see a 0-indexed column.
+    """
+
+    line: int
+    col: int
+
+    def __post_init__(self) -> None:
+        if self.line < 1:
+            raise ValueError(f"line must be >= 1, got {self.line}")
+        if self.col < 1:
+            raise ValueError(f"col must be >= 1, got {self.col}")
+
+
+@dataclass(frozen=True)
+class SyntaxErrorInfo:
+    """Where and why a parse failed."""
+
+    message: str
+    line: int | None = None
+    col: int | None = None
+
+
+@dataclass(frozen=True)
+class ParseResult:
+    """Outcome of :meth:`LanguageSupport.parse`.
+
+    ``parse`` never raises for malformed input; it returns ``ok=False`` with an
+    ``error`` instead, so the runner can skip a file and warn rather than crash.
+    """
+
+    root: object | None
+    ok: bool
+    error: SyntaxErrorInfo | None = None
+
+
+class LanguageSupport(ABC):
+    """Parser adapter for one :class:`Language`."""
+
+    language: Language
+    #: File extensions (with leading dot) this language claims.
+    extensions: tuple[str, ...]
+    #: Comment leaders used for inline suppression comments, longest first.
+    comment_prefixes: tuple[str, ...]
+
+    @abstractmethod
+    def parse(self, source: str, filename: str) -> ParseResult:
+        """Parse *source*.  Never raises; returns ``ok=False`` on failure."""
+
+    def query(self, name: str) -> object | None:
+        """Return a compiled structural query by name, or ``None``.
+
+        Only meaningful for tree-sitter backends; the ``ast`` backend returns
+        ``None`` and rules walk the tree directly.
+        """
+        return None