Skip to content

Commit 692b5fa

Browse files
committed
docs: describe the keyword_name condition and key taint
1 parent 303827c commit 692b5fa

3 files changed

Lines changed: 43 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# Changelog
22

3+
## Unreleased
4+
5+
### Advisories
6+
7+
- An advisory condition of kind `keyword_name` says the attacker must choose a keyword name of the call, as Django's ORM takes column aliases and lookups (`annotate(**{alias: expr})`); it carries its text and nothing else. The engine decides it from the keys of what the call expands with `**`, apart from the mapping's values: keys carrying attacker input meet it and the call is exploitable; constant keys, a dict literal with string keys, `dict(total=...)` or plain keywords, contradict it whatever the values carry, so the call is ruled out (`app.views:12 python.app.models.Item.objects.annotate(keywords=total)`, `(keywords absent)` for a call passing no keyword) and a project passing only those stays `not_affected`; keys the engine cannot establish, a `**extra` parameter, a mapping built elsewhere, `dict(zip(...))`, leave it pending review, so the call is reachable, and exploitable when the mapping's values carry input (#193).
8+
9+
### Analysis
10+
11+
- The keys of a mapping carry taint of their own, apart from its values: a dict literal `{alias: expr}`, `dict([(alias, expr)])`, a comprehension `{k: expr for k in input}` and a subscript assignment `mapping[alias] = expr` taint the `keys` location of the mapping's abstract object, which `{**mapping}`, `dict(mapping)` and `dict(**mapping)` copy; the value taint of a literal is what it was. A call expanding such a mapping with `**` passes its keys as the keyword names of the call, a way of passing only an advisory sink reads. Keys through a project wrapper are not followed; `mapping.update(other)`, `mapping.setdefault(k, v)`, `for k in mapping` and `mapping.keys()` carry no key taint; a mapping bound by a `Phi` is unknown (#193).
12+
13+
### Plugins
14+
15+
- `Arguments.keyword_unpacked` says a call expands a `**mapping` whose keys it does not write; a `**` literal with constant keys that nothing else uses is recorded as its keywords, so `given()` decides safe arguments and argument conditions for it. The cache format changes.
16+
317
## 0.19.0 (2026-09-29)
418

519
### Analysis

‎docs/plugins.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,9 @@ A model plugin may also carry `advisories`, a tuple of `Advisory` values
194194
(`coretrace_python.dependency`) with the package, the vulnerable range and the affected
195195
symbols, as the shipped `sample-advisories` plugin does. Requirements matching them are
196196
reported, calls to the affected symbols become reachable vulnerabilities and tainted
197-
calls become exploitable ones.
197+
calls become exploitable ones. An advisory's entry points carry `conditions`, of kind
198+
`argument`, `host`, `semantic` or `keyword_name`, and `attacker_arguments`, decided as
199+
the [usage guide](usage.md) describes.
198200

199201
### Reclassifying findings: `ProjectPlugin.refine`
200202

‎docs/usage.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -488,6 +488,32 @@ attacker's input is passed in that argument. The outcome has three cases:
488488

489489
The other conditions, the environment included, stay pending as before.
490490

491+
A `keyword_name` condition says the attacker must choose a keyword name of the call,
492+
as Django's ORM takes column aliases and lookups (`annotate(**{alias: expr})`):
493+
`{"kind": "keyword_name", "text": "…"}`, and nothing else. The engine decides it from
494+
the keys of what the call expands with `**`; the values of the mapping do not decide
495+
it. The outcome has three cases:
496+
497+
- Keys carrying attacker input meet it, and the call is exploitable. Key taint is
498+
carried, apart from value taint, for a dict literal `{alias: expr}`,
499+
`dict([(alias, expr)])`, a comprehension `{k: expr for k in request.GET}` and a
500+
subscript assignment `mapping[alias] = expr`, and copied by `{**mapping}` and
501+
`dict(mapping)`.
502+
- Constant keys — a dict literal with string keys, `dict(total=…)`, plain keywords —
503+
contradict it, whatever the values carry: the call is ruled out
504+
(`app.views:12 python.app.models.Item.objects.annotate(keywords=total)`, or
505+
`(keywords absent)` for a call passing no keyword), and a project passing only those
506+
stays `not_affected`.
507+
- Keys the engine cannot establish — a `**extra` parameter, a mapping built elsewhere
508+
or returned by a function, `dict(zip(...))`, `**request.GET` — leave it pending
509+
review, as any unknown argument does: the call is reachable, and exploitable when the
510+
mapping's values carry attacker input.
511+
512+
Keys passed through a project wrapper stay pending, and `mapping.update(other)`,
513+
`mapping.setdefault(k, v)`, `for k in mapping` and `mapping.keys()` carry no key
514+
taint. A literal the function fills after building it (`m = {}; m[alias] = expr`)
515+
has keys the literal does not write, so the call is not ruled out.
516+
491517
Every dependency finding records the highest level of evidence established in its
492518
`level` metadata: `declared` (the requirement allows a vulnerable version), `imported`
493519
(a module of the package is imported somewhere), `reachable` (an entry point or affected

0 commit comments

Comments
 (0)