universal-dev-security 1.0.0__py3-none-any.whl

universal_dev_security/config.py

@@ -0,0 +1,171 @@
+"""Load and validate project configuration (``.uds/config.toml``).
+
+Project configuration can only *add* restrictions. Settings that would weaken
+the mandatory global policy are ignored and reported as warnings.
+"""
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONFIG_RELATIVE_PATH = Path(".uds") / "config.toml"
+
+KNOWN_SCANNERS = ("gitleaks", "semgrep", "osv-scanner", "trivy")
+FAIL_ON_LEVELS = ("none", "unclassified", "low", "medium", "high", "critical")
+SECURITY_MODES = ("balanced", "strict")
+
+# Mandatory settings: the only accepted value is the safe one.
+MANDATORY_TRUE = (
+    "require_user_approval_for_high_risk_changes",
+    "require_user_approval_for_git_push",
+)
+
+
+class ConfigError(ValueError):
+    """Raised when the configuration file cannot be parsed."""
+
+
+@dataclass
+class ProjectConfig:
+    path: Path | None = None
+    exists: bool = False
+    project_name: str = ""
+    profile: str = "auto"
+    security_mode: str = "balanced"
+    allow_automatic_low_risk_fixes: bool = True
+    require_user_approval_for_high_risk_changes: bool = True
+    require_user_approval_for_git_push: bool = True
+    fail_on: str = "none"
+    deny_command_patterns: list[str] = field(default_factory=list)
+    approval_command_patterns: list[str] = field(default_factory=list)
+    protected_paths: list[str] = field(default_factory=list)
+    enabled_scanners: list[str] = field(default_factory=lambda: list(KNOWN_SCANNERS))
+    allow_network: bool = False
+    semgrep_configs: list[str] = field(default_factory=list)
+    scanner_timeout_seconds: int = 600
+    exclude_paths: list[str] = field(default_factory=list)
+    test_command: list[str] = field(default_factory=list)
+    test_timeout_seconds: int = 900
+    history_limit: int = 50
+    warnings: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": str(self.path) if self.path else None,
+            "exists": self.exists,
+            "project": {"name": self.project_name, "profile": self.profile},
+            "policy": {
+                "security_mode": self.security_mode,
+                "allow_automatic_low_risk_fixes": self.allow_automatic_low_risk_fixes,
+                "require_user_approval_for_high_risk_changes": self.require_user_approval_for_high_risk_changes,
+                "require_user_approval_for_git_push": self.require_user_approval_for_git_push,
+                "fail_on": self.fail_on,
+                "deny_command_patterns": self.deny_command_patterns,
+                "approval_command_patterns": self.approval_command_patterns,
+                "protected_paths": self.protected_paths,
+            },
+            "scanners": {
+                "enabled": self.enabled_scanners,
+                "allow_network": self.allow_network,
+                "semgrep_configs": self.semgrep_configs,
+                "timeout_seconds": self.scanner_timeout_seconds,
+                "exclude_paths": self.exclude_paths,
+            },
+            "testing": {"command": self.test_command, "timeout_seconds": self.test_timeout_seconds},
+            "history": {"limit": self.history_limit},
+            "warnings": self.warnings,
+        }
+
+
+def _str_list(value: Any, key: str, warnings: list[str], max_items: int = 200) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        warnings.append(f"{key} must be a list of strings; ignored.")
+        return []
+    return [item for item in value if item.strip()][:max_items]
+
+
+def _bounded_int(value: Any, key: str, default: int, low: int, high: int, warnings: list[str]) -> int:
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int) or not low <= value <= high:
+        warnings.append(f"{key} must be an integer between {low} and {high}; using {default}.")
+        return default
+    return value
+
+
+def load_config(project_root: Path) -> ProjectConfig:
+    root = project_root.expanduser().resolve()
+    path = root / CONFIG_RELATIVE_PATH
+    config = ProjectConfig(path=path)
+    if not path.is_file():
+        return config
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"Could not parse {path}: {type(exc).__name__}") from exc
+    config.exists = True
+    warnings = config.warnings
+
+    project = data.get("project", {}) if isinstance(data.get("project"), dict) else {}
+    config.project_name = str(project.get("name", ""))[:200]
+    config.profile = str(project.get("profile", "auto"))[:50]
+
+    policy = data.get("policy", {}) if isinstance(data.get("policy"), dict) else {}
+    mode = policy.get("security_mode", "balanced")
+    if mode in SECURITY_MODES:
+        config.security_mode = mode
+    else:
+        warnings.append(f"Unknown security_mode {mode!r}; using 'balanced'.")
+    if isinstance(policy.get("allow_automatic_low_risk_fixes"), bool):
+        config.allow_automatic_low_risk_fixes = policy["allow_automatic_low_risk_fixes"]
+    for key in MANDATORY_TRUE:
+        if key in policy and policy[key] is not True:
+            warnings.append(
+                f"policy.{key} cannot be disabled: the mandatory global policy requires it. Setting ignored."
+            )
+    fail_on = policy.get("fail_on", "none")
+    if fail_on in FAIL_ON_LEVELS:
+        config.fail_on = fail_on
+    else:
+        warnings.append(f"Unknown policy.fail_on {fail_on!r}; using 'none'.")
+    config.deny_command_patterns = _str_list(policy.get("deny_command_patterns"), "policy.deny_command_patterns", warnings)
+    config.approval_command_patterns = _str_list(
+        policy.get("approval_command_patterns"), "policy.approval_command_patterns", warnings
+    )
+    config.protected_paths = _str_list(policy.get("protected_paths"), "policy.protected_paths", warnings)
+    for key in ("allow_commands", "allowed_commands", "disable_rules", "disabled_rules"):
+        if key in policy:
+            warnings.append(f"policy.{key} is not supported: global rules cannot be disabled by project configuration.")
+
+    scanners = data.get("scanners", {}) if isinstance(data.get("scanners"), dict) else {}
+    if "enabled" in scanners:
+        enabled = _str_list(scanners.get("enabled"), "scanners.enabled", warnings)
+        unknown = [name for name in enabled if name not in KNOWN_SCANNERS]
+        if unknown:
+            warnings.append(f"Unknown scanners ignored: {', '.join(unknown)}")
+        config.enabled_scanners = [name for name in enabled if name in KNOWN_SCANNERS]
+        if "gitleaks" not in config.enabled_scanners:
+            # Secret scanning is a mandatory global control.
+            config.enabled_scanners.insert(0, "gitleaks")
+            warnings.append("gitleaks secret scanning is mandatory and was re-enabled.")
+    if isinstance(scanners.get("allow_network"), bool):
+        config.allow_network = scanners["allow_network"]
+    config.semgrep_configs = _str_list(scanners.get("semgrep_configs"), "scanners.semgrep_configs", warnings, 20)
+    config.scanner_timeout_seconds = _bounded_int(
+        scanners.get("timeout_seconds"), "scanners.timeout_seconds", 600, 10, 7200, warnings
+    )
+    config.exclude_paths = _str_list(scanners.get("exclude_paths"), "scanners.exclude_paths", warnings)
+
+    testing = data.get("testing", {}) if isinstance(data.get("testing"), dict) else {}
+    config.test_command = _str_list(testing.get("command"), "testing.command", warnings, 50)
+    config.test_timeout_seconds = _bounded_int(
+        testing.get("timeout_seconds"), "testing.timeout_seconds", 900, 10, 7200, warnings
+    )
+
+    history = data.get("history", {}) if isinstance(data.get("history"), dict) else {}
+    config.history_limit = _bounded_int(history.get("limit"), "history.limit", 50, 1, 1000, warnings)
+    return config

