sourcecode 2.7.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

sourcecode/posture.py

@@ -0,0 +1,458 @@
+"""Which beans are actually wired under a profile set — and which cannot be decided.
+
+Profile *detection* already ships: `@Profile`, negations, expressions,
+`spring.config.activate.on-profile`. What was missing is the consumer. "We saw a
+profile" is a fact about a file; "under `prod`, these beans are registered and
+these four conditions could not be resolved" is a fact about the running system,
+and only the second one answers the question a reviewer actually has.
+
+Resolution is deliberately partial and says so. A bean whose registration
+depends on a property value, an environment lookup, or a condition class we
+cannot evaluate is reported as **unresolved**, never assumed active and never
+assumed absent. A posture answer that guesses is worse than no posture answer:
+it is a confident security falsehood, which is the failure mode this whole
+kernel exists to prevent.
+
+Supported today:
+  * `@Profile("a")`, `@Profile({"a","b"})` (OR), `@Profile("!a")`
+  * expressions over those with `&`, `|`, `!` and parentheses
+
+Everything else — `@ConditionalOnProperty` and the rest of the `@Conditional*`
+family — lands in `unresolved` with the condition named.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+POSTURE_SCHEMA = "posture-v1"
+
+#: Conditions we can see but not decide. Named so the report can say which one
+#: blocked resolution instead of dropping the bean silently.
+_UNRESOLVABLE_CONDITIONS = (
+    "@ConditionalOnProperty",
+    "@ConditionalOnExpression",
+    "@ConditionalOnBean",
+    "@ConditionalOnMissingBean",
+    "@ConditionalOnClass",
+    "@ConditionalOnMissingClass",
+    "@ConditionalOnResource",
+    "@ConditionalOnWebApplication",
+    "@ConditionalOnNotWebApplication",
+    "@ConditionalOnJava",
+    "@ConditionalOnCloudPlatform",
+    "@Conditional",
+)
+
+_TOKEN_RE = re.compile(r'"([^"]*)"|([A-Za-z0-9_.\-]+)|([()&|!])')
+
+
+class ProfileExpressionError(ValueError):
+    """The expression could not be evaluated — the bean is reported unresolved."""
+
+
+def _tokenize(expression: str) -> "list[str]":
+    tokens: list[str] = []
+    for quoted, bare, op in _TOKEN_RE.findall(expression):
+        text = quoted if quoted else (bare or op)
+        if quoted:
+            # A quoted argument may itself be an expression: "a & !b".
+            inner = _tokenize(text) if any(c in text for c in "&|!()") else [text]
+            if tokens and tokens[-1] not in ("&", "|", "!", "("):
+                tokens.append("|")  # {"a","b"} — array elements are OR'd
+            tokens.extend(inner)
+        elif text.strip():
+            tokens.append(text.strip())
+    return [t for t in tokens if t and t != ","]
+
+
+def evaluate_profile_expression(expression: str, active: "set[str]") -> bool:
+    """Spring `@Profile` semantics: array is OR, `!` negates, `&`/`|` combine.
+
+    Raises ProfileExpressionError when the expression is not a form we evaluate,
+    so the caller reports the bean as unresolved rather than deciding by guess.
+    """
+    tokens = _tokenize(expression)
+    if not tokens:
+        raise ProfileExpressionError("empty profile expression")
+    pos = 0
+
+    def parse_or() -> bool:
+        nonlocal pos
+        value = parse_and()
+        while pos < len(tokens) and tokens[pos] == "|":
+            pos += 1
+            value = parse_and() or value
+        return value
+
+    def parse_and() -> bool:
+        nonlocal pos
+        value = parse_unary()
+        while pos < len(tokens) and tokens[pos] == "&":
+            pos += 1
+            value = parse_unary() and value
+        return value
+
+    def parse_unary() -> bool:
+        nonlocal pos
+        if pos < len(tokens) and tokens[pos] == "!":
+            pos += 1
+            return not parse_unary()
+        if pos < len(tokens) and tokens[pos] == "(":
+            pos += 1
+            value = parse_or()
+            if pos >= len(tokens) or tokens[pos] != ")":
+                raise ProfileExpressionError(f"unbalanced parentheses in {expression!r}")
+            pos += 1
+            return value
+        if pos >= len(tokens):
+            raise ProfileExpressionError(f"expression ends early: {expression!r}")
+        name = tokens[pos]
+        if name in ("&", "|", ")"):
+            raise ProfileExpressionError(f"unexpected {name!r} in {expression!r}")
+        pos += 1
+        return name in active
+
+    result = parse_or()
+    if pos != len(tokens):
+        raise ProfileExpressionError(f"trailing tokens in {expression!r}")
+    return result
+
+
+@dataclass(frozen=True)
+class BeanResolution:
+    """What a profile set implies for the bean graph, and what it does not."""
+
+    profiles: tuple[str, ...]
+    active: tuple[dict, ...] = ()
+    inactive: tuple[dict, ...] = ()
+    unresolved: tuple[dict, ...] = ()
+    unconditional_count: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "profiles": list(self.profiles),
+            "summary": {
+                "conditional_beans": len(self.active) + len(self.inactive) + len(self.unresolved),
+                "active": len(self.active),
+                "inactive": len(self.inactive),
+                "unresolved": len(self.unresolved),
+                "unconditional": self.unconditional_count,
+            },
+            "active": list(self.active),
+            "inactive": list(self.inactive),
+            # Never folded into active or inactive: a condition we cannot decide
+            # is a hole in the answer, and the reader is told where it is.
+            "unresolved": list(self.unresolved),
+        }
+
+
+def _node_annotations(node: dict) -> "list[str]":
+    raw = node.get("annotations") or []
+    return [str(a) for a in raw] if isinstance(raw, list) else []
+
+
+def _unresolvable_conditions(node: dict) -> "list[str]":
+    present: list[str] = []
+    for annotation in _node_annotations(node):
+        simple = annotation.split("(", 1)[0].strip()
+        if simple in _UNRESOLVABLE_CONDITIONS:
+            present.append(simple)
+    return sorted(set(present))
+
+
+def resolve_beans(
+    cir: "CanonicalRepositoryIR", profiles: "Optional[set[str]]" = None
+) -> BeanResolution:
+    """Resolve the conditional bean graph against an active profile set."""
+    from sourcecode.security_posture import _graph_nodes
+    from sourcecode.spring_profiles import profile_conditional_beans
+
+    active_profiles = set(profiles or set())
+    conditional = {b.symbol: b for b in profile_conditional_beans(cir)}
+
+    active: list[dict] = []
+    inactive: list[dict] = []
+    unresolved: list[dict] = []
+    unconditional = 0
+
+    for node in _graph_nodes(cir):
+        if not isinstance(node, dict):
+            continue
+        fqn = str(node.get("fqn") or "")
+        if not fqn or "#" in fqn:
+            continue  # members follow their declaring type
+        blockers = _unresolvable_conditions(node)
+        bean = conditional.get(fqn)
+        if bean is None and not blockers:
+            unconditional += 1
+            continue
+        entry = {"symbol": fqn, "source_file": str(node.get("source_file") or "")}
+        if blockers:
+            unresolved.append({
+                **entry,
+                "condition": blockers[0] if len(blockers) == 1 else ", ".join(blockers),
+                "reason": "registration depends on a condition this analyzer does not evaluate",
+            })
+            continue
+        assert bean is not None
+        expression = bean.expression or " | ".join(f'"{p}"' for p in bean.profiles)
+        try:
+            is_active = evaluate_profile_expression(expression, active_profiles)
+        except ProfileExpressionError as exc:
+            unresolved.append({
+                **entry, "condition": f"@Profile({expression})", "reason": str(exc),
+            })
+            continue
+        (active if is_active else inactive).append({
+            **entry, "condition": f"@Profile({expression})",
+        })
+
+    key = lambda e: e["symbol"]  # noqa: E731 — deterministic ordering, nothing else
+    return BeanResolution(
+        profiles=tuple(sorted(active_profiles)),
+        active=tuple(sorted(active, key=key)),
+        inactive=tuple(sorted(inactive, key=key)),
+        unresolved=tuple(sorted(unresolved, key=key)),
+        unconditional_count=unconditional,
+    )
+
+
+#: Published Spring Security vocabulary that makes a bean part of the request
+#: chain's authorization configuration. Recorded as evidence; never branched on
+#: a client's own class name.
+_SECURITY_CONFIG_ANNOTATIONS = frozenset({
+    "@EnableWebSecurity", "@EnableMethodSecurity", "@EnableGlobalMethodSecurity",
+    "@EnableReactiveMethodSecurity", "@EnableWebFluxSecurity",
+})
+_SECURITY_CONFIG_SUPERTYPES = frozenset({
+    "WebSecurityConfigurerAdapter", "SecurityFilterChain",
+    "AbstractSecurityInterceptor", "OncePerRequestFilter",
+})
+
+
+def _is_security_relevant(node: dict, cir: "CanonicalRepositoryIR") -> bool:
+    """True when this bean configures the request chain's authorization.
+
+    Structure only: a published security annotation, or a supertype from the
+    request-chain SPI. Which profile switches the security configuration is the
+    single most consequential thing a profile can change, so this projection
+    exists to make that switch visible rather than buried in a bean count.
+    """
+    for annotation in _node_annotations(node):
+        if annotation.split("(", 1)[0].strip() in _SECURITY_CONFIG_ANNOTATIONS:
+            return True
+    supertypes = node.get("supertypes") or node.get("extends") or []
+    if isinstance(supertypes, str):
+        supertypes = [supertypes]
+    if isinstance(supertypes, list):
+        for base in supertypes:
+            if str(base).rsplit(".", 1)[-1] in _SECURITY_CONFIG_SUPERTYPES:
+                return True
+    # A @Bean method returning SecurityFilterChain lives on the declaring class.
+    fqn = str(node.get("fqn") or "")
+    for member in _graph_nodes_cached(cir):
+        if not isinstance(member, dict):
+            continue
+        member_fqn = str(member.get("fqn") or "")
+        if not member_fqn.startswith(f"{fqn}#"):
+            continue
+        return_type = str(member.get("return_type") or "").rsplit(".", 1)[-1]
+        if return_type in _SECURITY_CONFIG_SUPERTYPES:
+            return True
+    return False
+
+
+def _graph_nodes_cached(cir: "CanonicalRepositoryIR") -> "list[dict]":
+    cached = getattr(cir, "_posture_nodes", None)
+    if cached is not None:
+        return cached
+    from sourcecode.security_posture import _graph_nodes
+
+    nodes = list(_graph_nodes(cir))
+    try:
+        object.__setattr__(cir, "_posture_nodes", nodes)
+    except Exception:
+        pass
+    return nodes
+
+
+def security_projection(cir: "CanonicalRepositoryIR", resolution: BeanResolution) -> dict:
+    """The security-relevant slice of a bean resolution."""
+    by_fqn = {
+        str(n.get("fqn") or ""): n for n in _graph_nodes_cached(cir) if isinstance(n, dict)
+    }
+
+    def _slice(entries: "tuple[dict, ...]") -> "list[dict]":
+        out = []
+        for entry in entries:
+            node = by_fqn.get(entry["symbol"])
+            if node is not None and _is_security_relevant(node, cir):
+                out.append(entry)
+        return out
+
+    active = _slice(resolution.active)
+    inactive = _slice(resolution.inactive)
+    unresolved = _slice(resolution.unresolved)
+    return {
+        "active": active,
+        "inactive": inactive,
+        "unresolved": unresolved,
+        "summary": {
+            "active": len(active), "inactive": len(inactive), "unresolved": len(unresolved),
+        },
+    }
+
+
+#: Policies that mean "this handler carries no guard of its own" — everything
+#: else is one. Empty covers an endpoint with no security record at all.
+_NO_HANDLER_GUARD_POLICIES = frozenset({
+    "", "none_detected", "programmatic", "xml_or_filter_chain",
+})
+
+
+def endpoint_projection(cir: "CanonicalRepositoryIR", security: dict) -> dict:
+    """What the resolved security configuration means for the HTTP surface.
+
+    An endpoint carrying its own guard (`@PreAuthorize`, `@RolesAllowed`, …) is
+    protected regardless of which profile is active. An endpoint without one
+    depends on the request chain — so when a profile set activates no chain
+    configuration at all, those endpoints are the ones a reviewer must be told
+    about by name, not left to derive from a bean list.
+
+    The claim is only made when the repository *has* security configuration that
+    this profile set switched off. A repository that never configured security
+    has a different problem, and saying "unprotected under prod" about it would
+    blame the profile for something the profile does not do.
+    """
+    guarded: list[str] = []
+    chain_dependent: list[dict] = []
+    for endpoint in getattr(cir, "endpoints", []) or []:
+        policy = getattr(getattr(endpoint, "security", None), "policy", None) or ""
+        entry = {"id": endpoint.id, "method": endpoint.method, "path": endpoint.path}
+        # Complement, not an allow-list: any policy other than the three that
+        # mean "no guard on this handler" IS a guard. Enumerating guard names
+        # instead would silently reclassify an endpoint as exposed the day a new
+        # guard vocabulary is recognised.
+        if policy in _NO_HANDLER_GUARD_POLICIES:
+            chain_dependent.append(entry)
+        else:
+            guarded.append(endpoint.id)
+
+    out: dict = {
+        "total": len(guarded) + len(chain_dependent),
+        "guarded_by_own_annotation": len(guarded),
+        "depends_on_request_chain": len(chain_dependent),
+    }
+    configures_chain = bool(security["active"])
+    switched_off = bool(security["inactive"]) and not configures_chain
+    if switched_off and chain_dependent:
+        out["unguarded_under_this_profile_set"] = [e["id"] for e in chain_dependent[:200]]
+        out["statement"] = (
+            f"{len(chain_dependent)} endpoint(s) carry no per-method guard, and this "
+            "profile set activates none of the repository's request-chain configuration"
+        )
+    if security["unresolved"]:
+        out["caveat"] = (
+            f"{len(security['unresolved'])} security configuration bean(s) could not be "
+            "resolved; the statement above does not account for what they would wire"
+        )
+    return out
+
+
+def build_posture(root: Path, profiles: "Optional[set[str]]" = None) -> dict:
+    """`posture` payload for one profile set."""
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.repository_ir import find_java_files
+    from sourcecode.spring_profiles import profiles_from_annotations, profiles_from_config
+
+    root = Path(root).resolve()
+    files = find_java_files(root)
+    cir = ContextGraph.build(files, root).cir
+    resolution = resolve_beans(cir, profiles)
+
+    declared = sorted(set(profiles_from_config(root)) | set(profiles_from_annotations(root, files)))
+    payload: dict = {
+        "schema_version": POSTURE_SCHEMA,
+        "profiles_requested": sorted(profiles or set()),
+        "profiles_declared": declared,
+        **resolution.to_dict(),
+        # Called out separately because a profile that switches the security
+        # configuration is not one bean among many — it is the difference
+        # between an authenticated surface and an open one.
+        "security": security_projection(cir, resolution),
+    }
+    payload["endpoints"] = endpoint_projection(cir, payload["security"])
+    # A requested profile no repository artefact mentions is almost always a typo,
+    # and silently resolving every `@Profile` against it would answer confidently
+    # about a configuration that does not exist.
+    unknown = sorted((profiles or set()) - set(declared))
+    if unknown:
+        payload["profiles_not_declared"] = unknown
+    return payload
+
+
+def diff_posture(root: Path, left: "set[str]", right: "set[str]") -> dict:
+    """What changes between two profile sets — the question a reviewer asks."""
+    a = build_posture(root, left)
+    b = build_posture(root, right)
+    a_active = {e["symbol"] for e in a["active"]}
+    b_active = {e["symbol"] for e in b["active"]}
+    unresolved = sorted(
+        {e["symbol"] for e in a["unresolved"]} | {e["symbol"] for e in b["unresolved"]}
+    )
+    a_sec = {e["symbol"] for e in a["security"]["active"]}
+    b_sec = {e["symbol"] for e in b["security"]["active"]}
+    sec_unresolved = sorted(
+        {e["symbol"] for e in a["security"]["unresolved"]}
+        | {e["symbol"] for e in b["security"]["unresolved"]}
+    )
+    security_delta: dict = {
+        "left_active": sorted(a_sec),
+        "right_active": sorted(b_sec),
+        "only_in_left": sorted(a_sec - b_sec),
+        "only_in_right": sorted(b_sec - a_sec),
+        "unresolved": sec_unresolved,
+    }
+    # One side configuring the request chain while the other does not is the
+    # finding this command exists to surface; it is stated, not left to be
+    # inferred from two lists.
+    left_names = ",".join(a["profiles_requested"]) or "(no profile)"
+    right_names = ",".join(b["profiles_requested"]) or "(no profile)"
+    if a_sec and not b_sec:
+        security_delta["note"] = (
+            f"{left_names} configures the request chain; "
+            f"{right_names} activates no security configuration"
+        )
+    elif b_sec and not a_sec:
+        security_delta["note"] = (
+            f"{right_names} configures the request chain; "
+            f"{left_names} activates no security configuration"
+        )
+
+    return {
+        "schema_version": POSTURE_SCHEMA,
+        "left": {
+            "profiles": a["profiles_requested"],
+            "active": len(a_active),
+            "endpoints": a["endpoints"],
+        },
+        "right": {
+            "profiles": b["profiles_requested"],
+            "active": len(b_active),
+            "endpoints": b["endpoints"],
+        },
+        "only_in_left": sorted(a_active - b_active),
+        "only_in_right": sorted(b_active - a_active),
+        "in_both": len(a_active & b_active),
+        "security": security_delta,
+        # A bean nobody could resolve is not "unchanged" — it is undecided under
+        # both sets, and a delta that hid it would read as a clean comparison.
+        "unresolved": unresolved,
+    }