agenteval-toolkit 0.1.0__py3-none-any.whl

agenteval/collectors/normalize.py

@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Normalize a snapshot of raw Kubernetes objects into assets and facts (pure functions, easy to test offline).
+
+Snapshot format (same as the items field of `kubectl get -o json`, camelCase):
+{
+  "cluster": {"name": "prod-gpu-1"},
+  "workloads": [Deployment/StatefulSet ...],
+  "services": [...], "ingresses": [...], "network_policies": [...]
+}
+
+Security note: this module records only the *names* of sensitive environment variables and never writes their values to facts or reports.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+from agenteval.models import Asset
+
+# Label/annotation prefix for AgentEval hints, e.g. agenteval.io/auth: oidc.
+# Override with AGENTEVAL_ANNOTATION_PREFIX (a trailing "/" is added if missing).
+ANN = os.environ.get("AGENTEVAL_ANNOTATION_PREFIX", "agenteval.io/").rstrip("/") + "/"
+
+SERVER_PATTERNS: dict[str, str] = {
+    "vllm": r"vllm",
+    "tgi": r"text-generation-inference",
+    "triton": r"tritonserver",
+    "ollama": r"ollama",
+    "llamacpp": r"llama[.\-_]?cpp",
+    "sglang": r"sglang",
+    "ray-serve": r"rayproject/ray",
+    "kserve": r"kserve",
+}
+GENERATIVE_SERVERS = {"vllm", "tgi", "ollama", "llamacpp", "sglang"}
+AUTH_SIDECAR = re.compile(r"oauth2-proxy|envoy|kong|authz|istio/proxy", re.I)
+GUARD_SIDECAR = re.compile(r"guard|guardrails|nemo-guardrails", re.I)
+SECRET_NAME = re.compile(r"(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)", re.I)
+
+
+# ---------------- Helpers ----------------
+
+def _meta(obj: dict) -> dict:
+    return obj.get("metadata") or {}
+
+
+def _labels_match(selector: dict | None, labels: dict, empty_matches_all: bool) -> bool:
+    """Label subset matching.
+
+    - Service.spec.selector is a flat dict; empty/missing selects no Pods;
+    - NetworkPolicy.spec.podSelector is a LabelSelector; {} selects all Pods;
+    - selectors with matchExpressions are treated as non-matching for now (conservative; full support in Phase 2).
+    """
+    if not selector:
+        return empty_matches_all and selector is not None
+    if selector.get("matchExpressions"):
+        return False
+    match = (selector.get("matchLabels") or {}) if "matchLabels" in selector else selector
+    if not match:
+        return empty_matches_all
+    return all(labels.get(k) == v for k, v in match.items())
+
+
+def _image_tag(ref: str) -> str | None:
+    if "@" in ref:
+        return None
+    last = ref.rsplit("/", 1)[-1]
+    return last.split(":", 1)[1] if ":" in last else None
+
+
+def detect_server(images: list[str]) -> str | None:
+    for img in images:
+        for server, pat in SERVER_PATTERNS.items():
+            if re.search(pat, img, re.I):
+                return server
+    return None
+
+
+def _model_from_args(container: dict) -> str | None:
+    args = (container.get("command") or []) + (container.get("args") or [])
+    for i, a in enumerate(args):
+        if a in ("--model", "--model-id", "--model_name") and i + 1 < len(args):
+            return args[i + 1]
+        if a.startswith("--model=") or a.startswith("--model-id="):
+            return a.split("=", 1)[1]
+        if a == "serve" and i + 1 < len(args) and not args[i + 1].startswith("-"):
+            return args[i + 1]
+    for e in container.get("env") or []:
+        if e.get("name") in ("MODEL_ID", "MODEL_NAME", "MODEL") and e.get("value"):
+            return e["value"]
+    return None
+
+
+# ---------------- Main logic ----------------
+
+def _workload_to_asset(wl: dict, services: list[dict], ingresses: list[dict],
+                       netpols: list[dict]) -> Asset | None:
+    meta = _meta(wl)
+    ns = meta.get("namespace", "default")
+    name = meta.get("name", "unknown")
+    tpl = (wl.get("spec") or {}).get("template") or {}
+    tpl_meta = _meta(tpl)
+    pod_spec = tpl.get("spec") or {}
+    containers = pod_spec.get("containers") or []
+    pod_labels = tpl_meta.get("labels") or {}
+    labels = {**(meta.get("labels") or {}), **pod_labels}
+    ann = {**(meta.get("annotations") or {}), **(tpl_meta.get("annotations") or {})}
+
+    images = [c.get("image", "") for c in containers + (pod_spec.get("initContainers") or [])]
+    server = detect_server(images)
+    if not server and labels.get(ANN + "inference") != "true":
+        return None  # not an inference workload
+
+    # --- Authentication ---
+    auth_method = ann.get(ANN + "auth")
+    auth_enabled = bool(auth_method and auth_method.lower() != "none")
+    if not auth_method:
+        for c in containers:
+            args = (c.get("command") or []) + (c.get("args") or [])
+            env_names = {e.get("name") for e in c.get("env") or []}
+            if any(a == "--api-key" or a.startswith("--api-key=") for a in args) or \
+                    env_names & {"VLLM_API_KEY", "API_KEY"}:
+                auth_enabled, auth_method = True, "api-key"
+            elif AUTH_SIDECAR.search(c.get("image", "")):
+                auth_enabled, auth_method = True, "proxy-sidecar"
+
+    # --- Exposure and TLS ---
+    svcs = [s for s in services if _meta(s).get("namespace") == ns
+            and _labels_match((s.get("spec") or {}).get("selector"), pod_labels, empty_matches_all=False)]
+    svc_names = {_meta(s).get("name") for s in svcs}
+    svc_types = sorted({(s.get("spec") or {}).get("type", "ClusterIP") for s in svcs})
+    ings = []
+    for ing in ingresses:
+        if _meta(ing).get("namespace") != ns:
+            continue
+        backends = set()
+        for rule in (ing.get("spec") or {}).get("rules") or []:
+            for p in ((rule.get("http") or {}).get("paths")) or []:
+                backends.add((((p.get("backend") or {}).get("service")) or {}).get("name"))
+        if backends & svc_names:
+            ings.append(ing)
+    public = bool(ings) or any(t in ("LoadBalancer", "NodePort") for t in svc_types)
+    hosts = sorted({r.get("host") for i in ings for r in (i.get("spec") or {}).get("rules") or [] if r.get("host")})
+    if ings:
+        tls_enabled = all((i.get("spec") or {}).get("tls") for i in ings)
+    else:
+        tls_enabled = ann.get(ANN + "tls") == "true"
+
+    # --- NetworkPolicy ---
+    np_present = any(
+        _meta(np).get("namespace") == ns and _labels_match((np.get("spec") or {}).get("podSelector", {}), pod_labels, empty_matches_all=True)
+        for np in netpols
+    )
+
+    # --- Images ---
+    main_images = [c.get("image", "") for c in containers]
+    digest_pinned = all("@sha256:" in i for i in main_images) if main_images else False
+    any_latest = any(_image_tag(i) in (None, "latest") and "@sha256:" not in i for i in main_images)
+
+    # --- SecurityContext ---
+    pod_sc = pod_spec.get("securityContext") or {}
+    def _non_root(c):
+        sc = c.get("securityContext") or {}
+        if sc.get("runAsNonRoot") is True or pod_sc.get("runAsNonRoot") is True:
+            return True
+        uid = sc.get("runAsUser", pod_sc.get("runAsUser"))
+        return isinstance(uid, int) and uid > 0
+    run_as_non_root = all(_non_root(c) for c in containers) if containers else False
+    privileged = any((c.get("securityContext") or {}).get("privileged") is True for c in containers)
+    # Kubernetes allows privilege escalation by default; it must be explicitly set to false
+    allow_pe = any((c.get("securityContext") or {}).get("allowPrivilegeEscalation") is not False for c in containers)
+
+    # --- Plaintext secrets (names only) ---
+    plaintext = sorted({
+        f"{c.get('name')}:{e.get('name')}"
+        for c in containers for e in c.get("env") or []
+        if e.get("value") and SECRET_NAME.search(e.get("name", ""))
+    })
+
+    # --- Resource limits ---
+    limits_set = all(((c.get("resources") or {}).get("limits") or {}).get("memory") for c in containers) \
+        if containers else False
+
+    # --- Content safety ---
+    cs = ann.get(ANN + "content-safety")
+    cs_enabled = bool(cs and cs.lower() != "none")
+    if not cs:
+        cs_enabled = any(GUARD_SIDECAR.search(i) for i in main_images[1:])
+        cs = "sidecar" if cs_enabled else None
+
+    model_name = ann.get(ANN + "model") or next((m for c in containers if (m := _model_from_args(c))), None)
+
+    facts: dict[str, Any] = {
+        "kind": wl.get("kind", "Deployment"),
+        "server": server or "custom",
+        "replicas": (wl.get("spec") or {}).get("replicas"),
+        "owner": labels.get(ANN + "owner") or labels.get("owner") or labels.get("team"),
+        "risk_tier": ann.get(ANN + "risk-tier", "standard"),
+        "customer_facing": ann.get(ANN + "customer-facing") == "true",
+        "ai_disclosure": {"enabled": ann.get(ANN + "ai-disclosure") == "true"},
+        "model": {
+            "name": model_name,
+            "source": ann.get(ANN + "model-source"),
+            "card_url": ann.get(ANN + "model-card"),
+            "provenance_verified": ann.get(ANN + "provenance-verified") == "true",
+            "generative": (server in GENERATIVE_SERVERS) or ann.get(ANN + "generative") == "true",
+            "fine_tuned": ann.get(ANN + "fine-tuned") == "true",
+        },
+        "auth": {"enabled": auth_enabled, "method": auth_method},
+        "exposure": {"public": public, "service_types": svc_types, "ingress_hosts": hosts},
+        "tls": {"enabled": tls_enabled},
+        "network_policy": {"present": np_present},
+        "image": {"refs": main_images, "all_digest_pinned": digest_pinned, "any_latest": any_latest},
+        "security_context": {
+            "run_as_non_root": run_as_non_root,
+            "privileged": privileged,
+            "allow_privilege_escalation": allow_pe,
+        },
+        "secrets": {"plaintext_env": plaintext},
+        "resources": {"limits_set": limits_set},
+        "logging": {"request_logging": ann.get(ANN + "request-logging") == "true",
+                    "pii_redaction": ann.get(ANN + "log-redaction") == "true"},
+        "monitoring": {"enabled": ann.get("prometheus.io/scrape") == "true" or ann.get(ANN + "monitoring") == "true"},
+        "content_safety": {"enabled": cs_enabled, "method": cs},
+    }
+    kind = facts["kind"].lower()
+    return Asset(id=f"{kind}/{ns}/{name}", type="inference_service", name=name, namespace=ns, facts=facts)
+
+
+def normalize_snapshot(snapshot: dict) -> list[Asset]:
+    services = snapshot.get("services") or []
+    ingresses = snapshot.get("ingresses") or []
+    netpols = snapshot.get("network_policies") or []
+    assets = [a for wl in snapshot.get("workloads") or []
+              if (a := _workload_to_asset(wl, services, ingresses, netpols)) is not None]
+
+    cluster_name = (snapshot.get("cluster") or {}).get("name", "cluster")
+    cluster = Asset(
+        id=f"cluster/{cluster_name}", type="cluster", name=cluster_name,
+        facts={
+            "inference_service_count": len(assets),
+            "namespaces": sorted({a.namespace for a in assets if a.namespace}),
+        },
+    )
+    return [cluster, *assets]