universal_dev_security/detector.py

@@ -0,0 +1,201 @@
+"""Conservative, local-only project technology detection and scanning profiles."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from universal_dev_security.projectfiles import ProjectInventory, build_inventory
+
+# Lockfiles and manifests that dependency scanners (OSV-Scanner, Trivy) understand.
+DEPENDENCY_FILES = {
+    "requirements.txt", "poetry.lock", "pipfile.lock", "pdm.lock", "uv.lock", "pyproject.toml", "setup.py",
+    "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml", "bun.lock", "package.json",
+    "composer.lock", "composer.json", "gemfile.lock", "cargo.lock", "go.mod", "go.sum",
+    "pom.xml", "gradle.lockfile", "build.gradle", "build.gradle.kts", "packages.lock.json",
+    "packages.config", "pubspec.lock", "mix.lock", "conan.lock",
+}
+DEPENDENCY_SUFFIXES = {".csproj", ".fsproj", ".vbproj"}
+
+CODE_SUFFIXES = {
+    ".py", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".php", ".java", ".kt", ".cs", ".go", ".rb",
+    ".rs", ".scala", ".swift", ".c", ".cc", ".cpp", ".h", ".hpp", ".sh", ".ps1", ".vue", ".svelte",
+}
+
+IAC_NAMES = {"dockerfile", "containerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yml",
+             "compose.yaml", "chart.yaml", "kustomization.yaml"}
+IAC_SUFFIXES = {".tf", ".tfvars", ".bicep", ".hcl"}
+
+# Technology profile -> scanners that are meaningful + optional Semgrep rule packs.
+# Rule pack names refer to the public Semgrep Registry (https://semgrep.dev/explore).
+PROFILES: dict[str, dict[str, Any]] = {
+    "generic":     {"scanners": ["gitleaks"], "semgrep": []},
+    "python":      {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/python"]},
+    "javascript":  {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/javascript"]},
+    "typescript":  {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/typescript"]},
+    "node":        {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/nodejs"]},
+    "react":       {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/react"]},
+    "nextjs":      {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/react"]},
+    "php":         {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/php"]},
+    "wordpress":   {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/php"]},
+    "woocommerce": {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/php"]},
+    "java":        {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/java"]},
+    "dotnet":      {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/csharp"]},
+    "go":          {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/golang"]},
+    "rust":        {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": []},
+    "ruby":        {"scanners": ["gitleaks", "semgrep", "osv-scanner", "trivy"], "semgrep": ["p/ruby"]},
+    "docker":      {"scanners": ["gitleaks", "semgrep", "trivy"], "semgrep": ["p/dockerfile"]},
+    "terraform":   {"scanners": ["gitleaks", "semgrep", "trivy"], "semgrep": ["p/terraform"]},
+    "kubernetes":  {"scanners": ["gitleaks", "semgrep", "trivy"], "semgrep": ["p/kubernetes"]},
+}
+
+
+def _read_json(path: Path, limit: int = 2_000_000) -> dict[str, Any]:
+    try:
+        if path.stat().st_size > limit:
+            return {}
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError, UnicodeDecodeError):
+        return {}
+
+
+def _package_json_dependencies(root: Path, inventory: ProjectInventory) -> set[str]:
+    deps: set[str] = set()
+    for relative in inventory.find("package.json")[:25]:
+        data = _read_json(root / relative)
+        for key in ("dependencies", "devDependencies", "peerDependencies"):
+            section = data.get(key)
+            if isinstance(section, dict):
+                deps.update(str(name).lower() for name in section)
+    return deps
+
+
+def _composer_requirements(root: Path, inventory: ProjectInventory) -> set[str]:
+    deps: set[str] = set()
+    for relative in inventory.find("composer.json")[:25]:
+        data = _read_json(root / relative)
+        for key in ("require", "require-dev"):
+            section = data.get(key)
+            if isinstance(section, dict):
+                deps.update(str(name).lower() for name in section)
+    return deps
+
+
+def detect_technologies(root: Path, inventory: ProjectInventory) -> dict[str, list[str]]:
+    """Return {technology: [evidence, ...]} from file markers and manifests."""
+    found: dict[str, list[str]] = {}
+
+    def add(tech: str, evidence: str) -> None:
+        found.setdefault(tech, [])
+        if evidence not in found[tech] and len(found[tech]) < 5:
+            found[tech].append(evidence)
+
+    for name in ("pyproject.toml", "requirements.txt", "Pipfile", "setup.py", "setup.cfg", "poetry.lock", "uv.lock"):
+        for path in inventory.find(name)[:2]:
+            add("python", path)
+    if inventory.has_suffix(".py") and "python" not in found:
+        add("python", "*.py source files")
+
+    js_deps = _package_json_dependencies(root, inventory)
+    for path in inventory.find("package.json")[:2]:
+        add("node", path)
+        add("javascript", path)
+    if inventory.has_suffix(".js", ".jsx", ".mjs", ".cjs"):
+        add("javascript", "*.js source files")
+    if inventory.find("tsconfig.json") or inventory.has_suffix(".ts", ".tsx") or "typescript" in js_deps:
+        add("typescript", (inventory.find("tsconfig.json") or ["*.ts source files"])[0])
+    if "react" in js_deps or "react-dom" in js_deps:
+        add("react", "package.json dependency: react")
+    if "next" in js_deps or any(inventory.find(n) for n in ("next.config.js", "next.config.mjs", "next.config.ts")):
+        add("nextjs", "package.json dependency: next" if "next" in js_deps else "next.config.*")
+        add("react", "Next.js implies React")
+
+    composer = _composer_requirements(root, inventory)
+    for path in inventory.find("composer.json")[:2]:
+        add("php", path)
+    if inventory.has_suffix(".php"):
+        add("php", "*.php source files")
+    wp_markers = inventory.find("wp-config.php") + inventory.find("wp-config-sample.php") + inventory.find("wp-load.php")
+    if wp_markers or inventory.has_path_part("wp-content") or any("wordpress" in d for d in composer):
+        add("wordpress", (wp_markers or ["wp-content/"])[0])
+        add("php", "WordPress implies PHP")
+    plugin_headers = [p for p in inventory.files if p.lower().endswith("woocommerce.php")]
+    if (inventory.has_path_part("wp-content/plugins/woocommerce") or plugin_headers
+            or any("woocommerce" in d for d in composer)):
+        add("woocommerce", (plugin_headers or ["wp-content/plugins/woocommerce/"])[0])
+
+    for name in ("pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle"):
+        for path in inventory.find(name)[:2]:
+            add("java", path)
+    if inventory.has_suffix(".java"):
+        add("java", "*.java source files")
+
+    for path in [p for p in inventory.files if p.lower().endswith((".sln", ".csproj", ".fsproj", ".vbproj"))][:3]:
+        add("dotnet", path)
+
+    for path in inventory.find("go.mod")[:2]:
+        add("go", path)
+    for path in inventory.find("Cargo.toml")[:2]:
+        add("rust", path)
+    for path in inventory.find("Gemfile")[:2]:
+        add("ruby", path)
+
+    docker = [p for p in inventory.files if p.rsplit("/", 1)[-1].lower() in IAC_NAMES - {"chart.yaml", "kustomization.yaml"}
+              or p.rsplit("/", 1)[-1].lower().startswith("dockerfile")]
+    for path in docker[:3]:
+        add("docker", path)
+    for path in [p for p in inventory.files if p.lower().endswith((".tf", ".tfvars"))][:3]:
+        add("terraform", path)
+    for path in (inventory.find("Chart.yaml") + inventory.find("kustomization.yaml"))[:3]:
+        add("kubernetes", path)
+    return found
+
+
+def has_dependency_manifests(inventory: ProjectInventory) -> bool:
+    return any(name.lower() in DEPENDENCY_FILES for name in inventory.names) or inventory.has_suffix(*DEPENDENCY_SUFFIXES)
+
+
+def has_source_code(inventory: ProjectInventory) -> bool:
+    return inventory.has_suffix(*CODE_SUFFIXES)
+
+
+def has_iac(inventory: ProjectInventory) -> bool:
+    names = {n.lower() for n in inventory.names}
+    return bool(names & IAC_NAMES) or any(n.startswith("dockerfile") for n in names) or inventory.has_suffix(*IAC_SUFFIXES)
+
+
+def recommended_semgrep_configs(technologies: list[str]) -> list[str]:
+    configs = ["p/default"]
+    for tech in technologies:
+        for config in PROFILES.get(tech, {}).get("semgrep", []):
+            if config not in configs:
+                configs.append(config)
+    return configs
+
+
+def detect_project(path: Path, inventory: ProjectInventory | None = None) -> dict[str, Any]:
+    target = path.expanduser().resolve()
+    if not target.exists() or not target.is_dir():
+        raise ValueError(f"Project path is not an existing directory: {target}")
+    inventory = inventory or build_inventory(target)
+    technologies = detect_technologies(target, inventory)
+    detected = sorted(technologies) or ["generic"]
+    scanners: list[str] = []
+    for tech in detected:
+        for scanner in PROFILES.get(tech, PROFILES["generic"])["scanners"]:
+            if scanner not in scanners:
+                scanners.append(scanner)
+    return {
+        "path": str(target),
+        "detected": detected,
+        "evidence": technologies,
+        "recommended_scanners": scanners,
+        "semgrep_configs": recommended_semgrep_configs(detected) if "semgrep" in scanners else [],
+        "dependency_manifests": has_dependency_manifests(inventory),
+        "infrastructure_as_code": has_iac(inventory),
+        "files_inventoried": len(inventory.files),
+        "inventory_truncated": inventory.truncated,
+        "detector": "marker-based",
+        "network_used": False,
+    }

universal_dev_security/engine.py

@@ -0,0 +1,203 @@
+"""Scan orchestration: run applicable scanners and aggregate honest results."""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from universal_dev_security import __version__
+from universal_dev_security.config import FAIL_ON_LEVELS, ProjectConfig
+from universal_dev_security.detector import detect_project
+import hashlib
+import json
+import shutil
+import subprocess
+
+from universal_dev_security.findings import Category, Finding, ScanResult, ScanStatus, Severity, severity_counts
+from universal_dev_security.projectfiles import build_inventory
+from universal_dev_security.scanners import get_scanner
+from universal_dev_security.scanners.base import ScannerExecutionError, ScanOptions, run_tool
+
+SCHEMA_VERSION = "2.0"
+
+
+def overall_status(results: list[ScanResult]) -> str:
+    """Aggregate scanner states without overstating coverage.
+
+    * ``not_scanned`` - no scanner executed.
+    * ``findings``    - at least one executed scanner returned findings.
+    * ``error``       - no findings, but at least one scanner failed.
+    * ``incomplete``  - no findings or errors, but an applicable scanner did not run.
+    * ``clean``       - every applicable scanner executed and returned nothing.
+    """
+    executed = [r for r in results if r.status.executed]
+    if not executed:
+        return "not_scanned"
+    if any(r.status is ScanStatus.FINDINGS for r in results):
+        return "findings"
+    if any(r.status is ScanStatus.ERROR for r in results):
+        return "error"
+    if any(r.status in (ScanStatus.NOT_INSTALLED, ScanStatus.SKIPPED) for r in results):
+        return "incomplete"
+    return "clean"
+
+
+def scope_fingerprint(extra_excludes: list[str]) -> str:
+    """Identify the scan scope (built-in and configured exclusions).
+
+    When it differs between two scans, findings that disappeared may have been
+    excluded rather than fixed, and comparisons must say so.
+    """
+    from universal_dev_security.projectfiles import DEFAULT_EXCLUDED_DIRS
+    from universal_dev_security.scanners.gitleaks import SECRET_SCAN_EXCLUDES
+
+    basis = json.dumps([sorted(DEFAULT_EXCLUDED_DIRS), list(SECRET_SCAN_EXCLUDES), sorted(extra_excludes)])
+    return hashlib.sha256(basis.encode("utf-8")).hexdigest()[:16]
+
+
+def git_tracked_files(root: Path) -> set[str] | None:
+    """Project-relative paths tracked by Git, or None when ``root`` is not inside a Git work tree."""
+    git = shutil.which("git")
+    if not git:
+        return None
+    try:
+        completed = run_tool([git, "ls-files", "-z"], cwd=root, timeout=120)
+    except (OSError, subprocess.SubprocessError, ScannerExecutionError):
+        return None
+    if completed.returncode != 0:
+        return None
+    return {path.replace("\\", "/") for path in completed.stdout.split("\0") if path}
+
+
+def annotate_git_exposure(root: Path, findings: list[Finding]) -> None:
+    """Mark secret findings as committed (tracked by Git) or local-only.
+
+    A secret in a tracked file has been (or will be) shared through the
+    repository and must be rotated; one in an untracked or ignored local file
+    has not left the machine through Git.
+    """
+    secrets = [f for f in findings if f.category is Category.SECRET]
+    if not secrets:
+        return
+    tracked = git_tracked_files(root)
+    for finding in secrets:
+        if finding.commit:
+            finding.tracked_in_git = True  # found in Git history
+        elif tracked is not None:
+            finding.tracked_in_git = finding.file in tracked
+
+
+def finding_sort_key(finding: Finding) -> tuple[int, int, str, str, int]:
+    """Committed secrets first, then by severity (critical → unclassified), tool, file, line."""
+    exposed = 0 if (finding.category is Category.SECRET and finding.tracked_in_git) else 1
+    return (exposed, -finding.severity.rank, finding.tool, finding.file, finding.start_line or 0)
+
+
+def threshold_reached(findings: list[Finding], fail_on: str) -> bool:
+    if fail_on not in FAIL_ON_LEVELS or fail_on == "none":
+        return False
+    if fail_on == "unclassified":
+        return bool(findings)
+    threshold = Severity(fail_on).rank
+    # Unclassified secrets are always treated as blocking once a threshold is set:
+    # an exposed credential is never "low risk" just because it lacks a label.
+    return any(f.severity.rank >= threshold or (f.category.value == "secret") for f in findings)
+
+
+def run_scan(
+    target: Path,
+    config: ProjectConfig | None = None,
+    *,
+    tools: list[str] | None = None,
+    allow_network: bool | None = None,
+    progress: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    root = target.expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError(f"Scan target is not an existing directory: {root}")
+    config = config or ProjectConfig()
+    started = datetime.now(timezone.utc)
+    inventory = build_inventory(root, extra_excludes=config.exclude_paths)
+    project = detect_project(root, inventory)
+    options = ScanOptions(
+        timeout_seconds=config.scanner_timeout_seconds,
+        allow_network=config.allow_network if allow_network is None else allow_network,
+        semgrep_configs=config.semgrep_configs,
+        exclude_paths=config.exclude_paths,
+        technologies=project["detected"],
+    )
+    requested = tools or config.enabled_scanners
+    results: list[ScanResult] = []
+    for name in requested:
+        adapter = get_scanner(name)
+        if progress:
+            progress(f"Running {adapter.display_name}...")
+        results.append(adapter.scan(root, inventory, options))
+
+    findings = [finding for result in results for finding in result.findings]
+    annotate_git_exposure(root, findings)
+    findings.sort(key=finding_sort_key)
+    status = overall_status(results)
+    counts = severity_counts(findings)
+    privacy = []
+    for name in requested:
+        adapter = get_scanner(name)
+        privacy.append({
+            "tool": name,
+            "transmits_project_metadata": adapter.transmits_project_metadata,
+            "downloads_data": adapter.downloads_data,
+            "note": adapter.network_note,
+        })
+    return {
+        "schema_version": SCHEMA_VERSION,
+        # Microseconds keep ids strictly ordered even for scans started within the same second.
+        "scan_id": started.strftime("%Y%m%dT%H%M%S%fZ") + "-" + uuid.uuid4().hex[:6],
+        "uds_version": __version__,
+        "started_at": started.isoformat(),
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+        "target": str(root),
+        "project": {
+            "detected": project["detected"],
+            "files_inventoried": project["files_inventoried"],
+            "inventory_truncated": project["inventory_truncated"],
+        },
+        "options": {"tools": requested, "allow_network": options.allow_network, "fail_on": config.fail_on,
+                    "scope_fingerprint": scope_fingerprint(config.exclude_paths)},
+        "overall_status": status,
+        "scanners": [{k: v for k, v in r.to_dict().items() if k != "findings"} for r in results],
+        "summary": {
+            "finding_count": len(findings),
+            "by_severity": counts,
+            "by_tool": {r.tool: r.finding_count for r in results},
+            "by_category": {c: sum(1 for f in findings if f.category.value == c)
+                            for c in ("secret", "code", "dependency", "configuration")},
+            "security_score": None,
+            "score_note": "Not calculated: UDS does not publish a numeric score without a validated, documented methodology.",
+        },
+        "coverage": {
+            "executed": [r.tool for r in results if r.status.executed],
+            "not_executed": [{"tool": r.tool, "status": r.status.value, "reason": r.reason} for r in results
+                             if not r.status.executed],
+        },
+        "privacy": privacy,
+        "findings": [f.to_dict() for f in findings],
+        "limitations": [
+            "This report covers only the scanners listed as executed.",
+            "A clean result is not proof that the project is secure.",
+            "Severity is shown only when supplied by the scanner or derived from a published scale (CVSS); "
+            "other findings are unclassified.",
+            "Secret values, matched text and raw scanner output are intentionally excluded.",
+        ],
+    }
+
+
+def exit_code_for(scan: dict[str, Any], fail_on: str = "none", require_complete: bool = False) -> int:
+    """0 = success, 1 = findings at/above threshold, 2 = scan error / nothing scanned / incomplete (if required)."""
+    status = scan["overall_status"]
+    if status in ("not_scanned", "error") or any(s["status"] == "error" for s in scan["scanners"]):
+        return 2
+    if require_complete and status == "incomplete":
+        return 2
+    findings = [Finding.from_dict(f) for f in scan["findings"]]
+    return 1 if threshold_reached(findings, fail_on) else 0