sourcecode 2.0.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

sourcecode/security_posture.py

@@ -0,0 +1,608 @@
+"""security_posture.py — Knowledge-Layer security-posture inference (P1-A).
+
+Infers **custom endpoint security models without prior knowledge of the
+framework**. Detection emerges from semantic evidence — coverage, specificity,
+correlation, request-interception topology — never from proprietary annotation
+names. This is the Knowledge Layer of the frozen Semantic IR → ContextGraph →
+Knowledge split (see docs/architecture/DESIGN-robustness-security-inference.md
+§0, §1, §6, §10). It adds no IR atom: every fact it reads (per-symbol
+annotations, endpoint surface, implements/extends edges) already exists.
+
+INVARIANT — Vendor-Agnostic Inference (VAI, DESIGN §0.5)
+--------------------------------------------------------
+No predicate in this module branches on a proprietary / client / convention
+name. A concrete annotation name (a repo's bespoke ``@<CustomGuard>``) may appear only in the
+*evidence* of a verdict, never in the predicate that produced it. The only name
+table here (`_OPEN_STANDARD_*`) lists **published open standards** and is used
+purely to *subtract the known baseline*; "custom" is the structural residue,
+discovered by frequency + specificity + correlation. A config file
+(`sourcecode.config.json`) is never required and never enters detection — it only
+upgrades a specific finding's confidence ``Likely → Verified``.
+
+The module never raises: any structural gap degrades to ``Unknown`` with a
+reason, following the "absence of evidence is not evidence of absence"
+discipline. It never emits a categorical "N endpoints unsecured".
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional
+
+from sourcecode.security_config import load_custom_security
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+
+# ---------------------------------------------------------------------------
+# Evidence-Confidence envelope (DESIGN §0) — shared vocabulary
+# ---------------------------------------------------------------------------
+
+class Confidence(str, Enum):
+    """A verdict's confidence. ``str`` mixin so it serializes to its label."""
+
+    VERIFIED = "Verified"                          # a fact atom directly supports the claim
+    LIKELY = "Likely"                              # inferred from a pattern/relation, not a direct atom
+    UNKNOWN = "Unknown"                            # no recognized pattern matched (absence of evidence)
+    REQUIRES_MANUAL_REVIEW = "RequiresManualReview"  # conflicting / partial evidence
+
+
+@dataclass
+class Evidence:
+    """What a verdict was derived from — atoms, relations, source spans."""
+
+    atoms_used: list = field(default_factory=list)
+    relations_used: list = field(default_factory=list)
+    source_spans: list = field(default_factory=list)
+    # free-form structural evidence (coverage %, correlated filter, concrete
+    # annotation name-as-evidence). Concrete names are ALLOWED here — never in a
+    # predicate.
+    details: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        out: dict = {}
+        if self.atoms_used:
+            out["atoms_used"] = list(self.atoms_used)
+        if self.relations_used:
+            out["relations_used"] = list(self.relations_used)
+        if self.source_spans:
+            out["source_spans"] = list(self.source_spans)
+        if self.details:
+            out["details"] = dict(self.details)
+        return out
+
+
+@dataclass
+class Verdict:
+    """A Knowledge-Layer conclusion carrying its Evidence-Confidence envelope."""
+
+    claim: str
+    confidence: Confidence
+    evidence: Evidence = field(default_factory=Evidence)
+    limitations: list[str] = field(default_factory=list)
+    fp_causes: list[str] = field(default_factory=list)
+    fn_causes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "claim": self.claim,
+            "confidence": self.confidence.value,
+            "evidence": self.evidence.to_dict(),
+            "limitations": list(self.limitations),
+            "fp_causes": list(self.fp_causes),
+            "fn_causes": list(self.fn_causes),
+        }
+
+
+# ---------------------------------------------------------------------------
+# Open-standard baseline table (DESIGN §0.5) — DATA, not predicates
+# ---------------------------------------------------------------------------
+# The ONLY name table permitted. It lists published, open-standard vocabulary so
+# the engine can *subtract the known baseline* and treat the residue as
+# candidate-custom. Rules (enforced by the VAI grep-gate test):
+#   1. Only open, published standards — NEVER a client / project name.
+#   2. Used only to subtract the baseline — never to positively match "custom".
+#
+# Simple names (annotation `@X` is stored as the token `@X`; we compare `X`).
+# Covers three published families that legitimately appear on handler methods:
+# authorization, HTTP-mapping/binding, and bean-validation — so that a repo's
+# non-standard *residue* is what remains.
+
+# Published authorization / authentication vocabulary
+# (org.springframework.security, jakarta/javax.annotation.security,
+#  jakarta/javax.ws.rs.security, Apache Shiro published annotations).
+_OPEN_STANDARD_SECURITY: frozenset[str] = frozenset({
+    "PreAuthorize", "PostAuthorize", "PreFilter", "PostFilter", "Secured",
+    "RolesAllowed", "PermitAll", "DenyAll", "Authenticated",
+    "AuthenticationPrincipal", "CurrentSecurityContext", "EnableWebSecurity",
+    "EnableMethodSecurity", "EnableGlobalMethodSecurity", "RequiresAuthentication",
+    "RequiresUser", "RequiresGuest", "RequiresRoles", "RequiresPermissions",
+    "RequiresGuestOnly",
+})
+
+# Published HTTP-mapping / request-binding vocabulary (Spring MVC + JAX-RS).
+# These appear on ~all handlers; subtracting them keeps coverage meaningful.
+_OPEN_STANDARD_WEB: frozenset[str] = frozenset({
+    "RequestMapping", "GetMapping", "PostMapping", "PutMapping", "DeleteMapping",
+    "PatchMapping", "RequestBody", "ResponseBody", "ResponseStatus", "RestController",
+    "Controller", "PathVariable", "RequestParam", "RequestHeader", "RequestPart",
+    "ModelAttribute", "CookieValue", "MatrixVariable", "SessionAttribute",
+    "RequestAttribute", "CrossOrigin", "ExceptionHandler", "InitBinder",
+    "Path", "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS",
+    "Produces", "Consumes", "PathParam", "QueryParam", "HeaderParam",
+    "FormParam", "CookieParam", "MatrixParam", "BeanParam", "Context", "DefaultValue",
+})
+
+# Published bean-validation / documentation vocabulary.
+_OPEN_STANDARD_MISC: frozenset[str] = frozenset({
+    "Valid", "Validated", "NotNull", "NotBlank", "NotEmpty", "Size", "Min", "Max",
+    "Pattern", "Email", "Positive", "Negative", "Transactional", "Async",
+    "Operation", "ApiOperation", "ApiResponse", "ApiResponses", "Parameter",
+    "Tag", "Schema", "Deprecated", "Override", "SuppressWarnings", "Autowired",
+    "Qualifier", "Value", "Inject", "Resource",
+})
+
+_OPEN_STANDARD_BASELINE: frozenset[str] = (
+    _OPEN_STANDARD_SECURITY | _OPEN_STANDARD_WEB | _OPEN_STANDARD_MISC
+)
+
+# Published request-chain SPI base types / interfaces (servlet + Spring +
+# JAX-RS). A class that implements/extends one of these IS a request interceptor,
+# by structure — the concrete base type is recorded as evidence, never branched.
+_REQUEST_CHAIN_SPI: frozenset[str] = frozenset({
+    "Filter", "OncePerRequestFilter", "GenericFilterBean", "HandlerInterceptor",
+    "HandlerInterceptorAdapter", "WebFilter", "ContainerRequestFilter",
+    "ContainerResponseFilter", "ClientHttpRequestInterceptor",
+    "SecurityFilterChain", "WebSecurityConfigurerAdapter", "AbstractSecurityInterceptor",
+    "DelegatingFilterProxy",
+})
+
+# Endpoint security policies that ARE a recognized standard per-method guard.
+# ("none_detected"/"programmatic"/"xml_or_filter_chain" are NOT per-method guards;
+#  "custom" is a config-recognized custom gate, handled separately.)
+_STANDARD_GUARD_POLICIES: frozenset[str] = frozenset({
+    "deny_all", "permit_all", "roles_allowed", "authenticated", "secured",
+    "openapi_security", "requiresauthentication", "requiresroles",
+    "requirespermissions", "requiresuser",
+})
+
+
+def _is_baseline(simple: str) -> bool:
+    """True if ``simple`` (an annotation simple-name, no '@') is published
+    open-standard vocabulary. Pure set-subtraction against the baseline DATA
+    table — NOT a client-name branch (VAI §0.5)."""
+    return simple in _OPEN_STANDARD_BASELINE
+
+
+def _is_standard_guard_policy(policy: str) -> bool:
+    """True if an endpoint's security policy is a recognized standard guard."""
+    p = (policy or "").lower()
+    return p in _STANDARD_GUARD_POLICIES or p.startswith("spring_") or p.startswith("shiro_")
+
+
+# ---------------------------------------------------------------------------
+# Structural substrate (reads existing IR facts — adds no atom)
+# ---------------------------------------------------------------------------
+
+def _annotation_simple(token: str) -> str:
+    """`@Foo(bar=1)` / `@a.b.Foo` → `Foo`. Meaning-free normalization."""
+    t = (token or "").strip().lstrip("@")
+    t = t.split("(", 1)[0].strip()
+    return t.rsplit(".", 1)[-1]
+
+
+def _graph_nodes(cir: "CanonicalRepositoryIR") -> list[dict]:
+    raw = getattr(cir, "_raw_ir", None) or {}
+    graph = raw.get("graph") if isinstance(raw, dict) else None
+    if not isinstance(graph, dict):
+        return []
+    nodes = graph.get("nodes")
+    return nodes if isinstance(nodes, list) else []
+
+
+# Symbol kinds that are callable members carrying method-level annotations.
+# A mapped handler surfaces as kind "endpoint"; a plain method as "method".
+_METHOD_KINDS: frozenset[str] = frozenset({"method", "endpoint"})
+
+
+def _owner_of(method_fqn: str) -> str:
+    """Owning class FQN of a method symbol `pkg.Class#method` → `pkg.Class`."""
+    return method_fqn.split("#", 1)[0] if "#" in method_fqn else method_fqn
+
+
+@dataclass
+class _AnnotationUsage:
+    """Meaning-free usage stat for one annotation simple-name (DESIGN §1 IR note,
+    computed here as a Knowledge-Layer projection — no new atom)."""
+
+    simple: str
+    token: str                          # representative source token (evidence only)
+    handler_hits: int = 0               # controller-handler methods carrying it
+    non_handler_hits: int = 0           # any other method carrying it
+    handler_owners: set[str] = field(default_factory=set)
+
+
+def _collect_usage(
+    cir: "CanonicalRepositoryIR",
+) -> tuple[dict[str, _AnnotationUsage], int, int, set[str]]:
+    """Scan existing per-symbol annotations. Returns (usage_by_simple,
+    total_handler_methods, total_non_handler_methods, handler_symbols).
+
+    Controller-handler methods = the handler symbols of `cir.endpoints`; this is
+    the authoritative endpoint surface (already structurally derived by the IR).
+    """
+    handler_symbols: set[str] = {
+        ep.handler_symbol for ep in cir.endpoints if getattr(ep, "handler_symbol", "")
+    }
+    controller_classes: set[str] = {
+        ep.controller_class for ep in cir.endpoints if getattr(ep, "controller_class", "")
+    }
+
+    usage: dict[str, _AnnotationUsage] = {}
+    total_handler = 0
+    total_non_handler = 0
+
+    for node in _graph_nodes(cir):
+        if not isinstance(node, dict):
+            continue
+        if node.get("symbol_kind") not in _METHOD_KINDS:
+            continue
+        fqn = node.get("fqn") or ""
+        anns = node.get("annotations") or []
+        if not isinstance(anns, list):
+            continue
+        is_handler = fqn in handler_symbols
+        # a method of a controller class that is not itself a mapped endpoint
+        # still counts toward the "non-handler" denominator (specificity signal)
+        if is_handler:
+            total_handler += 1
+        else:
+            total_non_handler += 1
+        for tok in anns:
+            simple = _annotation_simple(str(tok))
+            if not simple:
+                continue
+            u = usage.get(simple)
+            if u is None:
+                u = _AnnotationUsage(simple=simple, token=str(tok).split("(", 1)[0])
+                usage[simple] = u
+            if is_handler:
+                u.handler_hits += 1
+                u.handler_owners.add(_owner_of(fqn))
+            else:
+                u.non_handler_hits += 1
+
+    return usage, total_handler, total_non_handler, handler_symbols
+
+
+# ---------------------------------------------------------------------------
+# Request-interception inference (DESIGN §1 correlation booster)
+# ---------------------------------------------------------------------------
+
+def _infer_interception(cir: "CanonicalRepositoryIR") -> Optional[Verdict]:
+    """Infer an authentication/request pipeline from structure: classes that
+    implement/extend a published request-chain SPI (§0.5 baseline). The concrete
+    base type is evidence, never a branch. Returns a ``Likely`` verdict or None.
+    """
+    interceptors: list[dict] = []
+    for edge in getattr(cir, "dependencies", None) or []:
+        if not isinstance(edge, dict):
+            continue
+        if edge.get("type") not in ("implements", "extends"):
+            continue
+        base_simple = (edge.get("to") or "").split("<", 1)[0].rsplit(".", 1)[-1]
+        if base_simple in _REQUEST_CHAIN_SPI:
+            interceptors.append({
+                "class": edge.get("from") or "",
+                "implements": base_simple,
+            })
+
+    if not interceptors:
+        return None
+
+    interceptors.sort(key=lambda d: d["class"])
+    return Verdict(
+        claim="Authentication pipeline inferred",
+        confidence=Confidence.LIKELY,
+        evidence=Evidence(
+            relations_used=[f"{d['class']} -> {d['implements']}" for d in interceptors],
+            details={
+                "interceptor_count": len(interceptors),
+                "interceptors": interceptors[:50],
+            },
+        ),
+        limitations=[
+            "Pipeline order (@Order/registration) and per-filter URL patterns are "
+            "not reconstructed in this increment — presence is structural only.",
+            "A request-chain SPI implementer does not prove the filter enforces "
+            "authorization; it establishes a request-interception surface.",
+        ],
+        fp_causes=["A logging/CORS/metrics filter also implements the servlet Filter SPI."],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Custom-gate auto-detection (DESIGN §1 — VAI-clean heuristic)
+# ---------------------------------------------------------------------------
+
+# Tunable thresholds (structural, name-free).
+_DEFAULT_COVERAGE = 0.15        # (b) ≥N% of controller-handler methods
+_SPECIFICITY_RATIO = 3.0        # (c) handler rate ≫ non-handler rate
+
+
+def _detect_custom_gates(
+    cir: "CanonicalRepositoryIR",
+    *,
+    coverage_threshold: float,
+    interception: Optional[Verdict],
+    configured: dict[str, Any],
+) -> list[Verdict]:
+    """Discover candidate custom authorization annotations by STRUCTURE only.
+
+    An annotation simple-name is a candidate custom gate when ALL hold — each a
+    structural test, none a name check (DESIGN §1):
+      (a) outside the open-standard baseline table (set-subtraction on DATA);
+      (b) coverage — on ≥ threshold of controller-handler methods;
+      (c) specificity — its handler rate ≫ its non-handler rate;
+      (d) correlation (booster) — co-occurs with a request-interception surface.
+
+    Emits ``Likely`` verdicts. A `sourcecode.config.json` entry naming the same
+    annotation upgrades it to ``Verified`` (user asserting ground truth) — but
+    detection already fired without it.
+    """
+    usage, total_handler, total_non_handler, _ = _collect_usage(cir)
+    if total_handler == 0:
+        return []
+
+    verdicts: list[Verdict] = []
+    for simple, u in sorted(usage.items()):
+        # (a) subtract the published baseline
+        if _is_baseline(simple):
+            continue
+        # (b) coverage over the controller-handler surface
+        coverage = u.handler_hits / total_handler
+        if coverage < coverage_threshold:
+            continue
+        # (c) specificity: tracks the endpoint surface, not the whole codebase
+        handler_rate = coverage
+        non_handler_rate = (
+            u.non_handler_hits / total_non_handler if total_non_handler else 0.0
+        )
+        if non_handler_rate > 0.0 and handler_rate < _SPECIFICITY_RATIO * non_handler_rate:
+            continue
+
+        # (d) correlation booster — still Likely without config; config → Verified
+        correlated = interception is not None
+        config_confirmed = simple in configured
+        confidence = Confidence.VERIFIED if config_confirmed else Confidence.LIKELY
+
+        details: dict = {
+            # concrete name lives ONLY here, as evidence (VAI §0.5)
+            "annotation": u.token,
+            "coverage": round(coverage, 4),
+            "coverage_pct": f"{round(coverage * 100)}% of controller handlers",
+            "handler_hits": u.handler_hits,
+            "handler_total": total_handler,
+            "non_handler_hits": u.non_handler_hits,
+            "specificity_ratio": (
+                round(handler_rate / non_handler_rate, 2)
+                if non_handler_rate > 0 else None
+            ),
+            "correlated_with_interception": correlated,
+            "config_confirmed": config_confirmed,
+        }
+        limitations = [
+            "Detected structurally (coverage + specificity); confirm the annotation "
+            "actually enforces authorization.",
+        ]
+        if not config_confirmed:
+            limitations.append(
+                "Confidence is Likely — declare this annotation in "
+                "sourcecode.config.json to upgrade to Verified."
+            )
+        verdicts.append(Verdict(
+            claim="Custom authorization mechanism detected",
+            confidence=confidence,
+            evidence=Evidence(details=details),
+            limitations=limitations,
+            fp_causes=[
+                "A non-security annotation applied systematically to controllers "
+                "(e.g. auditing/logging) can present the same coverage shape.",
+            ],
+            fn_causes=[
+                "A gate applied to <{:.0%} of handlers, or class-level only, may "
+                "fall below the coverage threshold.".format(coverage_threshold),
+            ],
+        ))
+    return verdicts
+
+
+# ---------------------------------------------------------------------------
+# Per-endpoint 4-way posture (DESIGN §1)
+# ---------------------------------------------------------------------------
+
+def _handler_annotation_index(cir: "CanonicalRepositoryIR") -> dict[str, set[str]]:
+    """handler_symbol → {annotation simple-names on that method}."""
+    idx: dict[str, set[str]] = {}
+    for node in _graph_nodes(cir):
+        if not isinstance(node, dict) or node.get("symbol_kind") not in _METHOD_KINDS:
+            continue
+        fqn = node.get("fqn") or ""
+        anns = node.get("annotations") or []
+        if isinstance(anns, list):
+            idx[fqn] = {_annotation_simple(str(t)) for t in anns}
+    return idx
+
+
+def gate_bearing_handlers(
+    cir: "CanonicalRepositoryIR", gate_simple_names: set[str]
+) -> set[str]:
+    """handler_symbols whose method carries one of the given (auto-detected or
+    configured) custom-gate annotations. Used to suppress categorical
+    "unsecured" false alarms (DESIGN §10 acceptance #3)."""
+    if not gate_simple_names:
+        return set()
+    handler_syms = {ep.handler_symbol for ep in cir.endpoints if ep.handler_symbol}
+    idx = _handler_annotation_index(cir)
+    return {
+        h for h in handler_syms
+        if idx.get(h, set()) & gate_simple_names
+    }
+
+
+@dataclass
+class SecurityPostureResult:
+    """Repo-level security-posture projection (P1-A)."""
+
+    security_model: str
+    custom_gates: list[Verdict] = field(default_factory=list)
+    interception: Optional[Verdict] = None
+    endpoint_verdicts: list[dict] = field(default_factory=list)
+    rollup: dict = field(default_factory=dict)
+    limitations: list[str] = field(default_factory=list)
+
+    def gate_simple_names(self) -> set[str]:
+        out: set[str] = set()
+        for v in self.custom_gates:
+            name = v.evidence.details.get("annotation") if v.evidence else None
+            if name:
+                out.add(_annotation_simple(str(name)))
+        return out
+
+    def to_dict(self) -> dict:
+        return {
+            "provenance": "security_posture projection (P1-A)",
+            "security_model": self.security_model,
+            "custom_authorization_mechanisms": [v.to_dict() for v in self.custom_gates],
+            "authentication_pipeline": (
+                self.interception.to_dict() if self.interception else None
+            ),
+            "endpoints": self.endpoint_verdicts,
+            "rollup": self.rollup,
+            "limitations": list(self.limitations),
+        }
+
+
+def infer_security_posture(
+    cir: "CanonicalRepositoryIR",
+    *,
+    root: Optional[Path] = None,
+    coverage_threshold: float = _DEFAULT_COVERAGE,
+) -> SecurityPostureResult:
+    """Infer the repo's endpoint security posture (P1-A).
+
+    Pipeline (all Knowledge Layer, no IR change):
+      1. infer the request-interception surface (structural);
+      2. auto-detect candidate custom authorization mechanisms (VAI-clean);
+      3. upgrade any that a config file confirms (Likely → Verified);
+      4. classify every endpoint into the 4-way posture with its confidence.
+
+    Never raises; never emits a categorical "unsecured" verdict.
+    """
+    security_model = str(cir.metadata.get("security_model", "unknown"))
+
+    # (0) config: names never drive detection — only upgrade confidence.
+    configured: dict[str, Any] = {}
+    try:
+        for spec in load_custom_security(root):
+            configured[spec.short_name] = spec
+    except Exception:
+        configured = {}
+
+    # (1) interception surface
+    interception = _infer_interception(cir)
+
+    # (2)+(3) custom-gate auto-detect, with config-driven confidence upgrade
+    custom_gates = _detect_custom_gates(
+        cir,
+        coverage_threshold=coverage_threshold,
+        interception=interception,
+        configured=configured,
+    )
+
+    gate_names = set()
+    for v in custom_gates:
+        nm = v.evidence.details.get("annotation")
+        if nm:
+            gate_names.add(_annotation_simple(str(nm)))
+    has_custom_gate = bool(custom_gates)
+    gate_bearers = gate_bearing_handlers(cir, gate_names)
+
+    # (4) per-endpoint 4-way classification
+    handler_ann = _handler_annotation_index(cir)
+    verdicts: list[dict] = []
+    rollup = {"protected_standard": 0, "protected_custom": 0,
+              "coverage_unknown": 0, "probably_exposed": 0}
+
+    for ep in cir.endpoints:
+        policy = ep.security.policy if ep.security is not None else "none_detected"
+        anns = handler_ann.get(ep.handler_symbol, set())
+        carries_gate = bool(anns & gate_names)
+
+        if policy == "custom" or carries_gate:
+            # protected by a custom gate. Verified only if the specific gate is
+            # config-confirmed; otherwise the mechanism is inferred → Likely.
+            gate_conf = Confidence.LIKELY
+            if policy == "custom" and ep.security and ep.security.annotation in configured:
+                gate_conf = Confidence.VERIFIED
+            elif carries_gate and (anns & set(configured.keys())):
+                gate_conf = Confidence.VERIFIED
+            verdict = "protected_custom"
+            confidence = gate_conf
+        elif _is_standard_guard_policy(policy):
+            verdict = "protected_standard"
+            confidence = Confidence.VERIFIED
+        elif security_model == "unknown":
+            verdict = "coverage_unknown"
+            confidence = Confidence.UNKNOWN
+        elif security_model in ("filter_based", "xml_or_filter_chain") or interception is not None:
+            # a centralized filter/interception surface plausibly covers this route
+            verdict = "coverage_unknown"
+            confidence = Confidence.UNKNOWN
+        elif has_custom_gate:
+            # a custom gate exists in the repo but not on THIS endpoint. Never
+            # categorical "unsecured": worst case is manual review (§10 #3).
+            verdict = "coverage_unknown"
+            confidence = Confidence.REQUIRES_MANUAL_REVIEW
+        elif security_model == "annotation_based":
+            # only warning verdict — Likely, never categorical.
+            verdict = "probably_exposed"
+            confidence = Confidence.LIKELY
+        else:
+            verdict = "coverage_unknown"
+            confidence = Confidence.UNKNOWN
+
+        rollup[verdict] = rollup.get(verdict, 0) + 1
+        verdicts.append({
+            "endpoint_id": ep.id,
+            "method": ep.method,
+            "path": ep.path,
+            "handler_symbol": ep.handler_symbol,
+            "verdict": verdict,
+            "confidence": confidence.value,
+            "policy": policy,
+        })
+
+    limitations = [
+        "Posture is inferred from static structure; a runtime security config "
+        "(WebSecurity DSL, XML) may protect routes this projection marks unknown.",
+    ]
+    if has_custom_gate:
+        limitations.append(
+            "A custom authorization mechanism was inferred — endpoints not carrying "
+            "it are reported 'coverage_unknown', never 'unsecured'."
+        )
+
+    result = SecurityPostureResult(
+        security_model=security_model,
+        custom_gates=custom_gates,
+        interception=interception,
+        endpoint_verdicts=verdicts,
+        rollup=rollup,
+        limitations=limitations,
+    )
+    # keep reference to suppress-set so callers (SEC-001) can dedupe false alarms
+    result._gate_bearing_handlers = gate_bearers  # type: ignore[attr-defined]
+    return result

sourcecode/semantic_integration_engine.py

@@ -179,7 +179,9 @@ class SemanticIntegrationEngine:
 
     def detect(self) -> list[Integration]:
         """All outbound integrations recoverable from typed facts, deterministically
-        ordered. One record per (type, kind, client). Targets are attributed by
+        ordered. One record per semantic point (kind + evidence location): a type that
+        touches several client libraries of the same kind counts once. Targets are
+        attributed by
         annotation args (declarative) or by literal scheme (imperative), never by a
         receiver variable name."""
         per_type: dict[str, list[Integration]] = {}
@@ -231,7 +233,21 @@ class SemanticIntegrationEngine:
             per_type[t.fqn] = list(recs.values())
 
         out = [r for recs in per_type.values() for r in recs]
-        return sorted(out, key=lambda i: (i.kind, i.client, i.evidence))
+        out.sort(key=lambda i: (i.kind, i.client, i.evidence))
+        # REG-1 (Broadleaf field test): one integration per semantic point =
+        # (kind, evidence location). A single type touching several client-library
+        # types of the SAME kind — e.g. spring-ldap + spring-security-ldap on one
+        # LdapUserDetailsMapper, or javamail + spring-mail on one MessageCreator —
+        # previously emitted one record per client label, double-counting the same
+        # integration. Collapse to a single record per (kind, evidence), preferring
+        # one that carries a resolved target; ties broken by the deterministic
+        # (kind, client, evidence) order established above.
+        deduped: dict[tuple, Integration] = {}
+        for r in out:
+            k = (r.kind, r.evidence)
+            if k not in deduped or (r.target and deduped[k].target is None):
+                deduped[k] = r
+        return list(deduped.values())
 
     def _coverage(self, n_records: int, n_files: int) -> "tuple[str, str]":
         """Honest coverage signal (mirrors integration_detector): a low count on a

sourcecode/serializer.py

@@ -462,11 +462,31 @@ def _mybatis_pairing(sm: "SourceMap", *, full: bool = False) -> "Optional[dict[s
 
 
 def _spring_boot_version(sm: "SourceMap") -> "Optional[str]":
-    """Extract Spring Boot version from detected frameworks."""
+    """Extract Spring Boot version from detected frameworks.
+
+    A3 fix (field validation, Broadleaf): when Spring Boot IS detected but the
+    stack detector could not attach a version (e.g. the version lives in a
+    `<spring.boot.version>` pom property rather than spring-boot-starter-parent),
+    fall back to migrate-check's property-resolving detector so `--compact`
+    reports the SAME version migrate-check already knows — the engine must not
+    surface a fact in one command and hide it in another. Gated on Boot already
+    being detected, so no phantom version is ever introduced.
+    """
+    _boot_detected = False
     for s in sm.stacks:
         for fw in s.frameworks:
-            if fw.name == "Spring Boot" and fw.version:
-                return fw.version
+            if fw.name == "Spring Boot":
+                if fw.version:
+                    return fw.version
+                _boot_detected = True
+    if _boot_detected:
+        _root = getattr(sm.metadata, "analyzed_path", None) if sm.metadata else None
+        if _root:
+            try:
+                from sourcecode.migrate_check import _detect_spring_boot
+                return _detect_spring_boot(Path(_root), 0)[1]
+            except Exception:
+                return None
     return None
 
 
@@ -753,7 +773,7 @@ def _bootstrap_structured(eps: list) -> "Optional[dict[str, Any]]":
 
         _ctrl_note = (
             f"{controller_classes} controller classes detected"
-            f" (use 'sourcecode endpoints' for per-method HTTP surface)"
+            f" (use 'ask endpoints' for per-method HTTP surface)"
         )
         if len(module_names) > 30:
             # Group by first path segment under ddd/ (inferred domain area)