coretrace-python-analyzer 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

coretrace_python/__init__.py

@@ -1,4 +1,4 @@
 """CoreTrace's Python static analysis frontend."""
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 

coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py

@@ -7,6 +7,7 @@ from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
 from coretrace_python.dependency import DependencyAnalysis
+from coretrace_python.dependency.correlation import affected_symbols, check_conditions, evidence
 from coretrace_python.findings import Confidence, Finding
 from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
@@ -17,12 +18,7 @@ class ReachableVulnerabilityPlugin(ProjectPlugin):
     requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
-        affected = {}
-        for requirement in ctx.dependencies.requirements:
-            for advisory in ctx.advisories:
-                if advisory.affects(requirement):
-                    for symbol in advisory.affected_symbols:
-                        affected.setdefault(symbol, advisory)
+        affected = affected_symbols(ctx.dependencies, ctx.advisories)
         if not affected:
             return ()
         findings: list[Finding] = []
@@ -32,25 +28,22 @@ class ReachableVulnerabilityPlugin(ProjectPlugin):
                 for site in graph.sites(function):
                     if not isinstance(site.target, ExternalSymbol):
                         continue
-                    advisory = affected.get(site.target.symbol)
-                    if advisory is None:
-                        continue
-                    findings.append(
-                        Finding(
-                            rule_id="reachable-vulnerability",
-                            message=(
-                                f"{advisory.id}: {site.target.symbol} is affected in the required "
-                                f"{advisory.package} {advisory.vulnerable}: {advisory.summary}"
-                            ),
-                            severity=advisory.severity,
-                            confidence=Confidence.HIGH,
-                            span=site.location,
-                            function=function,
-                            metadata={
-                                "advisory": advisory.id,
-                                "package": advisory.package,
-                                "symbol": str(site.target.symbol),
-                            },
+                    for advisory in affected.get(site.target.symbol, ()):
+                        check = check_conditions(advisory.entry_point(site.target.symbol), site.arguments)
+                        if check.contradicted is not None:
+                            continue
+                        findings.append(
+                            Finding(
+                                rule_id="reachable-vulnerability",
+                                message=(
+                                    f"{advisory.id}: {site.target.symbol} is affected in the required "
+                                    f"{advisory.package} {advisory.vulnerable}: {advisory.summary}"
+                                ),
+                                severity=advisory.severity,
+                                confidence=Confidence.HIGH,
+                                span=site.location,
+                                function=function,
+                                metadata=evidence(advisory, site.target.symbol, "reachable", check),
+                            )
                         )
-                    )
         return findings

coretrace_python/bundled/dependency/sample_advisories/sample_advisories.py

@@ -28,6 +28,7 @@ class SampleAdvisories(ModelPlugin):
             "yaml.load and full_load can execute arbitrary code from untrusted documents",
             Severity.CRITICAL,
             (_sym("yaml.load"), _sym("yaml.full_load"), _sym("yaml.unsafe_load")),
+            modules=("yaml",),
         ),
         Advisory(
             "CVE-2018-18074",
@@ -105,5 +106,6 @@ class SampleAdvisories(ModelPlugin):
             Severity.HIGH,
             (_sym("PIL.Image.open"),),
             ("GHSA-cfh3-3jmp-rvhc",),
+            modules=("PIL",),
         ),
     )

coretrace_python/bundled/dependency/vulnerable_dependency/plugin.toml

@@ -1,7 +1,7 @@
 name = "vulnerable-dependency"
 version = "1.0.0"
 plugin_api = ">=1,<2"
-requires = ["dependency.graph"]
+requires = ["dependency.graph", "interprocedural.callgraph"]
 provides = ["vulnerability.vulnerable-dependency"]
 
 [entrypoint]

coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py

@@ -7,21 +7,34 @@ from typing import ClassVar
 
 from coretrace_python.analysis import AnyAnalysis
 from coretrace_python.dependency import DependencyAnalysis
+from coretrace_python.dependency.correlation import affected_symbols, check_conditions, ruled_out
 from coretrace_python.findings import Confidence, Finding
+from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
 from coretrace_python.plugins import ProjectContext, ProjectPlugin
 
 
 class VulnerableDependencyPlugin(ProjectPlugin):
     name: ClassVar[str] = "vulnerable-dependency"
