apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/analysis/sink_evidence.py

@@ -0,0 +1,333 @@
+"""
+Sink-evidence collection for data flows.
+
+For each DataFlow, this module analyses the call site where tainted data
+arrives (the *sink*) and produces a ``CallSiteEvidence`` record that captures
+structural facts about the call:
+
+* **Argument construction** – is the tainted argument a string interpolation,
+  a concatenation, a direct variable pass, etc.?
+* **Co-arguments** – what other arguments (literal strings, keyword flags,
+  containers) are present alongside the tainted one?
+* **String patterns** – do literal string arguments contain SQL placeholders,
+  URL schemes, template syntax, or shell metacharacters?
+
+These are pure structural facts.  The cloud interprets them to assess risk.
+
+The same ``CallSiteEvidence`` model is reusable for *transformation* call
+sites (Gap 1 retrofit) – see ``build_evidence_for_call_site``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ..parsing.base import ParsedArgument, ParsedCallSite, ParsedFile
+
+
+# ---------------------------------------------------------------------------
+# Argument-construction classification
+# ---------------------------------------------------------------------------
+
+
+class ArgumentConstructionMethod:
+    """Language-neutral vocabulary for how an argument value is constructed."""
+
+    DIRECT = "direct"
+    STRING_INTERPOLATION = "string_interpolation"
+    STRING_CONCATENATION = "string_concatenation"
+    FORMAT_CALL = "format_call"
+    CALL_WRAPPED = "call_wrapped"
+    COLLECTION = "collection"
+    SPREAD = "spread"
+
+
+def classify_argument_construction(arg: ParsedArgument) -> str:
+    """Determine how a single argument's value was constructed (language-neutral)."""
+    if arg.is_spread or arg.is_keyword_spread:
+        return ArgumentConstructionMethod.SPREAD
+    if arg.is_string_interpolation:
+        return ArgumentConstructionMethod.STRING_INTERPOLATION
+    if arg.is_concatenation:
+        return ArgumentConstructionMethod.STRING_CONCATENATION
+    if arg.is_format_call:
+        return ArgumentConstructionMethod.FORMAT_CALL
+    if arg.is_call_result:
+        return ArgumentConstructionMethod.CALL_WRAPPED
+    if arg.container_type:
+        return ArgumentConstructionMethod.COLLECTION
+    return ArgumentConstructionMethod.DIRECT
+
+
+# ---------------------------------------------------------------------------
+# String-pattern detection (data-driven, language-agnostic)
+# ---------------------------------------------------------------------------
+
+
+class StringPatternType:
+    SQL_PLACEHOLDER = "sql_placeholder"
+    SQL_KEYWORD = "sql_keyword"
+    URL_SCHEME = "url_scheme"
+    TEMPLATE_SYNTAX = "template_syntax"
+    SHELL_METACHAR = "shell_metachar"
+    HTML_TAG = "html_tag"
+    PATH_TRAVERSAL = "path_traversal"
+    REGEX_ANCHOR = "regex_anchor"
+
+
+@dataclass
+class DetectedStringPattern:
+    pattern_type: str
+    matched: str
+    argument_position: int | None = None
+
+
+_PATTERN_RULES: list[tuple[str, re.Pattern[str]]] = [
+    (
+        StringPatternType.SQL_PLACEHOLDER,
+        re.compile(
+            r"(?:%s|%\(\w+\)s|\?\??|:\w+|\$\d+|\$\{\w+\})",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        StringPatternType.SQL_KEYWORD,
+        re.compile(
+            r"\b(?:SELECT|INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|WHERE|FROM|JOIN|UNION|INTO|VALUES|SET|ORDER\s+BY|GROUP\s+BY|HAVING|LIMIT|OFFSET|EXEC(?:UTE)?)\b",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        StringPatternType.URL_SCHEME,
+        re.compile(
+            r"https?://|ftp://|file://|s3://",
+        ),
+    ),
+    (
+        StringPatternType.TEMPLATE_SYNTAX,
+        re.compile(
+            r"\{\{.*?\}\}|\{%.*?%\}|\$\{[^}]+\}|<%=.*?%>",
+        ),
+    ),
+    (
+        StringPatternType.SHELL_METACHAR,
+        re.compile(
+            r"(?:\|\||&&|[;|`]|\$\(|\$\{)",
+        ),
+    ),
+    (
+        StringPatternType.HTML_TAG,
+        re.compile(
+            r"<(?:script|iframe|img|object|embed|form|input|style|link|meta|svg|base)\b",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        StringPatternType.PATH_TRAVERSAL,
+        re.compile(
+            r"\.\./|~/",
+        ),
+    ),
+    (
+        StringPatternType.REGEX_ANCHOR,
+        re.compile(
+            r"(?:^\^|\$$|\\[bdwsDWBZ])",
+        ),
+    ),
+]
+
+
+def detect_string_patterns(
+    value: str,
+    argument_position: int | None = None,
+) -> list[DetectedStringPattern]:
+    """Scan a literal string for well-known patterns."""
+    results: list[DetectedStringPattern] = []
+    seen: set[tuple[str, str]] = set()
+    for ptype, regex in _PATTERN_RULES:
+        for m in regex.finditer(value):
+            matched = m.group()
+            key = (ptype, matched)
+            if key not in seen:
+                seen.add(key)
+                results.append(
+                    DetectedStringPattern(
+                        pattern_type=ptype,
+                        matched=matched,
+                        argument_position=argument_position,
+                    )
+                )
+    return results
+
+
+# ---------------------------------------------------------------------------
+# CallSiteEvidence builder (reusable for sinks AND transformations)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ArgumentEvidence:
+    """Language-agnostic evidence about one argument at a call site."""
+
+    position: int | None
+    name: str | None
+    is_literal: bool
+    literal_value: str | None
+    literal_type: str | None
+    is_variable: bool
+    variable_name: str | None
+    is_call_result: bool
+    called_function: str | None
+    construction: str = "direct"
+    container_type: str | None = None
+    source_variables: list[str] = field(default_factory=list)
+    expression_text: str | None = None
+    is_tainted: bool = False
+
+
+@dataclass
+class CallSiteEvidence:
+    """Complete structural evidence about a call site."""
+
+    tainted_argument_position: int | None = None
+    tainted_argument_name: str | None = None
+    tainted_argument_construction: str | None = None
+    all_arguments: list[ArgumentEvidence] = field(default_factory=list)
+    string_patterns: list[DetectedStringPattern] = field(default_factory=list)
+
+
+def _parsed_arg_to_evidence(
+    arg: ParsedArgument,
+    is_tainted: bool = False,
+) -> ArgumentEvidence:
+    construction = classify_argument_construction(arg)
+    lit_val: str | None = None
+    if arg.is_literal and arg.literal_value is not None:
+        s = str(arg.literal_value)
+        lit_val = s[:500] if len(s) > 500 else s
+
+    expr_text: str | None = None
+    if arg.is_expression and arg.expression_text:
+        s = arg.expression_text
+        expr_text = s[:500] if len(s) > 500 else s
+
+    return ArgumentEvidence(
+        position=arg.position,
+        name=arg.name,
+        is_literal=arg.is_literal,
+        literal_value=lit_val,
+        literal_type=arg.literal_type,
+        is_variable=arg.is_variable,
+        variable_name=arg.variable_name,
+        is_call_result=arg.is_call_result,
+        called_function=arg.called_function,
+        construction=construction,
+        container_type=arg.container_type,
+        source_variables=list(arg.source_variables),
+        expression_text=expr_text,
+        is_tainted=is_tainted,
+    )
+
+
+def build_evidence_for_call_site(
+    call_site: ParsedCallSite,
+    tainted_arg_index: int | None = None,
+    tainted_arg_name: str | None = None,
+) -> CallSiteEvidence:
+    """
+    Build ``CallSiteEvidence`` for any call site.
+
+    Parameters
+    ----------
+    call_site:
+        The parsed call site (from the parser layer).
+    tainted_arg_index:
+        Position of the argument carrying tainted data (if applicable).
+    tainted_arg_name:
+        Keyword name of the argument carrying tainted data (if applicable).
+    """
+    args_evidence: list[ArgumentEvidence] = []
+    patterns: list[DetectedStringPattern] = []
+    tainted_construction: str | None = None
+
+    for arg in call_site.arguments:
+        is_this_tainted = False
+        if (
+            tainted_arg_index is not None
+            and arg.position == tainted_arg_index
+            or tainted_arg_name is not None
+            and arg.name == tainted_arg_name
+        ):
+            is_this_tainted = True
+
+        ev = _parsed_arg_to_evidence(arg, is_tainted=is_this_tainted)
+        args_evidence.append(ev)
+
+        if is_this_tainted:
+            tainted_construction = ev.construction
+
+        if arg.is_literal and arg.literal_value is not None:
+            val_str = str(arg.literal_value)
+            arg_patterns = detect_string_patterns(val_str, argument_position=arg.position)
+            patterns.extend(arg_patterns)
+
+    return CallSiteEvidence(
+        tainted_argument_position=tainted_arg_index,
+        tainted_argument_name=tainted_arg_name,
+        tainted_argument_construction=tainted_construction,
+        all_arguments=args_evidence,
+        string_patterns=patterns,
+    )
+
+
+# ---------------------------------------------------------------------------
+# SinkEvidenceCollector – post-processing step over DataFlows
+# ---------------------------------------------------------------------------
+
+
+class SinkEvidenceCollector:
+    """
+    Post-processes a list of ``DataFlow`` objects, enriching each with
+    ``CallSiteEvidence`` for the sink call site.
+
+    Requires parsed files so we can look up the ``ParsedCallSite`` at the
+    sink location.
+    """
+
+    def __init__(self, parsed_files: list[ParsedFile]) -> None:
+        self._call_sites_by_loc: dict[tuple[str, int], ParsedCallSite] = {}
+        for pf in parsed_files:
+            if not pf.success:
+                continue
+            for cs in pf.call_sites:
+                key = (str(cs.location.file), cs.location.line)
+                self._call_sites_by_loc[key] = cs
+
+    def get_call_site(
+        self,
+        file_path: Path | str,
+        line: int,
+    ) -> ParsedCallSite | None:
+        return self._call_sites_by_loc.get((str(file_path), line))
+
+    def collect_for_flow(
+        self,
+        sink_file: Path | str,
+        sink_line: int,
+        sink_arg_index: int | None,
+        sink_arg_name: str | None,
+    ) -> CallSiteEvidence | None:
+        """Build evidence for a single data flow's sink."""
+        cs = self.get_call_site(sink_file, sink_line)
+        if cs is None:
+            return None
+        return build_evidence_for_call_site(
+            cs,
+            tainted_arg_index=sink_arg_index,
+            tainted_arg_name=sink_arg_name,
+        )

apisec_code_bolt/analysis/url_prefix_resolver.py

@@ -0,0 +1,338 @@
+"""
+Cross-file URL prefix resolver for Django and Express/NestJS.
+
+Builds per-file prefix maps so that sub-urlconf and sub-router files
+can be annotated with their parent-mounted prefixes.
+
+Django: Scans call_sites for path("segment/", include("module.urls")) patterns,
+        resolves module dotted path → file path, propagates prefix chains.
+
+Express: Tracks require/import variable assignments, then finds
+         router.use("/prefix", variable) mounts and propagates chains.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..parsing.base import ParsedFile
+
+logger = logging.getLogger(__name__)
+
+
+def build_django_prefix_map(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+) -> dict[str, list[str]]:
+    """
+    Build a map of {file_path_str: [prefix, ...]} for Django URL files.
+
+    Scans for path("prefix/", include("app.urls")) patterns and propagates
+    prefix chains across files using a fixpoint algorithm (same approach as
+    the Express resolver) so that multi-level include chains are composed
+    correctly:
+      config/urls → api/    →  api/urls → auth/  →  authentication/urls
+      → authentication/urls gets ["api/auth/"]
+
+    Returns:
+        Dict mapping absolute file path strings to list of URL prefixes.
+    """
+    # Build dotted-module → file path index
+    module_to_file: dict[str, str] = {}
+    if project_root:
+        for pf in parsed_files:
+            try:
+                rel = pf.path.relative_to(project_root)
+                parts = rel.with_suffix("").parts
+                dotted = ".".join(parts)
+                module_to_file[dotted] = str(pf.path.resolve())
+                if len(parts) > 1:
+                    shorter = ".".join(parts[1:])
+                    module_to_file.setdefault(shorter, str(pf.path.resolve()))
+            except ValueError:
+                pass
+
+    file_by_stem: dict[str, list[str]] = {}
+    for pf in parsed_files:
+        stem = pf.path.stem
+        file_by_stem.setdefault(stem, []).append(str(pf.path.resolve()))
+
+    def _resolve_module(module_str: str) -> str | None:
+        if module_str in module_to_file:
+            return module_to_file[module_str]
+        for dotted, fp in module_to_file.items():
+            if dotted.endswith("." + module_str) or dotted == module_str:
+                return fp
+        last = module_str.rsplit(".", 1)[-1]
+        candidates = file_by_stem.get(last, [])
+        if len(candidates) == 1:
+            return candidates[0]
+        return None
+
+    # Build directed mount graph: (from_file_resolved, to_file_resolved, segment, call_line)
+    # call_line is used to detect variable-wrapper nesting (see step below).
+    mounts: list[tuple[str, str, str, int]] = []
+    for pf in parsed_files:
+        from_file = str(pf.path.resolve())
+        for call in pf.call_sites:
+            if call.callee_name not in ("path", "re_path", "url"):
+                continue
+            if not call.arguments or len(call.arguments) < 2:
+                continue
+
+            path_arg = call.arguments[0]
+            if not path_arg.is_literal or not isinstance(path_arg.literal_value, str):
+                continue
+            segment = path_arg.literal_value
+
+            view_arg = call.arguments[1]
+            view_text = ""
+            if view_arg.is_expression:
+                view_text = view_arg.expression_text or ""
+            elif view_arg.is_variable:
+                view_text = view_arg.variable_name or ""
+            elif view_arg.is_literal:
+                view_text = str(view_arg.literal_value)
+
+            call_line = call.location.line if call.location else 0
+
+            # Match both include("module") and include(("module", "namespace"))
+            include_match = re.search(r"include\s*\(\s*\(?\s*['\"]([^'\"]+)['\"]", view_text)
+            if include_match:
+                target_module = include_match.group(1)
+                target_file = _resolve_module(target_module)
+                if target_file:
+                    mounts.append((from_file, target_file, segment, call_line))
+
+    # Handle include(variable_name) wrappers.
+    #
+    # Pattern:
+    #   helper = [path("sub/", include("app.sub")), ...]
+    #   urlpatterns = [path("prefix/", include(helper))]
+    #
+    # The resolver only detects module-string includes; include(variable) produces
+    # no mount. But the cross-file mounts inside 'helper' need the extra "prefix/"
+    # segment composed in. We detect this by:
+    #   1. Finding path("segment/", include(var)) where var is a module-level variable.
+    #   2. Treating all mounts from the same file that appear at earlier lines
+    #      (the helper list is typically defined before urlpatterns) as nested under
+    #      that segment, replacing their bare segment with the composed one.
+    for pf in parsed_files:
+        from_file = str(pf.path.resolve())
+        for call in pf.call_sites:
+            if call.callee_name not in ("path", "re_path", "url"):
+                continue
+            if not call.arguments or len(call.arguments) < 2:
+                continue
+            path_arg = call.arguments[0]
+            if not path_arg.is_literal or not isinstance(path_arg.literal_value, str):
+                continue
+            wrapper_segment = path_arg.literal_value
+            view_arg = call.arguments[1]
+            view_text = (
+                view_arg.expression_text
+                if view_arg.is_expression
+                else (view_arg.variable_name if view_arg.is_variable else "")
+            ) or ""
+            # Detect include(variable_name) — bare identifier, not a module string
+            var_match = re.match(r"include\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)$", view_text)
+            if not var_match:
+                continue
+            var_name = var_match.group(1)
+            if var_name not in pf.module_variables:
+                continue
+            wrapper_line = call.location.line if call.location else 0
+            # Replace mounts from this file whose call line precedes the wrapper.
+            # Those mounts are inside the helper variable, not directly in urlpatterns.
+            updated: list[tuple[str, str, str, int]] = []
+            for m_from, m_to, m_seg, m_line in mounts:
+                if m_from == from_file and m_line < wrapper_line:
+                    composed_seg = _compose_url(wrapper_segment, m_seg)
+                    updated.append((m_from, m_to, composed_seg, m_line))
+                else:
+                    updated.append((m_from, m_to, m_seg, m_line))
+            mounts = updated
+
+    # Fixpoint: compose absolute prefixes through mount chains.
+    # Files absent from prefix_map are roots whose effective base prefix is "".
+    prefix_map: dict[str, list[str]] = {}
+    changed = True
+    max_iters = 20
+    iters = 0
+    while changed and iters < max_iters:
+        changed = False
+        iters += 1
+        for from_file, to_file, segment, _line in mounts:
+            from_prefixes = prefix_map.get(from_file, [""])
+            for from_prefix in from_prefixes:
+                composed = _compose_url(from_prefix, segment)
+                if to_file not in prefix_map:
+                    prefix_map[to_file] = []
+                if composed not in prefix_map[to_file]:
+                    prefix_map[to_file].append(composed)
+                    changed = True
+
+    return prefix_map
+
+
+_FASTIFY_PREFIX_RE = re.compile(r"\bprefix\s*:\s*['\"]([^'\"]+)['\"]")
+_REQUIRE_PATH_RE = re.compile(r"require\s*\(\s*['\"](\.[^'\"]+)['\"]")
+
+
+def build_express_prefix_map(
+    parsed_files: list[ParsedFile],
+    project_root: Path | None = None,
+) -> dict[str, list[str]]:
+    """
+    Build a map of {file_path_str: [prefix, ...]} for Express and Fastify router files.
+
+    Express: scans for router.use("/prefix", routerVar) patterns.
+    Fastify: scans for fastify.register(routerVar, { prefix: "/prefix" }) patterns.
+
+    Both patterns resolve the target module via the variable→file map built from
+    require() / ES imports. Handles multi-level mount chains via fixpoint propagation.
+
+    Returns:
+        Dict mapping absolute file path strings to list of URL prefixes.
+    """
+    # Build variable → file path map from require() / ES module imports
+    var_to_file: dict[str, list[str]] = {}
+
+    for pf in parsed_files:
+        for imp in pf.imports:
+            # Only local imports (start with . or /)
+            if not (imp.module.startswith(".") or imp.module.startswith("/")):
+                continue
+
+            # Resolve relative path
+            try:
+                if imp.module.startswith("."):
+                    target = (pf.path.parent / imp.module).resolve()
+                else:
+                    target = Path(imp.module)
+
+                # Try common extensions
+                for ext in (".ts", ".js", ".mjs", ""):
+                    candidate = target.with_suffix(ext) if ext else target
+                    if candidate.exists():
+                        target = candidate
+                        break
+                    # Try index file
+                    idx = target / ("index" + ext) if ext else target / "index.js"
+                    if idx.exists():
+                        target = idx
+                        break
+
+                target_str = str(target)
+            except Exception:
+                target_str = None
+
+            if not target_str:
+                continue
+
+            for name in imp.names:
+                var_to_file.setdefault(name, []).append(target_str)
+
+    # Build directed mount graph: (from_file, to_file, segment)
+    # All paths are resolved so that symlinks (e.g. /var → /private/var on macOS)
+    # don't cause mismatches between the map keys and plugin lookups.
+    mounts: list[tuple[str, str, str]] = []
+    for pf in parsed_files:
+        for call in pf.call_sites:
+            if not call.is_method_call:
+                continue
+            callee = call.callee_name.lower()
+
+            # ── Express: app.use('/prefix', router) ──────────────────────────
+            if callee == "use":
+                if not call.arguments or len(call.arguments) < 2:
+                    continue
+                prefix_arg = call.arguments[0]
+                if not prefix_arg.is_literal or not isinstance(prefix_arg.literal_value, str):
+                    continue
+                segment = prefix_arg.literal_value
+                router_arg = call.arguments[1]
+                if not router_arg.is_variable or not router_arg.variable_name:
+                    continue
+                var_name = router_arg.variable_name
+                for target_file in var_to_file.get(var_name, []):
+                    mounts.append((str(pf.path.resolve()), target_file, segment))
+
+            # ── Fastify: fastify.register(routerVar, { prefix: '/prefix' }) ──
+            elif callee == "register":
+                if not call.arguments or len(call.arguments) < 2:
+                    continue
+
+                # Extract prefix from the options object (second arg)
+                opts_arg = call.arguments[1]
+                opts_text = ""
+                if opts_arg.is_expression:
+                    opts_text = opts_arg.expression_text or ""
+                elif opts_arg.is_literal and isinstance(opts_arg.literal_value, str):
+                    opts_text = opts_arg.literal_value
+
+                prefix_m = _FASTIFY_PREFIX_RE.search(opts_text)
+                if not prefix_m:
+                    continue
+                segment = prefix_m.group(1)
+
+                # Resolve the plugin argument (first arg) to a file
+                plugin_arg = call.arguments[0]
+                target_files: list[str] = []
+                if plugin_arg.is_variable and plugin_arg.variable_name:
+                    target_files = var_to_file.get(plugin_arg.variable_name, [])
+                elif plugin_arg.is_expression and plugin_arg.expression_text:
+                    # require('./routes/users') inline
+                    req_m = _REQUIRE_PATH_RE.search(plugin_arg.expression_text)
+                    if req_m:
+                        rel_mod = req_m.group(1)
+                        try:
+                            target = (pf.path.parent / rel_mod).resolve()
+                            for ext in (".ts", ".js", ".mjs", ""):
+                                candidate = target.with_suffix(ext) if ext else target
+                                if candidate.exists():
+                                    target_files = [str(candidate)]
+                                    break
+                                idx = target / ("index" + ext) if ext else target / "index.js"
+                                if idx.exists():
+                                    target_files = [str(idx)]
+                                    break
+                        except Exception:
+                            pass
+
+                for target_file in target_files:
+                    mounts.append((str(pf.path.resolve()), target_file, segment))
+
+    # Fixpoint: compose absolute prefixes through mount chains.
+    # Files absent from prefix_map are roots whose effective base prefix is "".
+    # Example chain: app.ts("/"→routes) + routes("/blog"→blog) + blog("/writer"→writer)
+    #   → writer.ts gets ["/blog/writer"]
+    prefix_map: dict[str, list[str]] = {}
+    changed = True
+    max_iters = 20
+    iters = 0
+    while changed and iters < max_iters:
+        changed = False
+        iters += 1
+        for from_file, to_file, segment in mounts:
+            from_prefixes = prefix_map.get(from_file, [""])
+            for from_prefix in from_prefixes:
+                composed = _compose_url(from_prefix, segment)
+                if to_file not in prefix_map:
+                    prefix_map[to_file] = []
+                if composed not in prefix_map[to_file]:
+                    prefix_map[to_file].append(composed)
+                    changed = True
+
+    return prefix_map
+
+
+def _compose_url(base: str, segment: str) -> str:
+    """Compose two URL segments into a normalized absolute path."""
+    joined = base.rstrip("/") + "/" + segment.lstrip("/")
+    joined = re.sub(r"/+", "/", joined)
+    return joined or "/"

apisec_code_bolt/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface for apisec-code-bolt."""
+
+from .main import cli
+
+__all__ = ["cli"]

apisec_code_bolt/cli/exit_codes.py

@@ -0,0 +1,17 @@
+"""
+Structured exit codes for the surface CLI.
+
+Using named constants instead of bare integers makes the exit behaviour
+explicit and lets callers distinguish failure modes.
+"""
+
+
+class ExitCode:
+    """Namespace for CLI exit codes."""
+
+    SUCCESS = 0
+    MANIFEST_ERROR = 1  # Analysis completed but manifest invalid or empty
+    UPLOAD_FAILURE = 2  # Analysis OK, cloud upload failed
+    POLICY_VIOLATION = 3  # Analysis found policy violations (future)
+    CONFIG_ERROR = 4  # Configuration file invalid or missing required fields
+    AUTH_FAILURE = 5  # API key / cloud auth rejected