PyPI - coretrace-python-analyzer - Versions diffs - 0.3.0__tar.gz → 0.4.0__tar.gz - Mend

coretrace-python-analyzer 0.3.0tar.gz → 0.4.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (256) hide show

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/CHANGELOG.md RENAMED Viewed

@@ -1,5 +1,23 @@
 # Changelog
+## 0.4.0 (2026-09-24)
+### Analysis
+- The module body and the bodies of top-level classes are analysed as the functions `<module>` and `Cls.<body>`: their calls are call sites, their values carry taint, and an advisory entry point called at import time or in a class body is reachable. Coverage counts them; the cache format is bumped so cached results gain their findings (#113).
+### Dependencies
+- Advisories distinguish the `affected_symbols` a fix changed from the public `entry_points` through which they are reached, each justified and carrying `conditions` (checkable argument values, or `semantic` ones kept as pending review); `modules` names what the package installs. Every dependency finding records its evidence `level`: `declared`, `imported`, `reachable` or `exploitable` (#109).
+- A call to an API affected by several advisories of the pinned release reports every one of them, not the first listed (#109).
+- One advisory per identifier and package: a later contributor replaces an earlier one, so a curated feed refines the bundled sample, and the sample names the modules its packages install (#109).
+- A version specifier may be a union of ranges separated by `||`, as an advisory over several release series needs (`>=4.2,<4.2.28 || >=5.2,<5.2.11`); the OSV import produces one such advisory per package instead of one per range (#112).
+### Plugins
+- Every plugin module is registered in `sys.modules` before it runs, so a single-file plugin may define a dataclass under `from __future__ import annotations` (#105).
+- `ProjectPlugin.refine(ctx, findings)` lets a project plugin reclassify the findings of a run: severity, confidence and added metadata only, with `refined_by` and the original values recorded; anything else raises `RefinementError` (#106).
 ## 0.3.0 (2026-09-22)
 ### Plugins

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coretrace-python-analyzer
-Version: 0.3.0
+Version: 0.4.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.3.0 → coretrace_python_analyzer-0.4.0}/docs/plugins.md RENAMED Viewed

@@ -162,6 +162,38 @@ symbols, as the shipped `sample-advisories` plugin does. Requirements matching t
 reported, calls to the affected symbols become reachable vulnerabilities and tainted
 calls become exploitable ones.
+### Reclassifying findings: `ProjectPlugin.refine`
+A project plugin may also implement `refine(ctx, findings)`, called once with every
+finding of the run after all plugins have reported. It returns the same findings, in
+the same order, and may only change their `severity` and `confidence` or add metadata:
+the rule, the location, the message and the evidence a finding already carries are not
+the refiner's to touch, and the engine rejects a refinement that changes or drops any
+of them with a `RefinementError`. A reclassified finding records `refined_by` and the
+`original_severity` or `original_confidence` it had, so a report always shows what the
+detector said and who changed it.
+```python
+from dataclasses import replace
+from coretrace_python.findings import Confidence
+from coretrace_python.plugins import ProjectContext, ProjectPlugin
+class InternalOnly(ProjectPlugin):
+    name = "internal-only"
+    def analyze_project(self, ctx: ProjectContext):
+        return ()
+    def refine(self, ctx: ProjectContext, findings):
+        return tuple(
+            replace(f, confidence=Confidence.LOW, metadata={**f.metadata, "exposure": "internal"})
+            if f.function in INTERNAL else f
+            for f in findings
+        )
+```
 ### Secret scanners: `SecretDetector`
 Judges every string literal of the module, or every value of a configuration file,

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/docs/usage.md RENAMED Viewed

@@ -71,7 +71,10 @@ its package (`app/views.py` is `app.views`). Hidden directories, `node_modules`,
 dependency graph. Configuration files under the root (`.env`, YAML, TOML, JSON, INI,
 properties) are scanned for secrets.
-Functions and methods are analysed; module-level statements outside functions are not.
+Functions and methods are analysed, and so are the module body and the bodies of
+top-level classes, as the functions `<module>` and `Cls.<body>`: `application =
+get_asgi_application()` in `asgi.py` or `email = forms.EmailField()` in a form class are
+calls the analyzer sees, and a module-level `os.system(input())` is a finding in `<module>`.
 A function using syntax outside the supported subset is reported as an
 `unsupported-syntax` note and the other functions are still analysed; a file Python
 itself cannot parse is reported as a `syntax-error`. The coverage line and the JSON
@@ -198,7 +201,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.3.0"},
+  "tool": {"name": "coretrace-python-analyzer", "version": "0.4.0"},
   "root": "/home/me/project",
   "findings": [
     {
@@ -241,7 +244,8 @@ coretrace-python-analyzer --check src/ --advisories advisories.json
 A directory check reads `advisories.json` at the project root and every file passed
 with `--advisories`; a local entry wins over a plugin's for the same advisory. The file
-lists advisories with the package, the vulnerable version range and, optionally, the
+lists advisories with the package, the vulnerable version range (a specifier, or several
+separated by `||` when several release series are affected) and, optionally, the
 affected APIs that feed reachability and correlation:
 ```json
@@ -254,13 +258,45 @@ affected APIs that feed reachability and correlation:
       "vulnerable": "<5.4",
       "summary": "yaml.load can execute arbitrary code from untrusted documents",
       "severity": "critical",
-      "affected_symbols": ["python.yaml.load", "python.yaml.full_load"],
+      "affected_symbols": ["python.yaml.constructor.FullConstructor.construct_python_object_apply"],
+      "entry_points": [
+        {
+          "symbol": "python.yaml.full_load",
+          "justification": "FullLoader uses FullConstructor (commit 5080ba5)",
+          "conditions": [
+            {"kind": "semantic", "text": "the document carries a python/object/apply tag"}
+          ]
+        },
+        {
+          "symbol": "python.yaml.load",
+          "justification": "same path when Loader is FullLoader",
+          "conditions": [
+            {"kind": "argument", "text": "Loader is FullLoader", "argument": "Loader", "values": ["python.yaml.FullLoader"]},
+            {"kind": "semantic", "text": "the document carries a python/object/apply tag"}
+          ]
+        }
+      ],
+      "modules": ["yaml"],
       "aliases": ["GHSA-8q59-q68h-6hv4"]
     }
   ]
 }
 ```
+`affected_symbols` are the functions the fix changed; `entry_points` the public APIs
+through which a project reaches them, each with the justification that ties it to the
+fix — the commit, or the call path — and the `conditions` under which it is affected: an
+argument value the engine can check, or a `semantic` condition it cannot yet, kept on the
+finding as pending review rather than dropped. A call to either kind of symbol is
+reachable. `modules` names the top-level modules the package installs, so the analyzer
+can tell an imported package from a merely required one; it defaults to the package name.
+Every dependency finding records the highest level of evidence established in its
+`level` metadata: `declared` (the requirement allows a vulnerable version), `imported`
+(a module of the package is imported somewhere), `reachable` (an entry point or affected
+symbol is called) or `exploitable` (attacker input reaches it), with `entry_point`,
+`justification`, `conditions` and `conditions_pending_review` on the last two.
 A `coretrace-policy.toml` at the root, or the file passed with `--policy`, denies
 packages, requires pins and lists accepted advisories whose findings are dropped:

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/pyproject.toml RENAMED Viewed

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

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/__init__.py RENAMED Viewed

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

coretrace_python_analyzer-0.4.0/src/coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py ADDED Viewed

@@ -0,0 +1,46 @@
+"""Calls, anywhere in the project, to an API affected by a vulnerable requirement."""
+from __future__ import annotations
+from collections.abc import Sequence
+from typing import ClassVar
+from coretrace_python.analysis import AnyAnalysis
+from coretrace_python.dependency import DependencyAnalysis
+from coretrace_python.dependency.correlation import affected_symbols, evidence
+from coretrace_python.findings import Confidence, Finding
+from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
+from coretrace_python.plugins import ProjectContext, ProjectPlugin
+class ReachableVulnerabilityPlugin(ProjectPlugin):
+    name: ClassVar[str] = "reachable-vulnerability"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({DependencyAnalysis, CallGraphAnalysis})
+    def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
+        affected = affected_symbols(ctx.dependencies, ctx.advisories)
+        if not affected:
+            return ()
+        findings: list[Finding] = []
+        for module in 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, ()):
+                        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"),
+                            )
+                        )
+        return findings

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/bundled/dependency/sample_advisories/sample_advisories.py RENAMED Viewed

@@ -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_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py RENAMED Viewed

@@ -17,11 +17,13 @@ class VulnerableDependencyPlugin(ProjectPlugin):
     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()]
         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"
                 findings.append(
                     Finding(
                         rule_id="vulnerable-dependency",
@@ -37,6 +39,7 @@ class VulnerableDependencyPlugin(ProjectPlugin):
                             "advisory": advisory.id,
                             "package": advisory.package,
                             "specifier": requirement.specifier,
+                            "level": level,
                         },
                     )
                 )

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/cache.py RENAMED Viewed

@@ -37,7 +37,7 @@ from coretrace_python.interprocedural import (
 from coretrace_python.semantic.symbols import SymbolId
 from coretrace_python.source import SourceId, SourceSpan
-CACHE_FORMAT = 4
+CACHE_FORMAT = 5
 @dataclass(frozen=True)

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/dependency/__init__.py RENAMED Viewed

@@ -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_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/dependency/advisories.py RENAMED Viewed

@@ -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,15 @@ 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)
+    return entry
 def load_advisories(path: Path) -> tuple[Advisory, ...]:
     try:
         document = json.loads(path.read_text(encoding="utf-8"))
@@ -165,4 +184,22 @@ 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(
+                str(c["kind"]),
+                str(c["text"]),
+                None if c.get("argument") is None else str(c["argument"]),
+                tuple(str(v) for v in c.get("values") or []),
+            )
+            for c in entry.get("conditions") or []
+        ),
     )

coretrace_python_analyzer-0.4.0/src/coretrace_python/dependency/correlation.py ADDED Viewed

@@ -0,0 +1,113 @@
+"""Correlation engine (architecture §27).
+A package required in a vulnerable version, an API the advisory affects, a call to that
+API reachable in the project, and attacker-controlled data reaching that call: the
+affected APIs become sinks of the ``ADVISORY`` taint kind, so the shared taint engine,
+the function summaries and the refutation engine do the work, and the flows they leave
+are correlated here into one high-confidence ``exploitable-vulnerability`` finding.
+"""
+from __future__ import annotations
+from collections.abc import Iterable, Mapping
+from coretrace_python.dependency.graph import DIRECT, Advisory, DependencyGraph
+from coretrace_python.findings import Confidence, Finding, Severity
+from coretrace_python.findings.refutation import Status, Verdict, Verdicts
+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]) -> 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.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: Affected) -> tuple[Sink, ...]:
+    return tuple(Sink(symbol, TaintKind.ADVISORY) for symbol in affected)
+def evidence(advisory: Advisory, symbol: SymbolId, level: str) -> 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 under which
+    conditions, the ones the engine could not check listed as pending 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)
+        # ponytail: no condition is checked yet, so every one awaits review; argument
+        # conditions get checked at the call site once call sites carry argument symbols.
+        metadata["conditions_pending_review"] = "; ".join(c.text for c in entry.conditions)
+    return metadata
+def correlate(
+    function: str,
+    flows: Iterable[TaintFlow],
+    verdicts: Verdicts | None,
+    affected: Affected,
+) -> tuple[Finding, ...]:
+    """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
+        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
+        findings.extend(
+            _exploitable(function, flow, advisory, verdict, hotspot) for advisory in affected.get(flow.sink.symbol, ())
+        )
+    return tuple(findings)
+def _exploitable(
+    function: str, flow: TaintFlow, advisory: Advisory, verdict: Verdict | None, hotspot: bool
+) -> 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"),
+        "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,
+    )

{coretrace_python_analyzer-0.3.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/dependency/graph.py RENAMED Viewed

@@ -11,7 +11,7 @@ from __future__ import annotations
 import re
 import tomllib
-from collections.abc import Mapping
+from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from pathlib import PurePath
 from types import MappingProxyType
@@ -50,6 +50,13 @@ class Version:
         return self.parts + (0,) * (length - len(self.parts))
     def satisfies(self, specifier: str) -> bool:
+        """Whether this version is in ``specifier``: comma-separated clauses all hold, and
+        ``||`` separates alternatives, as an advisory over several release series needs
+        (``>=4.2,<4.2.28 || >=5.2,<5.2.11``)."""
+        return any(self._satisfies_all(alternative) for alternative in _alternatives(specifier))
+    def _satisfies_all(self, specifier: str) -> bool:
         for clause in [c.strip() for c in specifier.split(",") if c.strip()]:
             match = _CLAUSE.match(clause)
             if match is None:
@@ -91,12 +98,17 @@ class Version:
         return True
+def _alternatives(specifier: str) -> list[str]:
+    return [a for a in specifier.split("||") if a.strip()] or [""]
 def _lower_bounds(specifier: str) -> list[Version]:
     bounds: list[Version] = []
-    for clause in [c.strip() for c in specifier.split(",") if c.strip()]:
-        match = _CLAUSE.match(clause)
-        if match is not None and match.group(1) in (">=", ">", "~=", "^", "==", "==="):
-            bounds.append(Version.parse(match.group(2)))
+    for alternative in _alternatives(specifier):
+        for clause in [c.strip() for c in alternative.split(",") if c.strip()]:
+            match = _CLAUSE.match(clause)
+            if match is not None and match.group(1) in (">=", ">", "~=", "^", "==", "==="):
+                bounds.append(Version.parse(match.group(2)))
     return bounds
@@ -130,6 +142,37 @@ class Requirement:
         return any(v.satisfies(self.specifier) and v.satisfies(vulnerable) for v in candidates)
+@dataclass(frozen=True)
+class Condition:
+    """What must hold for an entry point to reach, or exploit, the affected code: the
+    value of an argument, the loader or algorithm used, the format decoded, the kind of
+    input, a configuration. ``kind`` says whether the engine can check it: an
+    ``argument`` condition names the argument and the values that satisfy it; a
+    ``semantic`` condition cannot be checked yet and is reported as pending review."""
+    kind: str
+    text: str
+    argument: str | None = None
+    values: tuple[str, ...] = ()
+    @property
+    def checkable(self) -> bool:
+        return self.kind == "argument"
+@dataclass(frozen=True)
+class AdvisoryEntryPoint:
+    """A public API through which a project reaches an affected symbol, justified by the
+    fixing commit or by a call path, with the conditions under which it is affected."""
+    symbol: SymbolId
+    justification: str
+    conditions: tuple[Condition, ...] = ()
+DIRECT = "affected symbol, changed by the fix"
 @dataclass(frozen=True)
 class Advisory:
     id: str
@@ -139,10 +182,36 @@ class Advisory:
     severity: Severity
     affected_symbols: tuple[SymbolId, ...] = ()
     aliases: tuple[str, ...] = ()
+    entry_points: tuple[AdvisoryEntryPoint, ...] = ()
+    # Top-level modules the package installs, to tell an imported package from a merely
+    # required one; defaults to the package name (``pyyaml`` installs ``yaml``: say so).
+    modules: tuple[str, ...] = ()
+    def __post_init__(self) -> None:
+        if not self.modules:
+            object.__setattr__(self, "modules", (normalize(self.package).replace("-", "_"),))
     def affects(self, requirement: Requirement) -> bool:
         return requirement.name == normalize(self.package) and requirement.may_match(self.vulnerable)
+    @property
+    def reachable_symbols(self) -> tuple[SymbolId, ...]:
+        """Every symbol a call to which reaches the vulnerability: the entry points and
+        the affected symbols themselves."""
+        return (*(e.symbol for e in self.entry_points), *self.affected_symbols)
+    def entry_point(self, symbol: SymbolId) -> AdvisoryEntryPoint | None:
+        return next((e for e in self.entry_points if e.symbol == symbol), None)
+    def imported_by(self, symbols: Iterable[SymbolId]) -> bool:
+        """Whether any of the ``symbols`` a project imports belongs to this package."""
+        prefixes = tuple(f"python.{m}" for m in self.modules)
+        return any(
+            s.canonical_name == p or s.canonical_name.startswith(p + ".") for s in symbols for p in prefixes
+        )
 class DependencyGraph:
     def __init__(self, requirements: Mapping[str, Requirement] | None = None, errors: tuple[str, ...] = ()) -> None:

coretrace-python-analyzer 0.3.0__tar.gz → 0.4.0__tar.gz

coretrace-python-analyzer 0.3.0tar.gz → 0.4.0tar.gz