-    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis})
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
 
     def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
         findings: list[Finding] = []
+        imported = [s for module in ctx.modules for s in ctx.imports(module).all_symbols()]
+        excluded = _ruled_out(ctx)
         for requirement in ctx.dependencies.requirements:
             for advisory in ctx.advisories:
                 if not advisory.affects(requirement):
                     continue
                 pinned = requirement.pinned is not None
+                level = "imported" if advisory.imported_by(imported) else "declared"
+                metadata = {
+                    "advisory": advisory.id,
+                    "package": advisory.package,
+                    "specifier": requirement.specifier,
+                    "level": level,
+                }
+                if excluded.get(advisory.id):
+                    metadata["ruled_out"] = "; ".join(excluded[advisory.id])
                 findings.append(
                     Finding(
                         rule_id="vulnerable-dependency",
@@ -33,11 +46,26 @@ class VulnerableDependencyPlugin(ProjectPlugin):
                         severity=advisory.severity,
                         confidence=Confidence.HIGH if pinned else Confidence.MEDIUM,
                         span=requirement.span,
-                        metadata={
-                            "advisory": advisory.id,
-                            "package": advisory.package,
-                            "specifier": requirement.specifier,
-                        },
+                        metadata=metadata,
                     )
                 )
         return findings
+
+
+def _ruled_out(ctx: ProjectContext) -> dict[str, list[str]]:
+    """By advisory, the calls to its entry points whose arguments contradict one of its
+    conditions: the evidence that the requirement, imported, is not reached there."""
+
+    affected = affected_symbols(ctx.dependencies, ctx.advisories)
+    excluded: dict[str, list[str]] = {}
+    for module in sorted(ctx.modules):
+        graph = ctx.call_graph(module)
+        for function in graph.functions:
+            for site in graph.sites(function):
+                if not isinstance(site.target, ExternalSymbol):
+                    continue
+                for advisory in affected.get(site.target.symbol, ()):
+                    check = check_conditions(advisory.entry_point(site.target.symbol), site.arguments)
+                    if check.contradicted is not None:
+                        excluded.setdefault(advisory.id, []).append(ruled_out(module, site, check))
+    return excluded

coretrace_python/cache.py

