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

coretrace-python-analyzer 0.2.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.2.0 → coretrace_python_analyzer-0.4.0}/CHANGELOG.md RENAMED Viewed

@@ -1,5 +1,39 @@
 # 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
+- Two plugins may declare the same symbol: an identical model is registered once and sinks merge their kinds and positions; a real conflict names both plugins instead of failing the run on the first duplicate (#92).
+- A plugin's entrypoint may be a package, `<module>/__init__.py`, so a plugin can split its tables across files and import them relatively (#93).
+- The cache key covers every file of a plugin directory, not only `.py` and `.toml`, so rules or advisories shipped as data invalidate cached results when they change (#94).
+### Analysis
+- New taint kinds: `NOSQL` in `TaintKind.ALL`; `LOG` and `PII` outside it, carried only by the values a model marks, so a NoSQL-injection, log-injection or personal-data detector no longer has to share a kind with another rule (#96).
+### Precision
+- A `Sanitizer` declared on a function of the analysed project takes precedence over the summary derived from its body, in the same file and across files, so a code base can declare its own validation layer (#95).
 ## 0.2.0 (2026-09-06)
 ### Adoption in an existing repository

{coretrace_python_analyzer-0.2.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.2.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.2.0 → coretrace_python_analyzer-0.4.0}/docs/plugins.md RENAMED Viewed

@@ -38,7 +38,12 @@ class = "SensitiveLoggingPlugin"
 | `plugin_api` | The range of plugin API versions the plugin supports. The current API is version 1. |
 | `requires` | Capabilities the plugin needs; a mismatch with the class's `requires` is a manifest error. |
 | `provides` | Capabilities the plugin offers, for documentation and conflict detection. |
-| `entrypoint` | The module file (without `.py`, next to the manifest) and the class in it. |
+| `entrypoint` | The module (without `.py`, next to the manifest) and the class in it. |
+The entrypoint module may be a package, `<module>/__init__.py`, when a plugin grows past
+one file: its submodules are reached through relative imports (`from .tables import
+celery`). Two plugins may use the same module name; each is imported under a name derived
+from its path.
 ## Symbols
@@ -101,10 +106,14 @@ class CommandInjectionPlugin(TaintDetector):
 ```
 `confidence` defaults to high; a hotspot, a flow behind a guard that mentions the value
-or an authorization decorator, is reported at medium. The taint kinds are `SQL`,
-`COMMAND`, `HTML`, `PATH`, `SSRF`, `CODE`, `DESERIALIZATION`, `REDIRECT`, `ADVISORY`
-(APIs affected by advisories) and `CREDENTIAL`, which only credential-named parameters
-carry so that ordinary input reaching a database write is not a plaintext credential.
+or an authorization decorator, is reported at medium. The taint kinds every source
+carries by default (`TaintKind.ALL`) are `SQL`, `NOSQL`, `COMMAND`, `HTML`, `PATH`,
+`SSRF`, `CODE`, `DESERIALIZATION`, `REDIRECT` and `ADVISORY` (APIs affected by
+advisories). Three kinds are outside `ALL`, so only a value a model marks with them
+reaches their sinks: `CREDENTIAL`, which credential-named parameters carry so that
+ordinary input reaching a database write is not a plaintext credential; `LOG`, for
+values that must not be written to a log as they are; and `PII`, for personal data
+that must not leave the application through a log, a third party or plain storage.
 ### Security models: `ModelPlugin`
@@ -142,12 +151,49 @@ class BottleModels(ModelPlugin):
 | `Validator(symbol, kinds=ALL, argument=0)` | A callable whose truth proves its argument safe, such as `re.fullmatch`; a flow guarded by it is refuted. |
 | `AuthorizationGuard(symbol, label)` | A decorator or a condition restricting who reaches the code, such as `login_required`; a flow behind it is a hotspot. |
+Two plugins may describe the same symbol. An identical model is registered once; two
+`Sink` models merge their kinds and positions, so a plugin can add `SQL` to a sink
+another plugin declared for `COMMAND`; any other difference is a conflict that stops
+the analysis with a `ModelError` naming both plugins.
 A model plugin may also carry `advisories`, a tuple of `Advisory` values
 (`coretrace_python.dependency`) with the package, the vulnerable range and the affected
 symbols, as the shipped `sample-advisories` plugin does. Requirements matching them are
 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.2.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.2.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:
@@ -283,8 +319,9 @@ coretrace-python-analyzer --check src/ --sbom sbom.json --policy security/policy
 ## Large projects
 `--cache DIR` keeps the results of a directory check on disk, one entry per module,
-keyed by the module's source, the tool and plugin versions, the security models, the
-advisories, the dependency graph and the modules it imports. On the next run an unchanged
+keyed by the module's source, the tool version, every file of every plugin directory
+(code, manifest and data alike), the security models, the advisories, the dependency
+graph and the modules it imports. On the next run an unchanged
 module is served from the cache, so editing one file re-analyses that file and its
 importers only. Entries are plain data; an unreadable entry is recomputed.
@@ -335,6 +372,29 @@ coretrace-python-analyzer --check src/ --plugins ./coretrace-plugins
 coretrace-python-analyzer --check src/ --no-bundled-plugins --plugins ./coretrace-plugins
 ```
+### Your own validation layer
+A code base that already validates its input has functions the analyzer cannot know are
+safe: a `clean()` that returns its argument looks, from its body, like a function that
+passes taint through. Declare them in a model plugin by their project symbol,
+`python.<module>.<function>`, and the analyzer takes your word over what it derived:
+```python
+from coretrace_python.plugins import ModelPlugin
+from coretrace_python.semantic.symbols import SymbolId
+from coretrace_python.taint import Sanitizer, TaintKind, Validator
+class HouseModels(ModelPlugin):
+    name = "house-models"
+    models = (
+        # the result of app.validation.clean is safe for commands, whatever the body does
+        Sanitizer(SymbolId("python.app.validation.clean"), TaintKind.COMMAND),
+        # a flow behind ``if app.validation.is_slug(value):`` is refuted
+        Validator(SymbolId("python.app.validation.is_slug")),
+    )
+```
 ## Continuous integration
 The exit status gates the job and the SARIF report feeds code scanning. On GitHub

{coretrace_python_analyzer-0.2.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.2.0"
+version = "0.4.0"
 description = "Static security analysis infrastructure for Python code"
 readme = "README.md"
 requires-python = ">=3.11"

{coretrace_python_analyzer-0.2.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.2.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.2.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.2.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.2.0 → coretrace_python_analyzer-0.4.0}/src/coretrace_python/cache.py RENAMED Viewed

@@ -14,7 +14,7 @@ from __future__ import annotations
 import hashlib
 import json
 import os
-from collections.abc import Iterable, Mapping
+from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 from types import MappingProxyType
@@ -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)
@@ -64,15 +64,18 @@ def fingerprint(*parts: str) -> str:
     return digest.hexdigest()
-def directory_fingerprint(directory: Path, suffixes: Iterable[str] = (".py", ".toml")) -> str:
-    """A digest of the source files under ``directory``, so edited plugin code misses."""
+def directory_fingerprint(directory: Path) -> str:
+    """A digest of every file under ``directory``, so an edited plugin misses: its code,
+    its manifest and the rule or advisory data it ships in any format. Bytecode and
+    hidden files are not part of what the plugin does."""
-    wanted = tuple(suffixes)
     parts: list[str] = []
     for path in sorted(directory.rglob("*")):
-        if path.is_file() and path.suffix in wanted:
-            parts.append(str(path.relative_to(directory)))
-            parts.append(path.read_text(encoding="utf-8", errors="replace"))
+        relative = path.relative_to(directory)
+        if not path.is_file() or any(p == "__pycache__" or p.startswith(".") for p in relative.parts):
+            continue
+        parts.append(str(relative))
+        parts.append(path.read_bytes().hex())
     return fingerprint(*parts)

{coretrace_python_analyzer-0.2.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.2.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.2.0__tar.gz → 0.4.0__tar.gz

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