Repository navigation
Expand file tree
/
Copy pathapi.py
More file actions
237 lines (187 loc) · 9.23 KB
/
Copy pathapi.py
File metadata and controls
237 lines (187 loc) · 9.23 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
"""The typed plugin contract (architecture §13, §32, §33, §34).
A plugin declares the analyses it needs and consumes them through a ``PluginContext``,
a deliberately narrow view of the engine: the module, its functions and the declared
analyses. Nothing else is reachable, which keeps plugins on the stable API and leaves
room for out-of-process isolation later.
"""
from __future__ import annotations
import dataclasses
from abc import ABC, abstractmethod
from collections.abc import Iterable, Mapping, Sequence
from pathlib import Path
from typing import Any, ClassVar, overload
from coretrace_python.analysis import (
Analysis,
AnalysisManager,
AnyAnalysis,
FunctionAnalysis,
UndeclaredDependencyError,
)
from coretrace_python.analysis.provider import R
from coretrace_python.dependency import Advisory, DependencyGraph, Policy
from coretrace_python.findings import Finding
from coretrace_python.findings.context import path_in_project
from coretrace_python.hir import nodes
from coretrace_python.interprocedural import (
CallGraph,
CallGraphAnalysis,
ModuleFunction,
ModuleGraph,
)
from coretrace_python.ir.lowering import analyzable_functions
from coretrace_python.semantic.imports import ImportAnalysis, ImportTable
from coretrace_python.taint import EntryPointAnalysis, Model, ProjectTemplates
PLUGIN_API_VERSION = 1
class Plugin(ABC):
"""Declares the analyses it needs and the security models it contributes,
then turns analysis results into findings."""
name: ClassVar[str]
requires: ClassVar[frozenset[AnyAnalysis]] = frozenset()
models: ClassVar[tuple[Model, ...]] = ()
advisories: ClassVar[tuple[Advisory, ...]] = ()
@abstractmethod
def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
raise NotImplementedError
def project_models(self, root: Path) -> Sequence[Model]:
"""Models read from the project under ``root``, such as validators it declares
in a file there. Called once per directory check, in every process analysing
it, before any module; a single-file check reads no project. A model declared
wrongly raises ``ModelError``, which stops the check with its message."""
return ()
class ModelPlugin(Plugin):
"""A plugin that only contributes security models or advisories (§15 providers)."""
def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
return ()
class ProjectContext:
"""What a project-scoped plugin sees: the module graph, the dependency graph, the
advisories every plugin and advisory file contributed, the dependency policy, each
module's imports, call graph and functions, and the project's templates with the
filters they call. The engine passes the call graphs and functions of modules it
served from its cache."""
def __init__(
self,
graph: ModuleGraph,
dependencies: DependencyGraph,
advisories: tuple[Advisory, ...],
managers: Mapping[str, AnalysisManager],
call_graphs: Mapping[str, CallGraph] | None = None,
policy: Policy | None = None,
root: Path | None = None,
functions: Mapping[str, tuple[ModuleFunction, ...]] | None = None,
templates: ProjectTemplates | None = None,
) -> None:
self.root = root
self.templates = templates or ProjectTemplates()
self.graph = graph
self.dependencies = dependencies
self.advisories = advisories
self.policy = policy or Policy()
self._managers = managers
self._call_graphs = dict(call_graphs or {})
self._functions = dict(functions or {})
@property
def modules(self) -> tuple[str, ...]:
return tuple(self._managers)
def imports(self, module: str) -> ImportTable:
return self._managers[module].get(ImportAnalysis)
def call_graph(self, module: str) -> CallGraph:
cached = self._call_graphs.get(module)
return cached if cached is not None else self._managers[module].get(CallGraphAnalysis)
def functions(self, module: str) -> tuple[ModuleFunction, ...]:
"""The module's functions as its call graph names them, each with its span, so a
finding can be placed in one, and the label of the entry point it is, if any."""
cached = self._functions.get(module)
return cached if cached is not None else self._managers[module].get(EntryPointAnalysis)
class ProjectPlugin(Plugin):
"""A plugin that runs once per project rather than once per module (§26)."""
def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
return ()
@abstractmethod
def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
raise NotImplementedError
def refine(self, ctx: ProjectContext, findings: tuple[Finding, ...]) -> Sequence[Finding]:
"""Reclassify the findings of the run, once every plugin has reported.
A refinement returns the same findings in the same order and may change only
their severity, their confidence and add metadata: what a finding is, where it
is and the evidence behind it are not the refiner's to touch. The engine records
who reclassified a finding and what it was before, and rejects anything else."""
return findings
class RefinementError(Exception):
"""A refinement did more than reclassify a finding."""
REFINABLE = ("severity", "confidence")
def apply_refinement(plugin: Plugin, original: Sequence[Finding], refined: Sequence[Finding]) -> tuple[Finding, ...]:
"""The refined findings, checked against the contract of ``ProjectPlugin.refine`` and
stamped with a trace of the reclassification."""
if len(refined) != len(original):
raise RefinementError(f"plugin {plugin.name!r} returned {len(refined)} findings for {len(original)}")
kept: list[Finding] = []
for before, after in zip(original, refined, strict=True):
for attribute in ("rule_id", "message", "span", "function"):
if getattr(before, attribute) != getattr(after, attribute):
raise RefinementError(f"plugin {plugin.name!r} changed the {attribute} of a finding")
lost = [k for k, v in before.metadata.items() if after.metadata.get(k) != v]
if lost:
raise RefinementError(f"plugin {plugin.name!r} changed the evidence {lost} of a finding")
changed = [a for a in REFINABLE if getattr(before, a) != getattr(after, a)]
if not changed:
kept.append(after)
continue
trace = dict(after.metadata)
for attribute in changed:
trace.setdefault(f"original_{attribute}", getattr(before, attribute).value)
refiners = trace.get("refined_by", "")
trace["refined_by"] = f"{refiners},{plugin.name}" if refiners else plugin.name
kept.append(dataclasses.replace(after, metadata=trace))
return tuple(kept)
class PluginContext:
"""What one plugin may see while analysing one module. ``root`` is the root of the
analysis, when the engine knows one: a file's path in the project is read from it."""
def __init__(
self,
manager: AnalysisManager,
plugin: Plugin,
functions: tuple[nodes.Function, ...] | None = None,
root: Path | None = None,
) -> None:
self._manager = manager
self._plugin = plugin
self._functions = analyzable_functions(manager.module) if functions is None else functions
self._root = root
def path(self, source_id: object) -> str | None:
"""The path of the file ``source_id`` names from the root of the analysis, what
tells test code apart (``findings.context``), not where the project sits; ``None``
for a file outside it (#253)."""
return path_in_project(source_id, self._root)
@property
def module(self) -> nodes.Module:
return self._manager.module
def functions(self) -> tuple[nodes.Function, ...]:
"""The functions the engine analyses: the module body (``<module>``), top-level
functions, class bodies (``Cls.<body>``) and methods."""
return self._functions
@overload
def get(self, analysis: type[Analysis[R]], function: None = None) -> R: ...
@overload
def get(self, analysis: type[FunctionAnalysis[R]], function: nodes.Function) -> R: ...
def get(self, analysis: AnyAnalysis, function: nodes.Function | None = None) -> Any:
if analysis not in self._plugin.requires:
raise UndeclaredDependencyError(
f"{self._plugin.name} requests {analysis.name} without declaring it in requires"
)
if function is None:
assert issubclass(analysis, Analysis)
return self._manager.get(analysis)
assert issubclass(analysis, FunctionAnalysis)
return self._manager.get(analysis, function)
def run_plugins(
manager: AnalysisManager,
plugins: Iterable[Plugin],
functions: tuple[nodes.Function, ...] | None = None,
root: Path | None = None,
) -> tuple[Finding, ...]:
"""Run every plugin against one shared manager and concatenate their findings;
``root`` is the root of the analysis (``PluginContext.path``)."""
findings: list[Finding] = []
for plugin in plugins:
findings.extend(plugin.analyze(PluginContext(manager, plugin, functions, root)))
return tuple(findings)