@@ -22,11 +22,13 @@ from typing import Any
 
 from coretrace_python.findings import Confidence, Finding, Severity
 from coretrace_python.interprocedural import (
+    Arguments,
     CallSite,
     ExternalCall,
     ExternalSymbol,
     FunctionSummary,
     KnownFunction,
+    ModuleFunction,
     ModuleGraph,
     Mutation,
     NonlocalWrite,
@@ -37,14 +39,14 @@ from coretrace_python.interprocedural import (
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.source import SourceId, SourceSpan
 
-CACHE_FORMAT = 4
+CACHE_FORMAT = 7
 
 
 @dataclass(frozen=True)
 class CachedModule:
     """Everything a later run needs from one module without lowering it again."""
 
-    functions: tuple[str, ...]
+    functions: tuple[ModuleFunction, ...]
     summaries: Mapping[str, FunctionSummary]
     sites: tuple[CallSite, ...]
     findings: tuple[Finding, ...]
@@ -128,7 +130,7 @@ class ProjectCache:
 def encode(module: CachedModule) -> dict[str, Any]:
     return {
         "format": CACHE_FORMAT,
-        "functions": list(module.functions),
+        "functions": [[f.name, _encode_span(f.span), f.entry_point] for f in module.functions],
         "summaries": {name: _encode_summary(s) for name, s in module.summaries.items()},
         "sites": [_encode_site(site) for site in module.sites],
         "findings": [_encode_finding(finding) for finding in module.findings],
@@ -139,7 +141,7 @@ def decode(data: Mapping[str, Any]) -> CachedModule:
     if data["format"] != CACHE_FORMAT:
         raise ValueError(f"unsupported cache format {data['format']!r}")
     return CachedModule(
-        tuple(_string(name) for name in data["functions"]),
+        tuple(_decode_function(function) for function in data["functions"]),
         {_string(name): _decode_summary(s) for name, s in data["summaries"].items()},
         tuple(_decode_site(site) for site in data["sites"]),
         tuple(_decode_finding(finding) for finding in data["findings"]),
@@ -187,6 +189,11 @@ def _decode_span(data: Any) -> SourceSpan:
     )
 
 
+def _decode_function(data: Any) -> ModuleFunction:
+    name, span, entry_point = data
+    return ModuleFunction(_string(name), _decode_span(span), None if entry_point is None else _string(entry_point))
+
+
 def _encode_finding(finding: Finding) -> dict[str, Any]:
     return {
         "rule": finding.rule_id,
@@ -219,6 +226,7 @@ def _encode_call(call: ExternalCall) -> dict[str, Any]:
         "keywords": sorted(call.keyword_dependencies),
         "location": _encode_span(call.location),
         "call_site": None if call.call_site is None else _encode_span(call.call_site),
+        "given": _encode_arguments(call.arguments),
     }
 
 
@@ -230,6 +238,7 @@ def _decode_call(data: Mapping[str, Any]) -> ExternalCall:
         _indices(data["keywords"]),
         _decode_span(data["location"]),
         None if site is None else _decode_span(site),
+        _decode_arguments(data["given"]),
     )
 
 
@@ -311,8 +320,7 @@ def _encode_site(site: CallSite) -> dict[str, Any]:
         "caller": site.caller,
         "location": _encode_span(site.location),
         "target": _encode_target(site.target),
-        "arguments": site.arguments,
-        "keywords": site.keywords,
+        "arguments": _encode_arguments(site.arguments),
     }
 
 
@@ -321,6 +329,27 @@ def _decode_site(data: Mapping[str, Any]) -> CallSite:
         _string(data["caller"]),
         _decode_span(data["location"]),
         _decode_target(data["target"]),
-        _integer(data["arguments"]),
-        _integer(data["keywords"]),
+        _decode_arguments(data["arguments"]),
+    )
+
+
+def _encode_arguments(arguments: Arguments) -> dict[str, Any]:
+    return {
+        "positional": list(arguments.positional),
+        "keywords": [[name, value] for name, value in arguments.keywords],
+        "unpacked": arguments.unpacked,
+    }
+
+
+def _decode_arguments(data: Mapping[str, Any]) -> Arguments:
+    def denoted(value: Any) -> str | None:
+        return None if value is None else _string(value)
+
+    unpacked = data["unpacked"]
+    if not isinstance(unpacked, bool):
+        raise TypeError(f"expected a boolean, got {unpacked!r}")
+    return Arguments(
+        tuple(denoted(value) for value in data["positional"]),
+        tuple((_string(name), denoted(value)) for name, value in data["keywords"]),
+        unpacked,
     )

coretrace_python/dependency/__init__.py

