Skip to content

Commit f1de919

Browse files
committed
feat: justify advisory entry points, keep their conditions and record evidence levels
An advisory now distinguishes the affected_symbols a fix changed from the public entry_points through which a project reaches them; each entry point carries the justification tying it to the fix and the conditions under which it is affected. A condition the engine cannot check is kept on the finding as pending review, never dropped. modules names what the package installs, so a required package can be told from an imported one. Every dependency finding records its evidence level: declared, imported, reachable or exploitable. Part of CoreTrace-Entreprise/coretrace-python-analyzer-plugins#2
1 parent 15d30ed commit f1de919

8 files changed

Lines changed: 167 additions & 16 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
## Unreleased
44

5+
### Dependencies
6+
7+
- 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`.
8+
59
### Plugins
610

711
- 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).

‎docs/usage.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -254,13 +254,45 @@ affected APIs that feed reachability and correlation:
254254
"vulnerable": "<5.4",
255255
"summary": "yaml.load can execute arbitrary code from untrusted documents",
256256
"severity": "critical",
257-
"affected_symbols": ["python.yaml.load", "python.yaml.full_load"],
257+
"affected_symbols": ["python.yaml.constructor.FullConstructor.construct_python_object_apply"],
258+
"entry_points": [
259+
{
260+
"symbol": "python.yaml.full_load",
261+
"justification": "FullLoader uses FullConstructor (commit 5080ba5)",
262+
"conditions": [
263+
{"kind": "semantic", "text": "the document carries a python/object/apply tag"}
264+
]
265+
},
266+
{
267+
"symbol": "python.yaml.load",
268+
"justification": "same path when Loader is FullLoader",
269+
"conditions": [
270+
{"kind": "argument", "text": "Loader is FullLoader", "argument": "Loader", "values": ["python.yaml.FullLoader"]},
271+
{"kind": "semantic", "text": "the document carries a python/object/apply tag"}
272+
]
273+
}
274+
],
275+
"modules": ["yaml"],
258276
"aliases": ["GHSA-8q59-q68h-6hv4"]
259277
}
260278
]
261279
}
262280
```
263281

282+
`affected_symbols` are the functions the fix changed; `entry_points` the public APIs
283+
through which a project reaches them, each with the justification that ties it to the
284+
fix — the commit, or the call path — and the `conditions` under which it is affected: an
285+
argument value the engine can check, or a `semantic` condition it cannot yet, kept on the
286+
finding as pending review rather than dropped. A call to either kind of symbol is
287+
reachable. `modules` names the top-level modules the package installs, so the analyzer
288+
can tell an imported package from a merely required one; it defaults to the package name.
289+
290+
Every dependency finding records the highest level of evidence established in its
291+
`level` metadata: `declared` (the requirement allows a vulnerable version), `imported`
292+
(a module of the package is imported somewhere), `reachable` (an entry point or affected
293+
symbol is called) or `exploitable` (attacker input reaches it), with `entry_point`,
294+
`justification`, `conditions` and `conditions_pending_review` on the last two.
295+
264296
A `coretrace-policy.toml` at the root, or the file passed with `--policy`, denies
265297
packages, requires pins and lists accepted advisories whose findings are dropped:
266298

‎src/coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
from coretrace_python.analysis import AnyAnalysis
99
from coretrace_python.dependency import DependencyAnalysis
10+
from coretrace_python.dependency.correlation import evidence
1011
from coretrace_python.findings import Confidence, Finding
1112
from coretrace_python.interprocedural import CallGraphAnalysis, ExternalSymbol
1213
from coretrace_python.plugins import ProjectContext, ProjectPlugin
@@ -21,7 +22,7 @@ def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
2122
for requirement in ctx.dependencies.requirements:
2223
for advisory in ctx.advisories:
2324
if advisory.affects(requirement):
24-
for symbol in advisory.affected_symbols:
25+
for symbol in advisory.reachable_symbols:
2526
affected.setdefault(symbol, advisory)
2627
if not affected:
2728
return ()
@@ -46,11 +47,7 @@ def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
4647
confidence=Confidence.HIGH,
4748
span=site.location,
4849
function=function,
49-
metadata={
50-
"advisory": advisory.id,
51-
"package": advisory.package,
52-
"symbol": str(site.target.symbol),
53-
},
50+
metadata=evidence(advisory, site.target.symbol, "reachable"),
5451
)
5552
)
5653
return findings