agenteval/config.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Runtime configuration and shared loaders."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+from agenteval.schema import check
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+# Starter content (rules, exams, certification, examples) copied into the wheel at build time.
+STARTER_ROOT = Path(__file__).resolve().parent / "_starter"
+STARTER_DIRS = ("rules", "exams", "certification", "examples")
+
+
+def content_dir(name: str, env_var: str) -> Path:
+    """Resolve a content directory: $ENV, then ./<name>, then a source checkout, then the bundled starter copy."""
+    env = os.environ.get(env_var)
+    if env:
+        return Path(env)
+    for candidate in (Path.cwd() / name, REPO_ROOT / name, STARTER_ROOT / name):
+        if candidate.exists():
+            return candidate
+    return Path.cwd() / name
+
+
+def starter_root() -> Path:
+    """Directory holding the bundled starter content (the wheel copy, or the source checkout)."""
+    return STARTER_ROOT if STARTER_ROOT.exists() else REPO_ROOT
+
+
+def default_rules_dir() -> Path:
+    return content_dir("rules", "AGENTEVAL_RULES_DIR")
+
+
+def load_attestations(path: str | Path | list | None) -> list[dict]:
+    """Read one or more attestation files and merge them."""
+    if not path:
+        return []
+    if isinstance(path, (list, tuple)):
+        return [a for p in path for a in load_attestations(p)]
+    with Path(path).open(encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+    check("attestations", data, str(path))
+    return data.get("attestations", []) if isinstance(data, dict) else data

agenteval/engine/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+
+from .conditions import evaluate, resolve, MISSING, ConditionError
+from .loader import load_packs, load_rules, RuleLoadError, rules_version
+from .evaluator import run_scan, evaluate_rule
+
+__all__ = [
+    "evaluate", "resolve", "MISSING", "ConditionError",
+    "load_packs", "load_rules", "RuleLoadError", "rules_version",
+    "run_scan", "evaluate_rule",
+]

agenteval/engine/conditions.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Safe condition expression evaluator (does not use eval).
+
+Syntax:
+  {"all": [cond, ...]}   all must hold
+  {"any": [cond, ...]}   any must hold
+  {"not": cond}          negation
+  {"field": "a.b.c", "op": "eq", "value": ...}   leaf condition
+
+Missing fields resolve to MISSING. Except for exists/not_exists/falsy/empty, every leaf condition returns False
+for MISSING, i.e. "no evidence means no pass" (fail-closed).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+class _Missing:
+    def __repr__(self) -> str:  # pragma: no cover
+        return "<missing>"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+MISSING = _Missing()
+
+
+class ConditionError(ValueError):
+    pass
+
+
+def resolve(facts: dict[str, Any], path: str) -> Any:
+    cur: Any = facts
+    for part in path.split("."):
+        if isinstance(cur, dict) and part in cur:
+            cur = cur[part]
+        else:
+            return MISSING
+    return cur
+
+
+def _cmp(a: Any, b: Any, fn) -> bool:
+    try:
+        return bool(fn(a, b))
+    except TypeError:
+        return False
+
+
+def _leaf(actual: Any, op: str, expected: Any) -> bool:
+    if op == "exists":
+        return actual is not MISSING and actual is not None
+    if op == "not_exists":
+        return actual is MISSING or actual is None
+    if op == "falsy":
+        return not actual
+    if op == "empty":
+        return actual is MISSING or actual is None or (hasattr(actual, "__len__") and len(actual) == 0)
+    if actual is MISSING:
+        return False
+    if op == "truthy":
+        return bool(actual)
+    if op == "not_empty":
+        return actual is not None and hasattr(actual, "__len__") and len(actual) > 0
+    if op == "eq":
+        return actual == expected
+    if op == "ne":
+        return actual != expected
+    if op == "in":
+        return isinstance(expected, list) and actual in expected
+    if op == "not_in":
+        return isinstance(expected, list) and actual not in expected
+    if op == "contains":
+        return isinstance(actual, (list, str, dict)) and expected in actual
+    if op == "not_contains":
+        return isinstance(actual, (list, str, dict)) and expected not in actual
+    if op == "regex":
+        return isinstance(actual, str) and re.search(str(expected), actual) is not None
+    if op == "gt":
+        return _cmp(actual, expected, lambda a, b: a > b)
+    if op == "gte":
+        return _cmp(actual, expected, lambda a, b: a >= b)
+    if op == "lt":
+        return _cmp(actual, expected, lambda a, b: a < b)
+    if op == "lte":
+        return _cmp(actual, expected, lambda a, b: a <= b)
+    raise ConditionError(f"Unknown operator: {op}")
+
+
+def evaluate(cond: dict[str, Any], facts: dict[str, Any], evidence: dict[str, Any] | None = None) -> bool:
+    """Evaluate a condition; if evidence is given, record the fields consulted and their actual values."""
+    if "all" in cond:
+        # No short-circuiting, so that complete evidence is collected
+        results = [evaluate(c, facts, evidence) for c in cond["all"]]
+        return all(results)
+    if "any" in cond:
+        results = [evaluate(c, facts, evidence) for c in cond["any"]]
+        return any(results)
+    if "not" in cond:
+        return not evaluate(cond["not"], facts, evidence)
+    if "field" in cond and "op" in cond:
+        actual = resolve(facts, cond["field"])
+        if evidence is not None:
+            evidence[cond["field"]] = None if actual is MISSING else actual
+        return _leaf(actual, cond["op"], cond.get("value"))
+    raise ConditionError(f"Invalid condition: {cond!r}")

agenteval/engine/evaluator.py

@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Rule evaluation: assets × rules → findings."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import date, datetime, timezone
+from typing import Any
+
+from agenteval.models import (
+    Asset, Finding, Rule, RuleType, ScanResult, ScanSummary, Status,
+)
+
+from agenteval.i18n import DEFAULT_LANG, format_message
+
+from .conditions import ConditionError, evaluate
+from .loader import rules_version
+
+
+def _match_attestation(rule: Rule, asset: Asset, attestations: list[dict[str, Any]]) -> dict | None:
+    """Merge all attestations for this rule that apply to the asset (wildcard "*" and asset-level); asset-level evidence wins.
+
+    When several attestations are merged, the earliest attested_at is kept (a conservative validity check), so
+    manual material and evaluation-generated attestations (e.g. agenteval eval --attest-asset) can live in separate files.
+    """
+    matched = [a for a in attestations if a.get("rule_id") == rule.id
+               and a.get("asset_id", "*") in ("*", asset.id)]
+    if not matched:
+        return None
+    matched.sort(key=lambda a: a.get("asset_id", "*") != "*")  # wildcard first, asset-level overrides
+    evidence: dict[str, Any] = {}
+    dates, people = [], []
+    for a in matched:
+        evidence.update({k: v for k, v in (a.get("evidence") or {}).items() if v})
+        if a.get("attested_at"):
+            d = a["attested_at"]
+            dates.append(date.fromisoformat(d) if isinstance(d, str) else (d.date() if isinstance(d, datetime) else d))
+        if a.get("attested_by"):
+            people.append(str(a["attested_by"]))
+    return {"evidence": evidence, "attested_at": min(dates) if dates else None,
+            "attested_by": ", ".join(dict.fromkeys(people)) or None}
+
+
+def _evaluate_attestation(rule: Rule, asset: Asset, attestations, today: date) -> tuple[Status, str, dict, dict]:
+    """Return (status, message code, message params, evidence)."""
+    spec = rule.attestation or {}
+    required = spec.get("evidence_required", [])
+    att = _match_attestation(rule, asset, attestations)
+    if att is None:
+        return Status.manual, "att_missing", {"required": required}, {"required": required}
+
+    evidence = att.get("evidence") or {}
+    missing = [k for k in required if not evidence.get(k)]
+    ev = {"attested_by": att.get("attested_by"), "attested_at": str(att.get("attested_at")),
+          "provided": sorted(evidence.keys())}
+    if missing:
+        return Status.failed, "att_incomplete", {"missing": missing}, {**ev, "missing": missing}
+
+    max_age = spec.get("max_age_days")
+    attested_at = att.get("attested_at")
+    if max_age and attested_at:
+        if isinstance(attested_at, str):
+            attested_at = date.fromisoformat(attested_at)
+        if isinstance(attested_at, datetime):
+            attested_at = attested_at.date()
+        age = (today - attested_at).days
+        ev["age_days"] = age
+        if age > max_age:
+            return Status.failed, "att_expired", {"age": age, "max_age": max_age}, ev
+    elif max_age and not attested_at:
+        return Status.failed, "att_no_date", {}, ev
+
+    return Status.passed, "att_ok", {}, ev
+
+
+def evaluate_rule(rule: Rule, asset: Asset, attestations: list[dict] | None = None,
+                  today: date | None = None) -> Finding | None:
+    """Return None if the rule does not target this asset type."""
+    if asset.type not in rule.applies_to.asset_types:
+        return None
+    today = today or datetime.now(timezone.utc).date()
+    evidence: dict[str, Any] = {}
+    params: dict[str, Any] = {}
+
+    try:
+        if rule.applies_to.when is not None and not evaluate(rule.applies_to.when, asset.facts):
+            status, code = Status.not_applicable, "not_applicable"
+        elif rule.type == RuleType.attestation:
+            status, code, params, evidence = _evaluate_attestation(rule, asset, attestations or [], today)
+        else:
+            ok = evaluate(rule.check or {}, asset.facts, evidence)
+            status = Status.passed if ok else Status.failed
+            code = "ok" if ok else "check_failed"
+    except ConditionError as e:
+        status, code, params = Status.error, "eval_error", {"error": str(e)}
+
+    return Finding(
+        rule_id=rule.id, pack=rule.pack, rule_title=rule.title, severity=rule.severity, category=rule.category,
+        asset_id=asset.id, asset_name=asset.name, asset_type=asset.type,
+        status=status, message=format_message(code, params, DEFAULT_LANG, rule.title),
+        message_code=code, message_params=params, evidence=evidence,
+        remediation=rule.remediation, sources=rule.sources, translations=rule.translations,
+    )
+
+
+def summarize(findings: list[Finding]) -> ScanSummary:
+    s = ScanSummary(total=len(findings))
+    for f in findings:
+        s.by_status[f.status.value] = s.by_status.get(f.status.value, 0) + 1
+        if f.status == Status.failed:
+            s.failed_by_severity[f.severity.value] = s.failed_by_severity.get(f.severity.value, 0) + 1
+    passed = s.by_status.get("pass", 0)
+    failed = s.by_status.get("fail", 0)
+    s.score = round(100.0 * passed / (passed + failed), 1) if (passed + failed) else 100.0
+    return s
+
+
+def run_scan(rules: list[Rule], assets: list[Asset], source: str,
+             attestations: list[dict] | None = None, today: date | None = None) -> ScanResult:
+    started = datetime.now(timezone.utc)
+    findings: list[Finding] = []
+    for asset in assets:
+        for rule in rules:
+            f = evaluate_rule(rule, asset, attestations, today)
+            if f is not None:
+                findings.append(f)
+    findings.sort(key=lambda f: (f.status != Status.failed, -f.severity.rank, f.rule_id, f.asset_id))
+    return ScanResult(
+        scan_id=uuid.uuid4().hex[:12], source=source, started_at=started,
+        finished_at=datetime.now(timezone.utc), rules_version=rules_version(rules),
+        asset_count=len(assets), findings=findings, summary=summarize(findings),
+    )

agenteval/engine/loader.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Rule loading and validation: YAML → JSON Schema validation → Pydantic models."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import yaml
+
+from agenteval.models import Rule, RulePack
+from agenteval.schema import errors as schema_errors
+
+
+class RuleLoadError(Exception):
+    def __init__(self, errors: list[str]):
+        self.errors = errors
+        super().__init__("Failed to load rules:\n  " + "\n  ".join(errors))
+
+
+def _iter_rule_docs(path: Path):
+    files = sorted(path.rglob("*.y*ml")) if path.is_dir() else [path]
+    for f in files:
+        if f.suffix not in (".yaml", ".yml") or "i18n" in f.parts or f.name == "pack.yaml":
+            continue
+        with f.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+        if data is None:
+            continue
+        # A file may hold a single rule or {"rules": [...]}
+        docs = data.get("rules", [data]) if isinstance(data, dict) else data
+        for i, doc in enumerate(docs):
+            yield f, i, doc
+
+
+def load_rules(path: str | Path, include_disabled: bool = False) -> list[Rule]:
+    path = Path(path)
+    if not path.exists():
+        raise RuleLoadError([f"Rule path does not exist: {path}"])
+
+    errors: list[str] = []
+    rules: list[Rule] = []
+    seen: dict[str, str] = {}
+
+    for f, i, doc in _iter_rule_docs(path):
+        loc = f"{f.name}[{i}]"
+        errs = schema_errors("rule", doc, loc)
+        if errs:
+            errors.extend(errs)
+            continue
+        rule = Rule.model_validate(doc)
+        rule.pack = _pack_for(path, f)
+        if rule.id in seen:
+            errors.append(f"{loc}: duplicate rule ID {rule.id} (first seen in {seen[rule.id]})")
+            continue
+        seen[rule.id] = loc
+        if rule.enabled or include_disabled:
+            rules.append(rule)
+
+    if not errors:
+        errors.extend(_attach_translations(path, rules))
+    if errors:
+        raise RuleLoadError(errors)
+    return sorted(rules, key=lambda r: r.id)
+
+
+def _pack_for(root: Path, f: Path) -> str:
+    """Rule pack a rule belongs to: the nearest pack.yaml found walking up from the file's directory."""
+    if not root.is_dir():
+        return ""
+    d = f.parent
+    while True:
+        meta = d / "pack.yaml"
+        if meta.exists():
+            with meta.open(encoding="utf-8") as fh:
+                return str((yaml.safe_load(fh) or {}).get("id", d.name))
+        if d == root or root not in d.parents:
+            return "default"
+        d = d.parent
+
+
+def load_packs(path: str | Path) -> dict[str, RulePack]:
+    path = Path(path)
+    packs: dict[str, RulePack] = {}
+    if path.is_dir():
+        for meta in sorted(path.rglob("pack.yaml")):
+            with meta.open(encoding="utf-8") as fh:
+                data = yaml.safe_load(fh) or {}
+            errs = schema_errors("pack", data, str(meta))
+            if errs:
+                raise RuleLoadError(errs)
+            p = RulePack.model_validate(data)
+            if p.id in packs:
+                raise RuleLoadError([f"{meta}: duplicate pack id {p.id}"])
+            packs[p.id] = p
+    return packs
+
+
+def _attach_translations(path: Path, rules: list[Rule]) -> list[str]:
+    """Read <rules_dir>/**/i18n/<lang>.yaml and attach translations by rule ID."""
+    errors: list[str] = []
+    if not path.is_dir():
+        return errors
+    by_id = {r.id: r for r in rules}
+    for f in sorted(path.rglob("i18n/*.y*ml")):
+        lang = f.stem
+        with f.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+        errs = schema_errors("translations", data, f.name)
+        if errs:
+            errors.extend(errs)
+            continue
+        for rid, tr in data.items():
+            rule = by_id.get(rid)
+            if rule is None:
+                continue  # Ignore rules that are disabled or belong to another pack
+            refs = tr.get("sources") or []
+            if len(refs) > len(rule.sources):
+                errors.append(f"{f.name}: {rid} has more translated sources than the original rule")
+                continue
+            rule.translations[lang] = tr
+    return errors
+
+
+def rules_version(rules: list[Rule]) -> str:
+    """Rule set fingerprint, used in reports to trace which rule version a scan used."""
+    h = hashlib.sha256()
+    for r in sorted(rules, key=lambda r: r.id):
+        h.update(f"{r.id}@{r.version}".encode())
+    return h.hexdigest()[:12]