coretrace-python-analyzer 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

coretrace_python/__init__.py

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

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/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/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/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/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/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/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/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/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/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

coretrace_python/reporters/json_format.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 
-from coretrace_python.findings import FINDING_SCHEMA_VERSION, Finding
+from coretrace_python.findings import FINDING_SCHEMA_VERSION, Component, Finding
 from coretrace_python.reporters.report import Report
 
 
@@ -28,11 +28,21 @@ def finding_record(finding: Finding, report: Report | None = None) -> dict[str,
     }
 
 
+def component_record(component: Component) -> dict[str, str]:
+    """A plugin or advisory file the result was produced with; a file has no version."""
+
+    record = {"kind": component.kind, "name": component.name}
+    if component.version is not None:
+        record["version"] = component.version
+    record["digest"] = component.digest
+    return record
+
+
 def render_json(report: Report) -> str:
-    document: dict[str, object] = {
-        "schema_version": FINDING_SCHEMA_VERSION,
-        "tool": {"name": report.tool_name, "version": report.tool_version},
-    }
+    tool: dict[str, object] = {"name": report.tool_name, "version": report.tool_version}
+    if report.components:
+        tool["components"] = [component_record(component) for component in report.components]
+    document: dict[str, object] = {"schema_version": FINDING_SCHEMA_VERSION, "tool": tool}
     if report.root is not None:
         document["root"] = str(report.root)
     document["findings"] = [finding_record(finding, report) for finding in report.findings]

coretrace_python/reporters/report.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 
-from coretrace_python.findings import Coverage, Finding
+from coretrace_python.findings import Component, Coverage, Finding
 
 
 def _order(finding: Finding) -> tuple[str, int, int, str]:
@@ -27,6 +27,8 @@ class Report:
     baselined: tuple[Finding, ...] = ()
     # Whether a baseline was applied, so new findings can be marked as such.
     with_baseline: bool = False
+    # The plugins and advisory files the result was produced with.
+    components: tuple[Component, ...] = ()
 
     def __post_init__(self) -> None:
         for name in ("findings", "suppressed", "baselined"):

coretrace_python/reporters/sarif.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 
-from coretrace_python.findings import Finding, Severity
+from coretrace_python.findings import Component, Finding, Severity
 from coretrace_python.reporters.report import Report
 
 SARIF_VERSION = "2.1.0"
@@ -59,6 +59,16 @@ def _result(
     return result
 
 
+def _extension(component: Component) -> dict[str, object]:
+    """A plugin or advisory file as a SARIF tool extension, its kind and digest as properties."""
+
+    extension: dict[str, object] = {"name": component.name}
+    if component.version is not None:
+        extension["version"] = component.version
+    extension["properties"] = {"kind": component.kind, "digest": component.digest}
+    return extension
+
+
 def render_sarif(report: Report) -> str:
     rule_ids: list[str] = []
     for finding in (*report.findings, *report.suppressed, *report.baselined):
@@ -78,7 +88,8 @@ def render_sarif(report: Report) -> str:
                             {"id": rule_id, "shortDescription": {"text": rule_id}}
                             for rule_id in rule_ids
                         ],
-                    }
+                    },
+                    **({"extensions": [_extension(c) for c in report.components]} if report.components else {}),
                 },
             "results": [
                 *(_result(report, f, rule_ids.index(f.rule_id), False, new) for f in report.findings),

coretrace_python/taint/engine.py

@@ -9,7 +9,7 @@ argument reaching a sink whose kinds it still carries is reported as a ``TaintFl
 
 from __future__ import annotations
 
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, replace
 from types import MappingProxyType
 from typing import ClassVar
@@ -119,6 +119,9 @@ class TaintFlow:
     sink_location: SourceSpan | None = None
     # What the arguments of the sink call denote, to decide the conditions on them.
     sink_arguments: Arguments | None = None
+    # How the tainted value is passed to the sink call: at a position, by a keyword, or
+    # (None, None) unpacked with ``*`` or ``**``; ``f(x, key=x)`` passes it twice.
+    passed_as: frozenset[tuple[int | None, str | None]] = frozenset()
 
 
 Key = Value | HeapLocation
@@ -559,6 +562,7 @@ class _TaintProblem(DataflowProblem[State]):
                     through,
                     call.location if sink_location is None else sink_location,
                     arguments,
+                    frozenset({(position, keyword)}),
                 )
             )
 