‎src/coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,13 @@ class VulnerableDependencyPlugin(ProjectPlugin):
1717

1818
def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
1919
findings: list[Finding] = []
20+
imported = [s for module in ctx.modules for s in ctx.imports(module).all_symbols()]
2021
for requirement in ctx.dependencies.requirements:
2122
for advisory in ctx.advisories:
2223
if not advisory.affects(requirement):
2324
continue
2425
pinned = requirement.pinned is not None
26+
level = "imported" if advisory.imported_by(imported) else "declared"
2527
findings.append(
2628
Finding(
2729
rule_id="vulnerable-dependency",
@@ -37,6 +39,7 @@ def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
3739
"advisory": advisory.id,
3840
"package": advisory.package,
3941
"specifier": requirement.specifier,
42+
"level": level,
4043
},
4144
)
4245
)

‎src/coretrace_python/dependency/__init__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
from coretrace_python.dependency.graph import (
1212
DEPENDENCY_FILES,
1313
Advisory,
14+
AdvisoryEntryPoint,
15+
Condition,
1416
DependencyAnalysis,
1517
DependencyGraph,
1618
Requirement,
@@ -26,7 +28,9 @@
2628
"DEPENDENCY_FILES",
2729
"POLICY_FILE",
2830
"Advisory",
31+
"AdvisoryEntryPoint",
2932
"AdvisoryFileError",
33+
"Condition",
3034
"DependencyAnalysis",
3135
"DependencyGraph",
3236
"Policy",

‎src/coretrace_python/dependency/advisories.py‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55
events into a version specifier; ``dump_advisories`` writes them as a small JSON file
66
that a project keeps at its root as ``advisories.json`` or passes with ``--advisories``.
77
OSV records name no affected APIs, so imported advisories feed the requirement checks
8-
and the SBOM; a file completed by hand with ``affected_symbols`` also feeds the
9-
reachability and correlation checks.
8+
and the SBOM; a file completed by hand with ``affected_symbols``, ``entry_points`` and
9+
their ``conditions`` also feeds the reachability and correlation checks.
1010
"""
1111

1212
from __future__ import annotations
@@ -17,7 +17,7 @@
1717
from pathlib import Path
1818
from typing import Any
1919

20-
from coretrace_python.dependency.graph import Advisory, normalize
20+
from coretrace_python.dependency.graph import Advisory, AdvisoryEntryPoint, Condition, normalize
2121
from coretrace_python.findings import Severity
2222
from coretrace_python.semantic.symbols import SymbolId
2323

@@ -137,13 +137,31 @@ def dump_advisories(advisories: Iterable[Advisory]) -> str:
137137
"severity": a.severity.value,
138138
"affected_symbols": [str(s) for s in a.affected_symbols],
139139
"aliases": list(a.aliases),
140+
"entry_points": [
141+
{
142+
"symbol": str(e.symbol),
143+
"justification": e.justification,
144+
"conditions": [_condition_entry(c) for c in e.conditions],
145+
}
146+
for e in a.entry_points
147+
],
148+
"modules": list(a.modules),
140149
}
141150
for a in advisories
142151
],
143152
}
144153
return json.dumps(document, indent=2) + "\n"
145154

146155

156+
def _condition_entry(condition: Condition) -> dict[str, Any]:
157+
entry: dict[str, Any] = {"kind": condition.kind, "text": condition.text}
158+
if condition.argument is not None:
159+
entry["argument"] = condition.argument
160+
if condition.values:
161+
entry["values"] = list(condition.values)
162+
return entry
163+
164+
147165
def load_advisories(path: Path) -> tuple[Advisory, ...]:
148166
try:
149167
document = json.loads(path.read_text(encoding="utf-8"))
@@ -165,4 +183,22 @@ def _advisory(entry: Mapping[str, Any]) -> Advisory:
165183
Severity(entry["severity"]),
166184
tuple(SymbolId(str(s)) for s in entry.get("affected_symbols") or []),
167185
tuple(str(a) for a in entry.get("aliases") or []),
186+
tuple(_entry_point(e) for e in entry.get("entry_points") or []),
187+
tuple(str(m) for m in entry.get("modules") or []),
188+
)
189+
190+
191+
def _entry_point(entry: Mapping[str, Any]) -> AdvisoryEntryPoint:
192+
return AdvisoryEntryPoint(
193+
SymbolId(str(entry["symbol"])),
194+
str(entry["justification"]),
195+
tuple(
196+
Condition(
197+
str(c["kind"]),
198+
str(c["text"]),
199+
None if c.get("argument") is None else str(c["argument"]),
200+
tuple(str(v) for v in c.get("values") or []),
201+
)
202+
for c in entry.get("conditions") or []
203+
),
168204
)

‎src/coretrace_python/dependency/correlation.py‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
from collections.abc import Iterable, Mapping
1313

14-
from coretrace_python.dependency.graph import Advisory, DependencyGraph
14+
from coretrace_python.dependency.graph import DIRECT, Advisory, DependencyGraph
1515
from coretrace_python.findings import Confidence, Finding, Severity
1616
from coretrace_python.findings.refutation import Status, Verdicts
1717
from coretrace_python.semantic.symbols import SymbolId
@@ -27,7 +27,7 @@ def affected_symbols(
2727
for requirement in dependencies.requirements:
2828
for advisory in advisories:
2929
if advisory.affects(requirement):
30-
for symbol in advisory.affected_symbols:
30+
for symbol in advisory.reachable_symbols:
3131
affected.setdefault(symbol, advisory)
3232
return affected
3333

@@ -36,6 +36,26 @@ def advisory_sinks(affected: Mapping[SymbolId, Advisory]) -> tuple[Sink, ...]:
3636
return tuple(Sink(symbol, TaintKind.ADVISORY) for symbol in affected)
3737

3838

39+
def evidence(advisory: Advisory, symbol: SymbolId, level: str) -> dict[str, str]:
40+
"""What a finding keeps of the advisory for ``symbol``: the level of evidence
41+
established, how the symbol relates to the vulnerability and under which
42+
conditions, the ones the engine could not check listed as pending review."""
43+
44+
metadata = {"advisory": advisory.id, "package": advisory.package, "symbol": str(symbol), "level": level}
45+
entry = advisory.entry_point(symbol)
46+
if entry is None:
47+
metadata["justification"] = DIRECT
48+
return metadata
49+
metadata["entry_point"] = str(entry.symbol)
50+
metadata["justification"] = entry.justification
51+
if entry.conditions:
52+
metadata["conditions"] = "; ".join(c.text for c in entry.conditions)
53+
# ponytail: no condition is checked yet, so every one awaits review; argument
54+
# conditions get checked at the call site once call sites carry argument symbols.
55+
metadata["conditions_pending_review"] = "; ".join(c.text for c in entry.conditions)
56+
return metadata
57+
58+
3959
def correlate(
4060
function: str,
4161
flows: Iterable[TaintFlow],
@@ -60,9 +80,7 @@ def correlate(
6080
f"the required {advisory.package} {advisory.vulnerable}: {advisory.summary}"
6181
)
6282
metadata = {
63-
"advisory": advisory.id,
64-
"package": advisory.package,
65-
"symbol": str(flow.sink.symbol),
83+
**evidence(advisory, flow.sink.symbol, "exploitable"),
6684
"source": str(flow.source.symbol),
6785
"source_label": flow.source.label,
6886
"verdict": "hotspot" if hotspot else "vulnerability",

‎src/coretrace_python/dependency/graph.py‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111

1212
import re
1313
import tomllib
14-
from collections.abc import Mapping
14+
from collections.abc import Iterable, Mapping
1515
from dataclasses import dataclass
1616
from pathlib import PurePath
1717
from types import MappingProxyType
@@ -130,6 +130,37 @@ def may_match(self, vulnerable: str) -> bool:
130130
return any(v.satisfies(self.specifier) and v.satisfies(vulnerable) for v in candidates)
131131

132132

133+
@dataclass(frozen=True)
134+
class Condition:
135+
"""What must hold for an entry point to reach, or exploit, the affected code: the
136+
value of an argument, the loader or algorithm used, the format decoded, the kind of
137+
input, a configuration. ``kind`` says whether the engine can check it: an
138+
``argument`` condition names the argument and the values that satisfy it; a
139+
``semantic`` condition cannot be checked yet and is reported as pending review."""
140+
141+
kind: str
142+
text: str
143+
argument: str | None = None
144+
values: tuple[str, ...] = ()
145+
146+
@property
147+
def checkable(self) -> bool:
148+
return self.kind == "argument"
149+
150+
151+
@dataclass(frozen=True)
152+
class AdvisoryEntryPoint:
153+
"""A public API through which a project reaches an affected symbol, justified by the
154+
fixing commit or by a call path, with the conditions under which it is affected."""
155+
156+
symbol: SymbolId
157+
justification: str
158+
conditions: tuple[Condition, ...] = ()
159+
160+
161+
DIRECT = "affected symbol, changed by the fix"
162+
163+
133164
@dataclass(frozen=True)
134165
class Advisory:
135166
id: str
@@ -139,10 +170,36 @@ class Advisory:
139170
severity: Severity
140171
affected_symbols: tuple[SymbolId, ...] = ()
141172
aliases: tuple[str, ...] = ()
173+
entry_points: tuple[AdvisoryEntryPoint, ...] = ()
174+
# Top-level modules the package installs, to tell an imported package from a merely
175+
# required one; defaults to the package name (``pyyaml`` installs ``yaml``: say so).
176+
modules: tuple[str, ...] = ()
177+
178+
def __post_init__(self) -> None:
179+
if not self.modules:
180+
object.__setattr__(self, "modules", (normalize(self.package).replace("-", "_"),))
142181

143182
def affects(self, requirement: Requirement) -> bool:
144183
return requirement.name == normalize(self.package) and requirement.may_match(self.vulnerable)
145184

185+
@property
186+
def reachable_symbols(self) -> tuple[SymbolId, ...]:
187+
"""Every symbol a call to which reaches the vulnerability: the entry points and
188+
the affected symbols themselves."""
189+
190+
return (*(e.symbol for e in self.entry_points), *self.affected_symbols)
191+
192+
def entry_point(self, symbol: SymbolId) -> AdvisoryEntryPoint | None:
193+
return next((e for e in self.entry_points if e.symbol == symbol), None)
194+
195+
def imported_by(self, symbols: Iterable[SymbolId]) -> bool:
196+
"""Whether any of the ``symbols`` a project imports belongs to this package."""
197+
198+
prefixes = tuple(f"python.{m}" for m in self.modules)
199+
return any(
200+
s.canonical_name == p or s.canonical_name.startswith(p + ".") for s in symbols for p in prefixes
201+
)
202+
146203

147204
class DependencyGraph:
148205
def __init__(self, requirements: Mapping[str, Requirement] | None = None, errors: tuple[str, ...] = ()) -> None:

0 commit comments

Comments
 (0)