coretrace-python-analyzer 0.8.0__tar.gz → 0.10.0__tar.gz

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.10.0 (2026-09-25)
+
+### Reports
+
+- A directory check names what its result was produced with, besides the engine and the sources. It lists each plugin it loaded, by manifest name and version, and each advisory file it read, by path, each with the SHA-256 digest of its content. The formats show them in these places:
+  - JSON: `tool.components`;
+  - SARIF: `tool.extensions`;
+  - CycloneDX SBOM: `metadata.tools.components`, with their hashes;
+  - OpenVEX: the document's `tooling`, so its `@id` changes with the advisory data.
+
+  Every finding about an advisory names the plugin (`name@version`) or advisory file it comes from, in its `advisory_source` metadata. The cache key and the reports identify a plugin by the same digest (#149).
+
+## 0.9.0 (2026-09-25)
+
+### Precision
+
+- An advisory entry point may name the `attacker_arguments` through which attacker input exploits it: by keyword, and by position when the argument may be passed positionally, a variadic one taking every later position. Attacker input in another argument leaves the call reachable instead of exploitable, so an advisory for `send_from_directory` that names its `path` no longer counts `download_name=`, and one for `requests.get` that names its `url` no longer counts the body. An argument unpacked with `*` or `**` may fill any of them: like an argument condition it leaves undecided, it does not rule the call out, so a wrapper forwarding `*args, **kwargs` still reaches the entry point. An entry point naming no argument counts every argument, as before. Each taint flow now records how its value is passed to the sink (#145).
+
 ## 0.8.0 (2026-09-25)
 
 ### Precision

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.8.0
+Version: 0.10.0
 Summary: Static security analysis infrastructure for Python code
 Project-URL: Homepage, https://github.com/CoreTrace/coretrace-python-analyzer
 Project-URL: Repository, https://github.com/CoreTrace/coretrace-python-analyzer

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/docs/usage.md

@@ -239,7 +239,7 @@ the directory of the checked file; a path outside it is printed as it is.
 ```json
 {
   "schema_version": 1,
-  "tool": {"name": "coretrace-python-analyzer", "version": "0.8.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.10.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -261,10 +261,34 @@ the directory of the checked file; a path outside it is printed as it is.
 
 `root` is the directory the paths are relative to.
 
+A directory check also lists, in `tool.components`, what the result was produced with
+besides the engine and the sources: each plugin it loaded, by manifest name and version,
+and each advisory file it read, by path (relative to the root when under it). Each
+component carries the SHA-256 digest of its content, so a result can be traced to the
+exact advisory data it used and reproduced. A plugin's digest covers its directory as the
+cache fingerprints it, bytecode and hidden files left out; a file's digest covers its
+bytes. A single-file check lists no components.
+
+```json
+"tool": {
+  "name": "coretrace-python-analyzer", "version": "0.10.0",
+  "components": [
+    {"kind": "plugin", "name": "curated-advisories", "version": "2026.09.25", "digest": "sha256:…"},
+    {"kind": "advisories", "name": "advisories.json", "digest": "sha256:…"}
+  ]
+}
+```
+
+A finding about an advisory names, in its `advisory_source` metadata, where the advisory
+comes from. For a plugin this is `name@version`, and for an advisory file its path. When
+several sources define the same advisory, it names the one whose definition is used, as
+the next section describes.
+
 `--format sarif` prints a SARIF 2.1.0 log, one run with the tool, its rules and one
 result per finding. The root is declared once as the `SRCROOT` original URI base and
 every location under it is relative to that base, which is what code scanning services
-need to attach results to files:
+need to attach results to files. The components of a directory check are the tool's
+`extensions`, their kind and digest in `properties`:
 
 ```bash
 coretrace-python-analyzer --check src/ --format sarif > report.sarif
@@ -336,6 +360,19 @@ it is reachable, called or not — `request.form['name']`, `for key in request.f
 `request.form.get('name')` all read it. A function reading it several times is reported
 once, where it first reads it.
 
+Most vulnerabilities need attacker input in one argument: the path `send_from_directory`
+serves, not its `download_name`; the URL `requests.get` fetches, not its body. An entry
+point may name them in `attacker_arguments`, by keyword `argument` and, when it may be
+passed positionally, by `position`, counted as for argument conditions; `"variadic": true`
+extends a position to every later one, as `safe_join(directory, *pathnames)` takes
+(`{"position": 1, "variadic": true}`). A call is then exploitable only when attacker
+input reaches one of them, `"attacker_arguments": [{"argument": "url", "position": 0}]`
+for `requests.get`; attacker input in another argument leaves it reachable. An argument
+unpacked with `*args` or `**kwargs` may fill any of them: like an argument condition it
+leaves undecided, it does not rule the call out, so it counts, and a wrapper forwarding
+`*args, **kwargs` to the entry point still reaches it. An entry point without
+`attacker_arguments` is exploitable through any argument.
+
 An `argument` condition is decided at each call. It names the argument by keyword and,
 when it may be passed positionally, by `position` (counted from 0, the receiver of a
 method excluded); `values` are what makes the call affected, written as the analyzer
@@ -372,7 +409,9 @@ ignore = ["CVE-2020-1747"]
 ```
 
 `--sbom PATH` writes a CycloneDX 1.5 bill of materials: one component per requirement
-with its package URL, and the advisories affecting them as vulnerabilities.
+with its package URL, and the advisories affecting them as vulnerabilities. Its tools
+list the analyzer and the components of the check, each with its SHA-256 hash: a plugin
+as an `application`, an advisory file as `data`.
 
 ```bash
 coretrace-python-analyzer --check src/ --sbom sbom.json --policy security/policy.toml
@@ -394,7 +433,9 @@ not the code of installed packages. A framework calling the vulnerable function
 project's behalf would go unseen. Without a lock file, a package is never
 `not_affected`. The document's `@id` derives from its statements, so two runs with the
 same result share it; its `author` is `Unknown Author`, as OpenVEX tools write when they
-cannot know it.
+cannot know it. Its `tooling` names the analyzer and each component with its digest
+(`coretrace-python-analyzer 0.10.0; curated-advisories 2026.09.25 (sha256:…)`), so the
+`@id` changes with the advisory data a statement was decided with.
 
 ## Large projects
 

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coretrace-python-analyzer"
-version = "0.8.0"
+version = "0.10.0"
 description = "Static security analysis infrastructure for Python code"
 readme = "README.md"
 requires-python = ">=3.11"

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/__init__.py

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

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/cli.py

@@ -242,9 +242,12 @@ def main(argv: list[str] | None = None) -> int:
                 findings = analysis.findings
                 coverage = analysis.coverage
                 suppressed = analysis.suppressed
+                components = analysis.components
                 if args.sbom is not None:
                     args.sbom.write_text(
-                        render_sbom(analysis.dependencies, analysis.advisories, engine.TOOL_NAME, __version__),
+                        render_sbom(
+                            analysis.dependencies, analysis.advisories, engine.TOOL_NAME, __version__, analysis.components
+                        ),
                         encoding="utf-8",
                     )
                 if args.vex is not None:
@@ -258,6 +261,7 @@ def main(argv: list[str] | None = None) -> int:
                             engine.TOOL_NAME,
                             __version__,
                             datetime.now(UTC),
+                            analysis.components,
                         ),
                         encoding="utf-8",
                     )
@@ -265,6 +269,7 @@ def main(argv: list[str] | None = None) -> int:
                 file_analysis = engine.analyze_file(SourceManager().load_file(args.path), plugin_roots)
                 findings, coverage = file_analysis.findings, file_analysis.coverage
                 suppressed = file_analysis.suppressed
+                components = ()
             root = args.path.resolve() if args.path.is_dir() else args.path.resolve().parent
             baselined = None
             if args.baseline is not None:
@@ -273,7 +278,7 @@ def main(argv: list[str] | None = None) -> int:
                 else:
                     Baseline.of(findings, root).save(args.baseline)
                     findings, baselined = (), findings
-            report = engine.report(findings, coverage, root, suppressed, baselined)
+            report = engine.report(findings, coverage, root, suppressed, baselined, components)
             print(render(args.format or "text", report), end="")
             threshold = Severity(args.fail_on).rank if args.fail_on is not None else 0
             failing = any(finding.severity.rank >= threshold for finding in findings)

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/dependency/__init__.py

@@ -12,6 +12,7 @@ from coretrace_python.dependency.graph import (
     DEPENDENCY_FILES,
     Advisory,
     AdvisoryEntryPoint,
+    AttackerArgument,
     Condition,
     DependencyAnalysis,
     DependencyGraph,
@@ -31,6 +32,7 @@ __all__ = [
     "Advisory",
     "AdvisoryEntryPoint",
     "AdvisoryFileError",
+    "AttackerArgument",
     "Condition",
     "DependencyAnalysis",
     "DependencyGraph",

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/dependency/advisories.py

@@ -17,7 +17,13 @@ from collections.abc import Iterable, Iterator, Mapping
 from pathlib import Path
 from typing import Any
 
-from coretrace_python.dependency.graph import Advisory, AdvisoryEntryPoint, Condition, normalize
+from coretrace_python.dependency.graph import (
+    Advisory,
+    AdvisoryEntryPoint,
+    AttackerArgument,
+    Condition,
+    normalize,
+)
 from coretrace_python.findings import Severity
 from coretrace_python.semantic.symbols import SymbolId
 
@@ -155,6 +161,19 @@ def _entry_point_entry(entry_point: AdvisoryEntryPoint) -> dict[str, Any]:
     }
     if entry_point.read:
         entry["read"] = True
+    if entry_point.attacker_arguments:
+        entry["attacker_arguments"] = [_attacker_argument_entry(a) for a in entry_point.attacker_arguments]
+    return entry
+
+
+def _attacker_argument_entry(argument: AttackerArgument) -> dict[str, Any]:
+    entry: dict[str, Any] = {}
+    if argument.argument is not None:
+        entry["argument"] = argument.argument
+    if argument.position is not None:
+        entry["position"] = argument.position
+    if argument.variadic:
+        entry["variadic"] = True
     return entry
 
 
@@ -206,9 +225,25 @@ def _entry_point(entry: Mapping[str, Any]) -> AdvisoryEntryPoint:
         str(entry["justification"]),
         tuple(_condition(c) for c in entry.get("conditions") or []),
         read,
+        tuple(_attacker_argument(a) for a in entry.get("attacker_arguments") or []),
     )
 
 
+def _attacker_argument(entry: Mapping[str, Any]) -> AttackerArgument:
+    argument, position, variadic = entry.get("argument"), entry.get("position"), entry.get("variadic", False)
+    if argument is not None and not isinstance(argument, str):
+        raise TypeError(f"attacker argument name must be a string, got {argument!r}")
+    if position is not None and (not isinstance(position, int) or isinstance(position, bool) or position < 0):
+        raise TypeError(f"attacker argument position must be a non-negative integer, got {position!r}")
+    if not isinstance(variadic, bool):
+        raise TypeError(f"attacker argument variadic must be true or false, got {variadic!r}")
+    if argument is None and position is None:
+        raise ValueError("an attacker argument needs a name, a position or both")
+    if variadic and position is None:
+        raise ValueError("a variadic attacker argument needs the position it starts at")
+    return AttackerArgument(argument, position, variadic)
+
+
 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):

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/dependency/correlation.py

@@ -133,7 +133,10 @@ def correlate(
             continue
         hotspot = verdict is not None and verdict.status is Status.HOTSPOT
         for advisory in affected.get(flow.sink.symbol, ()):
-            check = check_conditions(advisory.entry_point(flow.sink.symbol), flow.sink_arguments)
+            entry = advisory.entry_point(flow.sink.symbol)
+            if entry is not None and not any(entry.exploitable_through(p, k) for p, k in flow.passed_as):
+                continue
+            check = check_conditions(entry, flow.sink_arguments)
             if check.contradicted is None:
                 findings.append(_exploitable(function, flow, advisory, verdict, hotspot, check))
     return tuple(findings)

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/dependency/graph.py

@@ -166,6 +166,31 @@ class Condition:
         return self.kind == "argument"
 
 
+@dataclass(frozen=True)
+class AttackerArgument:
+    """An argument of an entry point that must carry the attacker's input: passed by
+    keyword ``argument``, or at ``position`` (from 0, a method's receiver excluded) when it
+    may be passed positionally; a ``variadic`` one, such as ``*pathnames``, also takes every
+    later position."""
+
+    argument: str | None = None
+    position: int | None = None
+    variadic: bool = False
+
+    def receives(self, position: int | None, keyword: str | None) -> bool:
+        """Whether the argument passed at ``position`` or as ``keyword`` is this one. An
+        argument unpacked with ``*`` or ``**`` has neither and may fill this one: like an
+        argument condition it leaves undecided, it does not rule the call out, so it is."""
+
+        if keyword is not None:
+            return keyword == self.argument
+        if position is None:
+            return True
+        if self.position is None:
+            return False
+        return position == self.position or (self.variadic and position > self.position)
+
+
 @dataclass(frozen=True)
 class AdvisoryEntryPoint:
     """A public API through which a project reaches an affected symbol, justified by the
@@ -173,12 +198,20 @@ class AdvisoryEntryPoint:
 
     An entry point is reached by a call, or — when ``read`` is set, for an attribute whose
     getter runs the affected code, such as a lazily parsed request body — by any read of
-    it or of an attribute of it."""
+    it or of an attribute of it. When it names ``attacker_arguments``, attacker input
+    exploits it only through one of them; otherwise through any argument."""
 
     symbol: SymbolId
     justification: str
     conditions: tuple[Condition, ...] = ()
     read: bool = False
+    attacker_arguments: tuple[AttackerArgument, ...] = ()
+
+    def exploitable_through(self, position: int | None, keyword: str | None) -> bool:
+        """Whether attacker input in the argument at ``position`` or ``keyword`` can
+        exploit the vulnerability."""
+
+        return not self.attacker_arguments or any(a.receives(position, keyword) for a in self.attacker_arguments)
 
 
 DIRECT = "affected symbol, changed by the fix"

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/dependency/sbom.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Iterable
+from collections.abc import Iterable, Sequence
 
 from coretrace_python.dependency.graph import Advisory, DependencyGraph, Requirement
+from coretrace_python.findings import PLUGIN, Component
 
 SPEC_VERSION = "1.5"
 
@@ -33,8 +34,22 @@ def _component(requirement: Requirement) -> dict[str, object]:
     return component
 
 
+def _tool(component: Component) -> dict[str, object]:
+    """A plugin as an application, an advisory file as data, each with its SHA-256."""
+
+    tool: dict[str, object] = {"type": "application" if component.kind == PLUGIN else "data", "name": component.name}
+    if component.version is not None:
+        tool["version"] = component.version
+    tool["hashes"] = [{"alg": "SHA-256", "content": component.digest.removeprefix("sha256:")}]
+    return tool
+
+
 def render_sbom(
-    dependencies: DependencyGraph, advisories: Iterable[Advisory], tool_name: str, tool_version: str
+    dependencies: DependencyGraph,
+    advisories: Iterable[Advisory],
+    tool_name: str,
+    tool_version: str,
+    components: Sequence[Component] = (),
 ) -> str:
     """A CycloneDX JSON document: one component per requirement, and the advisories
     affecting them as vulnerabilities. Deterministic for a given graph."""
@@ -57,7 +72,12 @@ def render_sbom(
         "specVersion": SPEC_VERSION,
         "version": 1,
         "metadata": {
-            "tools": {"components": [{"type": "application", "name": tool_name, "version": tool_version}]}
+            "tools": {
+                "components": [
+                    {"type": "application", "name": tool_name, "version": tool_version},
+                    *(_tool(component) for component in components),
+                ]
+            }
         },
         "components": [_component(requirement) for requirement in requirements],
         "vulnerabilities": vulnerabilities,

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/dependency/vex.py

@@ -23,7 +23,7 @@ from urllib.parse import quote
 
 from coretrace_python.dependency.graph import Advisory, DependencyGraph, Requirement
 from coretrace_python.dependency.sbom import purl
-from coretrace_python.findings import Finding
+from coretrace_python.findings import Component, Finding
 from coretrace_python.findings.coverage import Coverage
 
 CONTEXT = "https://openvex.dev/ns/v0.2.0"
@@ -44,6 +44,7 @@ def render_vex(
     tool_name: str,
     tool_version: str,
     timestamp: datetime,
+    components: Sequence[Component] = (),
 ) -> str:
     """The OpenVEX document of the project at ``root``. ``evidence`` is every finding of
     the check, those suppressed or accepted by the policy included. The document's
@@ -69,7 +70,12 @@ def render_vex(
                         **_status(advisory, requirement, about, dependencies, coverage, root),
                     }
                 )
-    tooling = f"{tool_name} {tool_version}"
+    tooling = "; ".join(
+        (
+            f"{tool_name} {tool_version}",
+            *(" ".join(filter(None, (c.name, c.version, f"({c.digest})"))) for c in components),
+        )
+    )
     content = {
         "@context": CONTEXT,
         "author": AUTHOR,

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/engine.py

@@ -7,9 +7,10 @@ plugins and analyses never import it.
 from __future__ import annotations
 
 import concurrent.futures
+import hashlib
 import multiprocessing
 from collections.abc import Callable, Iterable, Mapping, Sequence
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 from types import MappingProxyType
 from typing import Any, ClassVar
@@ -55,7 +56,10 @@ from coretrace_python.dependency.correlation import (
     correlate,
 )
 from coretrace_python.findings import (
+    ADVISORIES,
     FINDING_SCHEMA_VERSION,
+    PLUGIN,
+    Component,
     Confidence,
     Coverage,
     FileCoverage,
@@ -217,6 +221,8 @@ class ProjectAnalysis:
     suppressed: tuple[Finding, ...] = ()
     # Findings about an advisory the policy accepts, still evidence of what is reached.
     accepted: tuple[Finding, ...] = ()
+    # The plugins and advisory files the result was produced with.
+    components: tuple[Component, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -358,10 +364,10 @@ def analyze_project(
     for error in dependencies.errors:
         findings.append(_note("syntax-error", error, sources.add_source(error.split(":")[0], ""), 1))
     advisory_paths = _advisory_paths(root, advisory_files)
-    file_advisories: list[Advisory] = []
+    file_advisories: list[tuple[Path, tuple[Advisory, ...]]] = []
     for path in advisory_paths:
         try:
-            file_advisories.extend(load_advisories(path))
+            file_advisories.append((path, load_advisories(path)))
         except AdvisoryFileError as error:
             findings.append(_note("syntax-error", str(error), sources.add_source(str(path), ""), 1))
     policy = Policy()
@@ -392,9 +398,8 @@ def analyze_project(
     probe = next(iter(managers.values()), None) or _register_all(build_hir(sources.add_source("<empty>", "")))
     registry = load_plugins(plugin_roots, probe)
     all_plugins: tuple[Plugin, ...] = (*(loaded.plugin for loaded in registry), *plugins)
-    advisories = _merge_advisories(
-        (a for plugin in all_plugins for a in plugin.advisories), file_advisories
-    )
+    components = _components(registry, root, (path for path, _ in file_advisories))
+    advisories, origins = _merge_advisories(_contributions(registry, plugins, root, file_advisories))
     affected = affected_symbols(dependencies, advisories)
     models = plugin_models(all_plugins, root).extended(*advisory_sinks(affected))
     for manager in managers.values():
@@ -425,7 +430,7 @@ def analyze_project(
         manager.provide(EscapedTemplates, escaped)
         manager.provide(ClearingAnalysis, clearing)
 
-    configuration = _configuration_key(registry, plugins, models, advisories, dependencies, routes, escaped)
+    configuration = _configuration_key(components, plugins, models, advisories, dependencies, routes, escaped)
     keys = module_keys(
         graph,
         {name: fingerprint(configuration, str(files[name].source_id), name, files[name].text) for name in analysable},
@@ -511,6 +516,7 @@ def analyze_project(
     for plugin in all_plugins:
         if isinstance(plugin, ProjectPlugin):
             findings = list(apply_refinement(plugin, findings, plugin.refine(context, tuple(findings))))
+    findings = [_sourced(finding, origins) for finding in findings]
     accepted = tuple(f for f in findings if policy.accepts(f))
     kept, suppressed = partition(apply_policy(policy, findings), _text_of(sources))
     return ProjectAnalysis(
@@ -524,20 +530,78 @@ def analyze_project(
         Coverage(tuple(sorted(coverage, key=lambda c: c.path))),
         suppressed,
         accepted,
+        components,
+    )
+
+
+Origins = Mapping[tuple[str, str], str]
+
+
+def _merge_advisories(contributions: Iterable[tuple[str, Iterable[Advisory]]]) -> tuple[tuple[Advisory, ...], Origins]:
+    """One advisory per identifier and package, with the contributor it comes from: a
+    later contributor replaces an earlier one, so a curated plugin refines a bundled
+    sample and a local file, the project's own feed, wins over every plugin."""
+
+    merged: dict[tuple[str, str], tuple[str, Advisory]] = {}
+    for source, advisories in contributions:
+        for advisory in advisories:
+            merged[(advisory.id, advisory.package)] = (source, advisory)
+    return (
+        tuple(advisory for _, advisory in merged.values()),
+        MappingProxyType({key: source for key, (source, _) in merged.items()}),
     )
 
 
-def _merge_advisories(
-    from_plugins: Iterable[Advisory], from_files: Iterable[Advisory]
-) -> tuple[Advisory, ...]:
-    """One advisory per identifier and package: a later contributor replaces an earlier
-    one, so a curated plugin refines a bundled sample and a local file, the project's
-    own feed, wins over every plugin."""
+def _contributions(
+    registry: PluginRegistry,
+    plugins: Sequence[Plugin],
+    root: Path,
+    files: Iterable[tuple[Path, tuple[Advisory, ...]]],
+) -> list[tuple[str, Iterable[Advisory]]]:
+    """The advisories of each plugin, then of each advisory file, each under the name a
+    finding cites it by: ``name@version`` for a loaded plugin, the path for a file."""
+
+    return [
+        *((f"{loaded.manifest.name}@{loaded.manifest.version}", loaded.plugin.advisories) for loaded in registry),
+        *((plugin.name, plugin.advisories) for plugin in plugins),
+        *((_located(path, root), advisories) for path, advisories in files),
+    ]
 
-    merged: dict[tuple[str, str], Advisory] = {}
-    for advisory in (*from_plugins, *from_files):
-        merged[(advisory.id, advisory.package)] = advisory
-    return tuple(merged.values())
+
+def _components(registry: PluginRegistry, root: Path, files: Iterable[Path]) -> tuple[Component, ...]:
+    """The plugins and advisory files a project result is produced with, each with the
+    digest of its content: the plugin directory as the cache fingerprints it, the file's
+    bytes."""
+
+    return (
+        *(
+            Component(PLUGIN, loaded.manifest.name, f"sha256:{directory_fingerprint(loaded.directory)}", loaded.manifest.version)
+            for loaded in registry
+        ),
+        *(
+            Component(ADVISORIES, _located(path, root), f"sha256:{hashlib.sha256(path.read_bytes()).hexdigest()}")
+            for path in files
+        ),
+    )
+
+
+def _located(path: Path, root: Path) -> str:
+    """``path`` relative to ``root``, POSIX style, when it lies under it."""
+
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _sourced(finding: Finding, origins: Origins) -> Finding:
+    """``finding`` with the plugin or advisory file its advisory comes from, when it
+    cites one."""
+
+    origin = origins.get((finding.metadata.get("advisory", ""), finding.metadata.get("package", "")))
+    if origin is None:
+        return finding
+    return replace(finding, metadata={**finding.metadata, "advisory_source": origin})
 
 
 def _advisory_paths(root: Path, advisory_files: Sequence[Path]) -> tuple[Path, ...]:
@@ -623,15 +687,13 @@ def _analyse_batch(batch: _Batch) -> dict[str, dict[str, Any]]:
     registry = load_plugins(batch.plugin_roots, next(iter(managers.values())))
     all_plugins: tuple[Plugin, ...] = (*(loaded.plugin for loaded in registry), *batch.plugins)
     dependencies = resolve_dependencies(batch.root, sources)
-    file_advisories: list[Advisory] = []
+    file_advisories: list[tuple[Path, tuple[Advisory, ...]]] = []
     for path in batch.advisory_paths:
         try:
-            file_advisories.extend(load_advisories(path))
+            file_advisories.append((path, load_advisories(path)))
         except AdvisoryFileError:
             continue
-    advisories = _merge_advisories(
-        (a for plugin in all_plugins for a in plugin.advisories), file_advisories
-    )
+    advisories, _ = _merge_advisories(_contributions(registry, batch.plugins, batch.root, file_advisories))
     affected = affected_symbols(dependencies, advisories)
     models = plugin_models(all_plugins, batch.root).extended(*advisory_sinks(affected))
     routes = _decode_routes(batch.routes)
@@ -663,7 +725,7 @@ def _decode_routes(data: tuple[tuple[str, str, str, int], ...]) -> dict[SymbolId
 
 
 def _configuration_key(
-    registry: PluginRegistry,
+    components: Sequence[Component],
     plugins: Sequence[Plugin],
     models: ModelTable,
     advisories: tuple[Advisory, ...],
@@ -679,10 +741,7 @@ def _configuration_key(
         str(PYIR_SCHEMA_VERSION),
         str(FINDING_SCHEMA_VERSION),
         str(PLUGIN_API_VERSION),
-        *(
-            f"{loaded.manifest.name}={loaded.manifest.version}:{directory_fingerprint(loaded.directory)}"
-            for loaded in registry
-        ),
+        *(f"{c.name}={c.version}:{c.digest}" for c in components if c.kind == PLUGIN),
         *(f"{type(p).__module__}.{type(p).__qualname__}" for p in plugins),
         repr(models),
         repr(advisories),
@@ -776,6 +835,7 @@ def report(
     root: Path | None = None,
     suppressed: Sequence[Finding] = (),
     baselined: Sequence[Finding] | None = None,
+    components: Sequence[Component] = (),
 ) -> Report:
     """The report of a check; paths under ``root`` are rendered relative to it.
     ``baselined`` is the findings a baseline accounts for, ``None`` when none applied."""
@@ -789,4 +849,5 @@ def report(
         tuple(suppressed),
         tuple(baselined or ()),
         baselined is not None,
+        tuple(components),
     )

{coretrace_python_analyzer-0.8.0 → coretrace_python_analyzer-0.10.0}/src/coretrace_python/findings/__init__.py

@@ -2,9 +2,13 @@
 
 from coretrace_python.findings.coverage import Coverage, FileCoverage
 from coretrace_python.findings.model import FINDING_SCHEMA_VERSION, Confidence, Finding, Severity
+from coretrace_python.findings.provenance import ADVISORIES, PLUGIN, Component
 
 __all__ = [
+    "ADVISORIES",
     "FINDING_SCHEMA_VERSION",
+    "PLUGIN",
+    "Component",
     "Confidence",
     "Coverage",
     "FileCoverage",

coretrace_python_analyzer-0.10.0/src/coretrace_python/findings/provenance.py

@@ -0,0 +1,26 @@
+"""What a result was produced with, besides the engine and the analysed sources.
+
+Advisories decide the dependency findings and the VEX statements, and they come from
+plugins and advisory files that change on their own schedule. A report names each of
+them with the digest of its content, so a result can be traced to its data and
+reproduced.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+PLUGIN = "plugin"
+ADVISORIES = "advisories"
+
+
+@dataclass(frozen=True)
+class Component:
+    """A loaded plugin, by its manifest ``name`` and ``version``, or an advisory file, by
+    its path as ``name``. ``digest`` is ``sha256:`` and the hex digest of its content:
+    the plugin directory as the cache fingerprints it, or the file's bytes."""
+
+    kind: str
+    name: str
+    digest: str
+    version: str | None = None