@@ -819,7 +823,18 @@ def propagate_taint(
             state, found = problem.evaluate(block, solution.incoming(block.id))
             taints.update(state)
             flows.extend(found)
-    return TaintFacts(taints, tuple(dict.fromkeys(flows)))
+    return TaintFacts(taints, _merged(flows))
+
+
+def _merged(flows: Iterable[TaintFlow]) -> tuple[TaintFlow, ...]:
+    """One flow per source, sink, kinds and tainted value, however many arguments of the
+    sink call it is passed as."""
+
+    passed: dict[TaintFlow, frozenset[tuple[int | None, str | None]]] = {}
+    for flow in flows:
+        key = replace(flow, passed_as=frozenset())
+        passed[key] = passed.get(key, frozenset()) | flow.passed_as
+    return tuple(replace(flow, passed_as=ways) for flow, ways in passed.items())
 
 
 class TaintAnalysis(FunctionAnalysis[TaintFacts]):

{coretrace_python_analyzer-0.8.0.dist-info → coretrace_python_analyzer-0.10.0.dist-info}/METADATA

@@ -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.dist-info → coretrace_python_analyzer-0.10.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
-coretrace_python/__init__.py,sha256=u9j9n2ZvaBeVUS33TRJ3MIoLUWwaBdpCAainRMXI4ok,75
+coretrace_python/__init__.py,sha256=dpPkJxTU8YFTQytkIzuK1AwDQYRpHrAJPKFeSC3Beps,76
 coretrace_python/__main__.py,sha256=V8DnYtRboISK2VCKm7DGHLREKvqLbqApyWlKBOs26wU,65
 coretrace_python/cache.py,sha256=-pZv-ELm4jMCTXQWSZIobHaT9UHIjFu7IlMkOM0i4LI,13607
-coretrace_python/cli.py,sha256=86rTb3Kcezwk9DBTRg-G3G38ypx8zH4lZbCR467xvpE,11008
-coretrace_python/engine.py,sha256=VWTUTgm9k0DrPYhYrgJQHzXi_L00pxnH8fGfo8insMc,29340
+coretrace_python/cli.py,sha256=G5jhb6g6RgSRSjjS7DBgziIjUM1vTFwalJGvFHVKxrg,11225
+coretrace_python/engine.py,sha256=-E4z-HvKffI0WMUXPKdQxm61anu-r-cYXHGqnppalYk,31953
 coretrace_python/abstract/__init__.py,sha256=n5FNkV8Z4LmwG0r06KWdLj4N2CPSgAKwY3896tdmRgM,999
 coretrace_python/abstract/constants.py,sha256=z4-e7IzysxzGi58wFFff1MlEoV8l7AZsB9EL-q6b7vY,9071
 coretrace_python/abstract/heap.py,sha256=OaESXFGC0qzyhAr76xrCu4skeDVzZM4wlenQqfMTkdk,9642
@@ -88,17 +88,18 @@ coretrace_python/cfg/model.py,sha256=6EJiXFAGrsMgCdyxMJ6TClY8tQhJF6Hq2bX802Gc0yg
 coretrace_python/dataflow/__init__.py,sha256=N5uY8VTNjEk6-ARCgDkxr6uGqQIz2NbF-U9sC_v_lfA,547
 coretrace_python/dataflow/lattice.py,sha256=HgYGVcKVUlexvEc0yT47aQCudLxU_SWLpHhr17igkiE,1929
 coretrace_python/dataflow/solver.py,sha256=iDsW0wujhM2DXplu2JMKC46BRsroXlNETHPEoikPeG4,3475
-coretrace_python/dependency/__init__.py,sha256=CXE36X2d5rio90NWlpjLo8Hly-tmzDCvu05FZAj_WXQ,1138
-coretrace_python/dependency/advisories.py,sha256=tfR-5BmjV4GYcsF3CSGA4jSXNwOVG6mS8AqPfy2fWms,8653
-coretrace_python/dependency/correlation.py,sha256=pR9S0tcdumdk2DMfUXxz6Wdul_RZE8FBfVmCUEhcA7w,7231
-coretrace_python/dependency/graph.py,sha256=6UpAsqbtr5EoVGp6qkaQ7Gi1iUbGtulyh0hfpK_RqLg,16875
+coretrace_python/dependency/__init__.py,sha256=BxkxnNwIEpAYtwbshCQovG-YXJ80QbwyzkmyJdbgsVg,1184
+coretrace_python/dependency/advisories.py,sha256=zti7MrojcfxfYWJuGpyLXXJU3pffpT4SJnQUa_g34Lw,10274
+coretrace_python/dependency/correlation.py,sha256=GLtrMn5yYr4NcKYNYZTqIFpwoXOrgsqI9t6lggXxFbg,7388
+coretrace_python/dependency/graph.py,sha256=HtvKeWWG9cy9TzJQ7lYMGPfHjPBxoSVgwzoj71SegaE,18445
 coretrace_python/dependency/policy.py,sha256=bsxZXL9xC0jnAzkzDh6ncnW8oKLG2H13jYmXF_q99Ng,2454
-coretrace_python/dependency/sbom.py,sha256=h4K3Gb9O_D6uZyfpwpC5rPcNjH_Ib-3uvFxix6OKlfs,2520
-coretrace_python/dependency/vex.py,sha256=ZPASwL6Var269WifrU7g1NRlDf-jxKKs8LzMo8dUkxI,7237
-coretrace_python/findings/__init__.py,sha256=gnJI-uB2CkgZ8I5aFYP_N5yZb7FGNIy7LirVDh4NLwo,372
+coretrace_python/dependency/sbom.py,sha256=rzJ-t0Mwoghej8nk0N63Dpjr_wYXm6JzuOPXjD8Kqs4,3234
+coretrace_python/dependency/vex.py,sha256=YddBuXsv7UgEnHdM9Jfjpo_A700IuIqRMjQz7AHSLX4,7437
+coretrace_python/findings/__init__.py,sha256=yFKXSFEsAnFSxF1E_ptF2OH4YlUcCaSeIlWSvqMgaHo,500
 coretrace_python/findings/baseline.py,sha256=fbGQuULRsCjhxSNdwuLfwsvql9ZUfF3jqCXrRmIgOoQ,3468
 coretrace_python/findings/coverage.py,sha256=U8URLEz6EN4B_TTQlLFCOtEmUbINt7a0Bexb-6OUFlI,1203
 coretrace_python/findings/model.py,sha256=zRK1FDuLgiVY4ch6H_AN9rDxC1orNW4wc8YN3cfVFfc,1424
+coretrace_python/findings/provenance.py,sha256=vP3nbyDPMlRlxVcVlurF0mSGNuxO3B7kzDDDd_BVws0,838
 coretrace_python/findings/refutation.py,sha256=UeYCz70LwyL8AMimhs3ys9cH0j1_YbdHVu7y3VvmmUg,22026
 coretrace_python/findings/suppressions.py,sha256=kN4q0CA1tzeAubeYe4rUv_aRXda4PAsMZY0r8M5cuQI,2633
 coretrace_python/frontend/__init__.py,sha256=ULI2tf_IRTMboaKM6uzTkGGh4Agy3cFjtw2H1IPrz4g,627
@@ -125,9 +126,9 @@ coretrace_python/plugins/manifest.py,sha256=F24pgQSwApRUL6ZihRSLv9wL_M03A_pZjrj9
 coretrace_python/plugins/registry.py,sha256=ixKcT2YDky96TWCFckdzKnGRmFn1dbBVMSZLPvdxvY8,1177
 coretrace_python/plugins/secrets.py,sha256=fpCxXpz3u7a-p1mAabC99FK_DpC1RSg62lLPe96pGy8,15162
 coretrace_python/reporters/__init__.py,sha256=MHTEfIj5q1KvFeIm6aAzt4mwL8oCZMkpYlaAGaq_cdo,764
-coretrace_python/reporters/json_format.py,sha256=-eP6feOYFjJFVbP98-hxRZTK8m4OYYvtohdPie88Jx0,2198
-coretrace_python/reporters/report.py,sha256=fUlxvxbyZYherJpU7Kl9v55i0Opoipc80dNDMDMIf-w,1656
-coretrace_python/reporters/sarif.py,sha256=CfHfe9hTC9gzW408z-k3qbs0nB695gInqQs1Cxxu7Ow,3113
+coretrace_python/reporters/json_format.py,sha256=x1XRw6UOOX624LRw2rJFiZDBbIX-LVzQ0SqHwG4BdAw,2699
+coretrace_python/reporters/report.py,sha256=hEQPDtnEgDF0djXfg74vBM1B0uajZ_AWtNtu3eH7QI4,1777
+coretrace_python/reporters/sarif.py,sha256=0HF47hZ6F2WtrDDb2uICLPqYI0gLRiUgxBX69C5lbnU,3649
 coretrace_python/reporters/text.py,sha256=bHsHkMheyL0AB1iWtxBO5H9S14k1AqJvKkNsFro71xo,1043
 coretrace_python/semantic/__init__.py,sha256=_tjT9CgXfPbOMs8EFguhWrLeSmpyrqOHU_OSoQPiWYs,411
 coretrace_python/semantic/identity.py,sha256=uQBdqEXrOtYmGIiR9hZu0Pimv52iW1rOOOvIdG0InNY,1472
@@ -138,13 +139,13 @@ coretrace_python/source/__init__.py,sha256=0Y8fvtbkETnNCJR9Zq7RS5TSgF9c22pz3SSk1
 coretrace_python/source/manager.py,sha256=JRmMOcWfS1nocbVrdcvfQTqEfIkmnb5JP857TpGywN4,2736
 coretrace_python/source/model.py,sha256=FZnN5mlir3tzbIpWoxnn6YtRi9UcJ_y0sZM60tKr8U4,1727
 coretrace_python/taint/__init__.py,sha256=kfqCEXE5wKFLwz2XrT42_yEv9pW4vPfgg5yYBVVSr2I,1371
-coretrace_python/taint/engine.py,sha256=lB6ysdzYNuYhIiRUaxfI4F3cAnaUK55d4lF9AzPWfrU,39742
+coretrace_python/taint/engine.py,sha256=_uVUc2m29aljN_YR2iCQtEdvZFc-LJ5CDWiZF1Tz3WU,40524
 coretrace_python/taint/models.py,sha256=B84caPxmQvTdB9H_80nZOqcFlpNd9ofpKI2YL5Uc0UA,15269
 coretrace_python/taint/routes.py,sha256=UAJKXcw_sM9shf58FfDroxVO9bNSm4qrQdZknwUB0lo,6110
 coretrace_python/taint/templates.py,sha256=8Ojb43VXuWxOVifeXRpi3_2mjZfnvIC7GQ-AW80GUYk,11148
-coretrace_python_analyzer-0.8.0.dist-info/METADATA,sha256=6iUDBdRu9mMtAf4EaeD4sVOr4iEdxzT7tkfOBlaNNT8,3216
-coretrace_python_analyzer-0.8.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-coretrace_python_analyzer-0.8.0.dist-info/entry_points.txt,sha256=wdozemiraOkbt65g_Y_zgspuZpoLxJdaCVMJt1Ft3c0,72
-coretrace_python_analyzer-0.8.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-coretrace_python_analyzer-0.8.0.dist-info/licenses/NOTICE,sha256=s3VHj5ngV0ozjW_kZJpg_35ne6JwoBK0ysOjbqVtA0w,113
-coretrace_python_analyzer-0.8.0.dist-info/RECORD,,
+coretrace_python_analyzer-0.10.0.dist-info/METADATA,sha256=g7Y7gs7Dsb2oZY33Iz2_aG6SQNI6KLkWuwtpcfij1i4,3217
+coretrace_python_analyzer-0.10.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+coretrace_python_analyzer-0.10.0.dist-info/entry_points.txt,sha256=wdozemiraOkbt65g_Y_zgspuZpoLxJdaCVMJt1Ft3c0,72
+coretrace_python_analyzer-0.10.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+coretrace_python_analyzer-0.10.0.dist-info/licenses/NOTICE,sha256=s3VHj5ngV0ozjW_kZJpg_35ne6JwoBK0ysOjbqVtA0w,113
+coretrace_python_analyzer-0.10.0.dist-info/RECORD,,