@@ -11,6 +11,8 @@ from coretrace_python.dependency.advisories import (
 from coretrace_python.dependency.graph import (
     DEPENDENCY_FILES,
     Advisory,
+    AdvisoryEntryPoint,
+    Condition,
     DependencyAnalysis,
     DependencyGraph,
     Requirement,
@@ -26,7 +28,9 @@ __all__ = [
     "DEPENDENCY_FILES",
     "POLICY_FILE",
     "Advisory",
+    "AdvisoryEntryPoint",
     "AdvisoryFileError",
+    "Condition",
     "DependencyAnalysis",
     "DependencyGraph",
     "Policy",

coretrace_python/dependency/advisories.py

@@ -5,8 +5,8 @@ OSV dump into ``Advisory`` values, keeping the PyPI ecosystem and turning each r
 events into a version specifier; ``dump_advisories`` writes them as a small JSON file
 that a project keeps at its root as ``advisories.json`` or passes with ``--advisories``.
 OSV records name no affected APIs, so imported advisories feed the requirement checks
-and the SBOM; a file completed by hand with ``affected_symbols`` also feeds the
-reachability and correlation checks.
+and the SBOM; a file completed by hand with ``affected_symbols``, ``entry_points`` and
+their ``conditions`` also feeds the reachability and correlation checks.
 """
 
 from __future__ import annotations
@@ -17,7 +17,7 @@ from collections.abc import Iterable, Iterator, Mapping
 from pathlib import Path
 from typing import Any
 
-from coretrace_python.dependency.graph import Advisory, normalize
+from coretrace_python.dependency.graph import Advisory, AdvisoryEntryPoint, Condition, normalize
 from coretrace_python.findings import Severity
 from coretrace_python.semantic.symbols import SymbolId
 
@@ -84,8 +84,9 @@ def import_osv(records: Iterable[Mapping[str, Any]]) -> tuple[Advisory, ...]:
             if str(package.get("ecosystem", "")).lower() != "pypi" or not package.get("name"):
                 continue
             name = normalize(str(package["name"]))
-            for specifier in _specifiers(affected.get("ranges") or []):
-                advisories.append(Advisory(identifier, name, specifier, summary, severity, (), aliases))
+            specifiers = _specifiers(affected.get("ranges") or [])
+            if specifiers:
+                advisories.append(Advisory(identifier, name, " || ".join(specifiers), summary, severity, (), aliases))
     return tuple(advisories)
 
 
@@ -137,6 +138,15 @@ def dump_advisories(advisories: Iterable[Advisory]) -> str:
                 "severity": a.severity.value,
                 "affected_symbols": [str(s) for s in a.affected_symbols],
                 "aliases": list(a.aliases),
+                "entry_points": [
+                    {
+                        "symbol": str(e.symbol),
+                        "justification": e.justification,
+                        "conditions": [_condition_entry(c) for c in e.conditions],
+                    }
+                    for e in a.entry_points
+                ],
+                "modules": list(a.modules),
             }
             for a in advisories
         ],
@@ -144,6 +154,19 @@ def dump_advisories(advisories: Iterable[Advisory]) -> str:
     return json.dumps(document, indent=2) + "\n"
 
 
+def _condition_entry(condition: Condition) -> dict[str, Any]:
+    entry: dict[str, Any] = {"kind": condition.kind, "text": condition.text}
+    if condition.argument is not None:
+        entry["argument"] = condition.argument
+    if condition.values:
+        entry["values"] = list(condition.values)
+    if condition.position is not None:
+        entry["position"] = condition.position
+    if condition.default:
+        entry["default"] = True
+    return entry
+
+
 def load_advisories(path: Path) -> tuple[Advisory, ...]:
     try:
         document = json.loads(path.read_text(encoding="utf-8"))
@@ -165,4 +188,31 @@ def _advisory(entry: Mapping[str, Any]) -> Advisory:
         Severity(entry["severity"]),
         tuple(SymbolId(str(s)) for s in entry.get("affected_symbols") or []),
         tuple(str(a) for a in entry.get("aliases") or []),
+        tuple(_entry_point(e) for e in entry.get("entry_points") or []),
+        tuple(str(m) for m in entry.get("modules") or []),
+    )
+
+
+def _entry_point(entry: Mapping[str, Any]) -> AdvisoryEntryPoint:
+    return AdvisoryEntryPoint(
+        SymbolId(str(entry["symbol"])),
+        str(entry["justification"]),
+        tuple(_condition(c) for c in entry.get("conditions") or []),
+    )
+
+
+def _condition(entry: Mapping[str, Any]) -> Condition:
+    position = entry.get("position")
+    if position is not None and (not isinstance(position, int) or isinstance(position, bool) or position < 0):
+        raise TypeError(f"condition position must be a non-negative integer, got {position!r}")
+    default = entry.get("default", False)
+    if not isinstance(default, bool):
+        raise TypeError(f"condition default must be true or false, got {default!r}")
+    return Condition(
+        str(entry["kind"]),
+        str(entry["text"]),
+        None if entry.get("argument") is None else str(entry["argument"]),
+        tuple(str(v) for v in entry.get("values") or []),
+        position,
+        default,
     )

coretrace_python/dependency/correlation.py

@@ -10,78 +10,172 @@ are correlated here into one high-confidence ``exploitable-vulnerability`` findi
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
 
-from coretrace_python.dependency.graph import Advisory, DependencyGraph
+from coretrace_python.dependency.graph import (
+    DIRECT,
+    Advisory,
+    AdvisoryEntryPoint,
+    Condition,
+    DependencyGraph,
+)
 from coretrace_python.findings import Confidence, Finding, Severity
-from coretrace_python.findings.refutation import Status, Verdicts
+from coretrace_python.findings.refutation import Status, Verdict, Verdicts
+from coretrace_python.interprocedural import Arguments, CallSite, ExternalSymbol
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.taint import Sink, TaintFlow, TaintKind
 
+Affected = Mapping[SymbolId, tuple[Advisory, ...]]
 
-def affected_symbols(
-    dependencies: DependencyGraph, advisories: Iterable[Advisory]
-) -> Mapping[SymbolId, Advisory]:
-    """The APIs affected by advisories whose package is required in a vulnerable version."""
 
-    affected: dict[SymbolId, Advisory] = {}
+def affected_symbols(dependencies: DependencyGraph, advisories: Iterable[Advisory]) -> Affected:
+    """The APIs affected by advisories whose package is required in a vulnerable version,
+    each with every such advisory: a call to ``yaml.load`` reaches every CVE of the
+    pinned release, not the first one listed."""
+
+    affected: dict[SymbolId, list[Advisory]] = {}
     for requirement in dependencies.requirements:
         for advisory in advisories:
             if advisory.affects(requirement):
-                for symbol in advisory.affected_symbols:
-                    affected.setdefault(symbol, advisory)
-    return affected
+                for symbol in advisory.reachable_symbols:
+                    found = affected.setdefault(symbol, [])
+                    if advisory not in found:
+                        found.append(advisory)
+    return {symbol: tuple(found) for symbol, found in affected.items()}
 
 
-def advisory_sinks(affected: Mapping[SymbolId, Advisory]) -> tuple[Sink, ...]:
+def advisory_sinks(affected: Affected) -> tuple[Sink, ...]:
     return tuple(Sink(symbol, TaintKind.ADVISORY) for symbol in affected)
 
 
+@dataclass(frozen=True)
+class ConditionCheck:
+    """What one call tells of an entry point's conditions: those it meets, those left to
+    review (every semantic one, and every argument one the call does not decide), and
+    the argument condition it contradicts with what it passes instead (None: absent),
+    in which case the call does not reach the vulnerability."""
+
+    met: tuple[Condition, ...] = ()
+    pending: tuple[Condition, ...] = ()
+    contradicted: Condition | None = None
+    passed: str | None = None
+
+
+def check_conditions(entry: AdvisoryEntryPoint | None, arguments: Arguments | None) -> ConditionCheck:
+    """Decide ``entry``'s conditions against what the call's ``arguments`` denote."""
+
+    if entry is None:
+        return ConditionCheck()
+    met: list[Condition] = []
+    pending: list[Condition] = []
+    for condition in entry.conditions:
+        given = _given(condition, arguments) if condition.checkable and arguments is not None else None
+        if given is None:
+            pending.append(condition)
+            continue
+        explicit, value = given
+        if explicit and value is None:
+            pending.append(condition)
+            continue
+        affected = value in condition.values if explicit else condition.default
+        if not affected:
+            return ConditionCheck(tuple(met), tuple(pending), condition, value)
+        met.append(condition)
+    return ConditionCheck(tuple(met), tuple(pending))
+
+
+def _given(condition: Condition, arguments: Arguments) -> tuple[bool, str | None] | None:
+    """Whether the call gives the condition's argument, and what it denotes: ``(True,
+    value)`` when given, ``(False, None)`` when surely absent, None when it cannot tell."""
+
+    for name, value in arguments.keywords:
+        if name == condition.argument:
+            return True, value
+    if condition.position is not None and condition.position < len(arguments.positional):
+        return True, arguments.positional[condition.position]
+    return None if arguments.unpacked else (False, None)
+
+
+def ruled_out(module: str, site: CallSite, check: ConditionCheck) -> str:
+    """Which call a contradicted condition rules out, and why: ``app:12
+    python.yaml.load(Loader=python.yaml.SafeLoader)``."""
+
+    assert check.contradicted is not None and isinstance(site.target, ExternalSymbol)
+    argument = check.contradicted.argument or f"#{check.contradicted.position}"
+    passed = f"{argument} absent" if check.passed is None else f"{argument}={check.passed}"
+    return f"{module}:{site.location.start_line} {site.target.symbol}({passed})"
+
+
+def evidence(advisory: Advisory, symbol: SymbolId, level: str, check: ConditionCheck) -> dict[str, str]:
+    """What a finding keeps of the advisory for ``symbol``: the level of evidence
+    established, how the symbol relates to the vulnerability, and its conditions — those
+    the call meets and those left to review."""
+
+    metadata = {"advisory": advisory.id, "package": advisory.package, "symbol": str(symbol), "level": level}
+    entry = advisory.entry_point(symbol)
+    if entry is None:
+        metadata["justification"] = DIRECT
+        return metadata
+    metadata["entry_point"] = str(entry.symbol)
+    metadata["justification"] = entry.justification
+    if entry.conditions:
+        metadata["conditions"] = "; ".join(c.text for c in entry.conditions)
+    if check.met:
+        metadata["conditions_met"] = "; ".join(c.text for c in check.met)
+    if check.pending:
+        metadata["conditions_pending_review"] = "; ".join(c.text for c in check.pending)
+    return metadata
+
+
 def correlate(
     function: str,
     flows: Iterable[TaintFlow],
     verdicts: Verdicts | None,
-    affected: Mapping[SymbolId, Advisory],
+    affected: Affected,
 ) -> tuple[Finding, ...]:
-    """Exploitable-vulnerability findings for the non-refuted ADVISORY flows of a function."""
+    """Exploitable-vulnerability findings for the non-refuted ADVISORY flows of a function,
+    one per advisory the sink is affected by."""
 
     findings: list[Finding] = []
     for flow in flows:
         if not flow.kinds & TaintKind.ADVISORY:
             continue
-        advisory = affected.get(flow.sink.symbol)
-        if advisory is None:
-            continue
         verdict = verdicts.verdict(flow) if verdicts is not None else None
         if verdict is not None and verdict.status is Status.REFUTED:
             continue
         hotspot = verdict is not None and verdict.status is Status.HOTSPOT
-        message = (
-            f"{advisory.id}: {flow.source.label} input reaches {flow.sink.symbol}, affected in "
-            f"the required {advisory.package} {advisory.vulnerable}: {advisory.summary}"
-        )
-        metadata = {
-            "advisory": advisory.id,
-            "package": advisory.package,
-            "symbol": str(flow.sink.symbol),
-            "source": str(flow.source.symbol),
-            "source_label": flow.source.label,
-            "verdict": "hotspot" if hotspot else "vulnerability",
-        }
-        if verdict is not None:
-            metadata["evidence"] = verdict.evidence
-        if flow.through is not None and flow.sink_location is not None:
-            message += f" through {flow.through}"
-            metadata["through"] = flow.through
-            metadata["sink_line"] = str(flow.sink_location.start_line)
-        findings.append(
-            Finding(
-                rule_id="exploitable-vulnerability",
-                message=message,
-                severity=Severity.CRITICAL,
-                confidence=Confidence.MEDIUM if hotspot else Confidence.HIGH,
-                span=flow.location,
-                function=function,
-                metadata=metadata,
-            )
-        )
+        for advisory in affected.get(flow.sink.symbol, ()):
+            check = check_conditions(advisory.entry_point(flow.sink.symbol), flow.sink_arguments)
+            if check.contradicted is None:
+                findings.append(_exploitable(function, flow, advisory, verdict, hotspot, check))
     return tuple(findings)
+
+
+def _exploitable(
+    function: str, flow: TaintFlow, advisory: Advisory, verdict: Verdict | None, hotspot: bool, check: ConditionCheck
+) -> Finding:
+    message = (
+        f"{advisory.id}: {flow.source.label} input reaches {flow.sink.symbol}, affected in "
+        f"the required {advisory.package} {advisory.vulnerable}: {advisory.summary}"
+    )
+    metadata = {
+        **evidence(advisory, flow.sink.symbol, "exploitable", check),
+        "source": str(flow.source.symbol),
+        "source_label": flow.source.label,
+        "verdict": "hotspot" if hotspot else "vulnerability",
+    }
+    if verdict is not None:
+        metadata["evidence"] = verdict.evidence
+    if flow.through is not None and flow.sink_location is not None:
+        message += f" through {flow.through}"
+        metadata["through"] = flow.through
+        metadata["sink_line"] = str(flow.sink_location.start_line)
+    return Finding(
+        rule_id="exploitable-vulnerability",
+        message=message,
+        severity=Severity.CRITICAL,
+        confidence=Confidence.MEDIUM if hotspot else Confidence.HIGH,
+        span=flow.location,
+        function=function,
+        metadata=metadata,
+    )