Skip to content

Commit 6d2160f

Browse files
committed
Merge branch 'main' into release/0.8.0
2 parents 4df3fdc + f93684d commit 6d2160f

4 files changed

Lines changed: 35 additions & 18 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
### Precision
66

7+
- A `Validator` proves its argument safe only for the kinds it declares. A validator declared for `REDIRECT` used to refute a command injection through the same value; the flow is now a hotspot, and it is refuted only when the validator covers every kind reaching the sink (#143).
78
- A sanitizer called inside a project function protects the flows through that function, for every caller. That covers a helper that escapes before answering, a view redirecting to `reverse(...)`, and a helper rendering a template the analyzer shows escaping. Function summaries keep, for each parameter, the taint kinds cleared on every path from it to an external call or to the return value. A path that skips the sanitizer, or a kind it does not clear, still reaches the sink. The cache format is bumped (#134).
89

910
### Plugins

‎docs/plugins.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ class BottleModels(ModelPlugin):
150150
| `SuffixSink(suffix, kinds, positions=())` | A sink matched by the end of the symbol, for methods of any class such as `objects.raw`. |
151151
| `SafeArgument(symbol, argument, values, position=None, kinds=ALL)` | A call to the sink `symbol` whose `argument` (by keyword, or at `position`) denotes one of `values` is not a sink for `kinds`, such as `yaml.load` with `Loader=yaml.SafeLoader`. Values are written as the analyzer records arguments: a symbol by its canonical name, a constant as Python writes it (`True`). Only a value given explicitly makes the call safe. |
152152
| `TemplateRender(symbol, position=0, keyword="template_name")` | A call rendering, with autoescaping, the template named by its argument at `position` or `keyword`, such as `render_to_string`. What it returns carries no `HTML` when the name is written in the call and the project's template escapes everything it prints (see the usage guide). |
153-
| `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. `symbol` may be a function of the project, by its project symbol (`python.hc.accounts.views._allow_redirect`), which then counts wherever it is called, in its own module too. |
153+
| `Validator(symbol, kinds=ALL, argument=0)` | A callable whose truth proves its argument safe for `kinds`, such as `re.fullmatch`. A flow guarded by it is refuted when it carries no other kind into the sink, and is a hotspot otherwise: a redirect validator does not make a shell command safe. `symbol` may be a function of the project, by its project symbol (`python.hc.accounts.views._allow_redirect`), which then counts wherever it is called, in its own module too. |
154154
| `AuthorizationGuard(symbol, label)` | A decorator or a condition restricting who reaches the code, such as `login_required`; a flow behind it is a hotspot. |
155155

156156
Two plugins may describe the same symbol. An identical model is registered once; two

‎src/coretrace_python/findings/refutation.py‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@
6060
TaintAnalysis,
6161
TaintFacts,
6262
TaintFlow,
63+
TaintKind,
6364
)
6465

6566
VALIDATORS = frozenset(
@@ -219,15 +220,16 @@ def guards(self, sink: BlockId) -> list[_Guard]:
219220

220221
def interpret(
221222
self, condition: Value, truth: bool | None
222-
) -> tuple[dict[Value, str], set[Value]]:
223-
"""Values the condition proves safe (with the reason), and values it mentions
224-
without proving anything. ``truth`` is ``None`` when it is not fixed at the sink.
223+
) -> tuple[dict[Value, tuple[str, TaintKind]], set[Value]]:
224+
"""Values the condition proves safe (with the reason and the kinds it proves them
225+
safe for), and values it mentions without proving anything. ``truth`` is ``None``
226+
when it is not fixed at the sink.
225227
226228
A recognised check evaluated the wrong way (``isdigit()`` known false) yields
227229
nothing: it is neither a proof nor a reassuring guard."""
228230

229231
definition = self.defs.get(condition)
230-
proven: dict[Value, str] = {}
232+
proven: dict[Value, tuple[str, TaintKind]] = {}
231233
mentioned: set[Value] = set()
232234
if isinstance(definition, UnaryOp) and definition.operator == "not":
233235
return self.interpret(definition.operand, None if truth is None else not truth)
@@ -241,39 +243,42 @@ def interpret(
241243
recognised = self.recognise(definition)
242244
if recognised is None:
243245
return proven, set(self.closure(condition)) | {condition}
244-
tested, reason, when_true = recognised
246+
tested, reason, when_true, kinds = recognised
245247
if truth is None:
246248
mentioned = set(self.closure(condition)) | {condition}
247249
elif truth == when_true:
248250
# The check proves ``tested``; whatever else it reads is merely mentioned.
249-
proven[tested] = reason
251+
proven[tested] = (reason, kinds)
250252
mentioned = set(self.closure(condition)) | {condition}
251253
return proven, mentioned
252254

253-
def recognise(self, definition: Instruction | None) -> tuple[Value, str, bool] | None:
254-
"""``(validated value, reason, truth that validates)`` for known check shapes."""
255+
def recognise(self, definition: Instruction | None) -> tuple[Value, str, bool, TaintKind] | None:
256+
"""``(validated value, reason, truth that validates, kinds it proves)`` for known
257+
check shapes. A string check, a constant allowlist or an equality with a constant
258+
proves every kind; a ``Validator`` only the kinds it declares."""
255259

256260
if isinstance(definition, Call) and not definition.arguments:
257261
callee = self.defs.get(definition.callee)
258262
if isinstance(callee, GetAttr) and callee.attribute in VALIDATORS:
259-
return callee.object, f"guarded by {callee.attribute}()", True
263+
return callee.object, f"guarded by {callee.attribute}()", True, TaintKind.ALL
260264
if isinstance(definition, Call):
261265
symbol = self.symbols.get(definition.callee)
262266
validator = self.models.validator(symbol) if symbol is not None else None
263267
if validator is not None and validator.argument < len(definition.arguments):
264-
return definition.arguments[validator.argument], f"validated by {symbol}", True
268+
return definition.arguments[validator.argument], f"validated by {symbol}", True, validator.kinds
265269
if isinstance(definition, Compare):
266270
left, right = definition.left, definition.right
267271
if definition.operator in ("in", "not_in") and self.is_constant_collection(right):
268272
return (
269273
left,
270274
"allowlisted by a membership check on constants",
271275
definition.operator == "in",
276+
TaintKind.ALL,
272277
)
273278
if definition.operator in ("eq", "not_eq"):
274279
for tested, other in ((left, right), (right, left)):
275280
if isinstance(self.defs.get(other), Constant):
276-
return tested, "equals a constant", definition.operator == "eq"
281+
return tested, "equals a constant", definition.operator == "eq", TaintKind.ALL
277282
return None
278283

279284
def examined(
@@ -392,8 +397,9 @@ def judge(self, flow: TaintFlow, reachable: bool) -> Verdict:
392397
)
393398
for guard in self.guards(sink):
394399
found, mentioned = self.interpret(guard.condition, guard.truth)
395-
for value, reason in found.items():
396-
if value in chain:
400+
for value, (reason, kinds) in found.items():
401+
# A check proving some kinds only leaves the others reaching the sink.
402+
if value in chain and not flow.kinds & ~kinds:
397403
proven.setdefault(value, reason)
398404
examined = self.examined(guard.condition, mentioned, flow.argument, chain)
399405
for origin in origins:

‎tests/test_project_validators.py‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,10 @@
3232
)
3333

3434

35-
def verdict(*models: Model) -> Status:
35+
def verdict(*models: Model, sink: TaintKind = TaintKind.COMMAND) -> Status:
3636
module = build_hir(SourceManager().add_source("views.py", VIEW))
3737
registry = SecurityModelRegistry()
38-
registry.register(
39-
Source(SymbolId("python.builtins.input"), "stdin"), Sink(SymbolId("python.os.system"), TaintKind.COMMAND), *models
40-
)
38+
registry.register(Source(SymbolId("python.builtins.input"), "stdin"), Sink(SymbolId("python.os.system"), sink), *models)
4139
manager = engine.build_manager(module, registry)
4240
run = next(s for s in module.body if isinstance(s, nodes.Function) and s.name == "run")
4341
(found,) = manager.get(RefutationAnalysis, run).all()
@@ -48,6 +46,18 @@ def test_a_declared_project_validator_refutes_the_flow_it_guards() -> None:
4846
assert verdict(Validator(SymbolId("python.views.allowed"))) is Status.REFUTED
4947

5048

49+
def test_a_validator_proves_only_the_kinds_it_declares() -> None:
50+
# A redirect validator says nothing of what a shell makes of the value.
51+
allowed = SymbolId("python.views.allowed")
52+
53+
assert verdict(Validator(allowed, TaintKind.REDIRECT)) is Status.HOTSPOT
54+
assert verdict(Validator(allowed, TaintKind.COMMAND)) is Status.REFUTED
55+
assert verdict(Validator(allowed, TaintKind.COMMAND), sink=TaintKind.COMMAND | TaintKind.SQL) is Status.HOTSPOT
56+
assert verdict(Validator(allowed, TaintKind.COMMAND | TaintKind.SQL), sink=TaintKind.COMMAND | TaintKind.SQL) is (
57+
Status.REFUTED
58+
)
59+
60+
5161
def test_an_undeclared_project_function_leaves_a_hotspot() -> None:
5262
assert verdict() is Status.HOTSPOT
5363
assert verdict(Validator(SymbolId("python.other.allowed"))) is Status.HOTSPOT

0 commit comments

Comments
 (0)