Skip to content

Commit e695608

Browse files
authored
Merge pull request #163 from CoreTrace/feat/request-objects
feat: let the text attributes and URL parameters of a request object carry no NOSQL
2 parents 8f0e909 + 4a18850 commit e695608

10 files changed

Lines changed: 271 additions & 34 deletions

File tree

‎CHANGELOG.md‎

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

3+
## Unreleased
4+
5+
### Precision
6+
7+
- The text attributes and URL parameters of a request object carry no `NOSQL`. Django, REST framework, aiohttp and tornado views read a request tainted as a whole, so `request.GET["name"]` and a URL parameter were `nosql-injection` like the body. Now `GET`, `POST`, `COOKIES`, `META`, `headers`, `query_params`, aiohttp's `query` and `match_info`, tornado's `arguments` and the other text attributes are text, and so are the URL parameters a view receives after the request. The body, the files, REST framework's `data` and aiohttp's `json()` keep the kinds of the request. The other kinds are unchanged, and so is the regression corpus. A helper function the request is passed to still reads it as a whole (#162).
8+
9+
### Plugins
10+
11+
- A `RequestObject(symbol, text=())` model says that the inputs from an entry point, a route registrar, a typed parameter or a source are request objects, and which of their attributes are text (#162).
12+
313
## 0.12.0 (2026-09-26)
414

515
### Detection

‎docs/plugins.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,7 @@ class BottleModels(ModelPlugin):
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). |
153153
| `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. |
154+
| `RequestObject(symbol, text=())` | The inputs from `symbol`, an entry point, a route registrar, a typed parameter or a source, are request objects. A view receives the request first (after `self`), then URL parameters, which are text. Reading one of the request's `text` attributes gives text, as Django's `GET` or aiohttp's `query`; its body and files keep the request's kinds. An attribute read counts only when every source of the value is such a request. |
154155
| `AuthorizationGuard(symbol, label)` | A decorator or a condition restricting who reaches the code, such as `login_required`; a flow behind it is a hotspot. |
155156
| `Members(symbol, dynamic=None, defined=(), typed=())` | What the attributes and items of an instance of the class `symbol` give, for objects that give others by name. `typed` maps an attribute to the class of what it gives, called or not, since a call denotes its callee: pymongo's `get_database` gives a `Database`, as Flask-PyMongo's `db` property does. `dynamic`, when set, is the class of every item and of every attribute outside `defined` and `typed`: a pymongo client gives a `Database` by name (`client.shop`, `client["shop"]`), a database a `Collection`. Every path to a collection then denotes the collection class, so a sink on `Collection.find` covers them all. Without `dynamic`, an attribute keeps its path and an item its container's symbol, as for any class. |
156157

‎docs/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ variable is not treated that way yet.
112112
| `command-injection` | Shell or process execution (`os.system`, `subprocess` with a string, …). |
113113
| `code-injection` | The code `eval` or `exec` runs; the globals and locals passed with it are data. `dangerous-eval` reports every such call, this rule the ones attacker input reaches. |
114114
| `sql-injection` | A database statement (`cursor.execute`, SQLAlchemy `text`, Django `raw`, …). Parameters of a parameterised query are not statements. |
115-
| `nosql-injection` | A NoSQL query, such as a MongoDB filter, given attacker input that may hold a structure: a JSON body giving `{"$ne": null}` matches any value. The input that may hold a structure is JSON, the raw bodies a `json.loads` decodes, files, WebSocket messages and standard input. Text cannot hold an operator: form fields, query parameters, headers, cookies, URL parameters, the command line, the environment, and an entry-point parameter annotated with scalars (`str`, `int`, `Optional[str]`, `Annotated[str, Query()]`, `list[str]`, …), which FastAPI validates. Limits: a Django or aiohttp request object is tainted as a whole, so `request.GET` counts like `request.body`; the keys of a dict are not followed, so a string concatenated into `$where` is not reported. The analyzer ships no NoSQL sink: model plugins declare them. |
115+
| `nosql-injection` | A NoSQL query, such as a MongoDB filter, given attacker input that may hold a structure: a JSON body giving `{"$ne": null}` matches any value. The input that may hold a structure is JSON, the raw bodies a `json.loads` decodes, files, WebSocket messages and standard input. Text cannot hold an operator: form fields, query parameters, headers, cookies, URL parameters, the command line, the environment, and an entry-point parameter annotated with scalars (`str`, `int`, `Optional[str]`, `Annotated[str, Query()]`, `list[str]`, …), which FastAPI validates. A Django, REST framework, aiohttp or tornado view reads a request object: its text attributes (`GET`, `POST`, `headers`, `query_params`, `query`, `match_info`, `arguments`, …) and the URL parameters after it are text, its body, files and `data` are not. Limits: a helper function the request is passed to reads it as a whole; the keys of a dict are not followed, so a string concatenated into `$where` is not reported. The analyzer ships no NoSQL sink: model plugins declare them. |
116116
| `path-traversal` | A file system path (`open`, `send_file`, `os.remove`, …). |
117117
| `ssrf` | The URL of an HTTP client request (Requests, httpx, `urllib`), by position or as `url=`; the body, headers and query parameters are not the destination. |
118118
| `xss` | An HTTP response body built without escaping. A Django template rendered by `render_to_string` escapes, where the analyzer can establish it (below). |

‎src/coretrace_python/bundled/models/aiohttp/aiohttp_models.py‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
from coretrace_python.taint import (
1313
EntryPoint,
1414
Model,
15+
RequestObject,
1516
RouteRegistrar,
1617
Sink,
1718
Source,
@@ -22,6 +23,23 @@
2223
_METHODS = ("get", "post", "put", "patch", "delete", "head", "options")
2324
_REQUEST_CLASSES = ("aiohttp.web.Request", "aiohttp.web_request.Request")
2425
_ROUTERS = ("aiohttp.web.Application.router", "aiohttp.web.UrlDispatcher")
26+
# ``@routes.get('/')`` on a ``RouteTableDef``.
27+
_ROUTE_TABLES = tuple(f"aiohttp.web.RouteTableDef.{method}" for method in (*_METHODS, "route", "view"))
28+
# ``app.router.add_route('GET', '/', handler)``, ``app.router.add_get('/', handler)`` and
29+
# ``app.add_routes([web.get('/', handler)])``, each with the argument naming the handler.
30+
_ROUTE_CALLS = (
31+
*((f"{router}.add_route", 2) for router in _ROUTERS),
32+
*((f"{router}.add_{method}", 1) for router in _ROUTERS for method in (*_METHODS, "view")),
33+
("aiohttp.web.route", 2),
34+
*((f"aiohttp.web.{method}", 1) for method in (*_METHODS, "view")),
35+
)
36+
# What a request gives as text; its body (``json()``, ``text()``, ``read()``) may hold a
37+
# structure.
38+
_REQUEST_TEXT = (
39+
"query", "rel_url", "url", "path", "raw_path", "path_qs", "query_string", "match_info", "headers",
40+
"raw_headers", "cookies", "method", "host", "scheme", "remote", "forwarded", "content_type", "charset",
41+
"if_modified_since", "post",
42+
)
2543
_REDIRECTS = ("HTTPFound", "HTTPMovedPermanently", "HTTPSeeOther", "HTTPTemporaryRedirect", "HTTPPermanentRedirect")
2644
_CLIENT_FUNCTIONS = (
2745
*(f"aiohttp.ClientSession.{method}" for method in (*_METHODS, "request")),
@@ -40,18 +58,12 @@ class AiohttpModels(ModelPlugin):
4058
# The whole request is attacker-controlled: its query, match info, headers,
4159
# cookies and body all come from the client.
4260
*(TypedParameter(_sym(cls), "http") for cls in _REQUEST_CLASSES),
43-
# ``@routes.get('/')`` on a ``RouteTableDef``.
44-
*(EntryPoint(_sym(f"aiohttp.web.RouteTableDef.{method}"), "http") for method in (*_METHODS, "route", "view")),
45-
# ``app.router.add_route('GET', '/', handler)`` and ``app.router.add_get('/', handler)``.
46-
*(RouteRegistrar(_sym(f"{router}.add_route"), 2, "http", keyword="handler") for router in _ROUTERS),
61+
*(EntryPoint(_sym(table), "http") for table in _ROUTE_TABLES),
62+
*(RouteRegistrar(_sym(call), argument, "http", keyword="handler") for call, argument in _ROUTE_CALLS),
4763
*(
48-
RouteRegistrar(_sym(f"{router}.add_{method}"), 1, "http", keyword="handler")
49-
for router in _ROUTERS
50-
for method in (*_METHODS, "view")
64+
RequestObject(_sym(symbol), _REQUEST_TEXT)
65+
for symbol in (*_REQUEST_CLASSES, *_ROUTE_TABLES, *(call for call, _ in _ROUTE_CALLS))
5166
),
52-
# ``app.add_routes([web.get('/', handler)])``: the route definitions name the handler.
53-
RouteRegistrar(_sym("aiohttp.web.route"), 2, "http", keyword="handler"),
54-
*(RouteRegistrar(_sym(f"aiohttp.web.{method}"), 1, "http", keyword="handler") for method in (*_METHODS, "view")),
5567
Sink(_sym("aiohttp.web.Response"), TaintKind.HTML),
5668
Sink(_sym("aiohttp.web.FileResponse"), TaintKind.PATH),
5769
*(Sink(_sym(f"aiohttp.web.{exception}"), TaintKind.REDIRECT) for exception in _REDIRECTS),

‎src/coretrace_python/bundled/models/django/django_models.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
AuthorizationGuard,
1818
EntryPoint,
1919
Model,
20+
RequestObject,
2021
RouteRegistrar,
2122
Sanitizer,
2223
Sink,
@@ -88,6 +89,23 @@
8889
)
8990

9091

92+
# What a request object gives as text: the query string, form fields, headers, cookies
93+
# and path. Its body, its files and REST framework's parsed ``data`` may hold a structure.
94+
_REQUEST_TEXT = (
95+
"GET", "POST", "COOKIES", "META", "headers", "path", "path_info", "method", "scheme", "encoding",
96+
"content_type", "content_params", "resolver_match", "get_full_path", "get_full_path_info",
97+
"build_absolute_uri", "get_host", "get_port", "get_signed_cookie", "query_params",
98+
)
99+
# Every input a request object comes from: an annotated parameter, a class-based view's
100+
# method or ``self.request``, a decorated view, a view registered in a URL configuration.
101+
_REQUEST_INPUTS = (
102+
*_REQUEST_CLASSES,
103+
*_VIEW_BASES,
104+
*(f"{base}.request" for base in _VIEW_BASES),
105+
*_VIEW_DECORATORS,
106+
*_ROUTE_REGISTRARS,
107+
)
108+
91109
_TARGET_ONLY = ((TaintKind.REDIRECT, (0,)),)
92110

93111

@@ -103,6 +121,7 @@ class DjangoModels(ModelPlugin):
103121
# ``self.request`` in a class-based view: the attribute is inherited from the base.
104122
*(Source(_sym(f"{base}.request"), "http") for base in _VIEW_BASES),
105123
*(EntryPoint(_sym(decorator), "http") for decorator in _VIEW_DECORATORS),
124+
*(RequestObject(_sym(symbol), _REQUEST_TEXT) for symbol in _REQUEST_INPUTS),
106125
Sink(_sym("django.db.connection.cursor.execute"), TaintKind.SQL | TaintKind.CREDENTIAL, ((TaintKind.SQL, (0,)),)),
107126
Sink(_sym("django.db.connection.cursor.executemany"), TaintKind.SQL | TaintKind.CREDENTIAL, ((TaintKind.SQL, (0,)),)),
108127
Sink(_sym("django.db.models.expressions.RawSQL"), TaintKind.SQL | TaintKind.CREDENTIAL),

‎src/coretrace_python/bundled/models/tornado/tornado_models.py‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,28 @@
88

99
from coretrace_python.plugins import ModelPlugin
1010
from coretrace_python.semantic.symbols import SymbolId
11-
from coretrace_python.taint import TEXT_KINDS, EntryPoint, Model, Sanitizer, Sink, Source, TaintKind
11+
from coretrace_python.taint import (
12+
TEXT_KINDS,
13+
EntryPoint,
14+
Model,
15+
RequestObject,
16+
Sanitizer,
17+
Sink,
18+
Source,
19+
TaintKind,
20+
)
1221

1322
_HANDLERS = ("tornado.web.RequestHandler", "tornado.websocket.WebSocketHandler")
1423
# Text, which cannot hold a query operator; the request object holds the raw body too.
1524
_TEXT_METHODS = (
1625
"get_argument", "get_arguments", "get_query_argument", "get_query_arguments",
1726
"get_body_argument", "get_body_arguments", "get_cookie", "path_args", "path_kwargs",
1827
)
28+
# What ``self.request`` gives as text; its body and files may hold a structure.
29+
_REQUEST_TEXT = (
30+
"arguments", "query_arguments", "body_arguments", "query", "uri", "path", "headers", "cookies",
31+
"method", "host", "host_name", "remote_ip", "protocol", "version", "full_url",
32+
)
1933
_CLIENTS = ("tornado.httpclient.AsyncHTTPClient.fetch", "tornado.httpclient.HTTPClient.fetch")
2034
_TARGET_ONLY = ((TaintKind.REDIRECT, (0,)),)
2135

@@ -33,6 +47,7 @@ class TornadoModels(ModelPlugin):
3347
EntryPoint(_sym("tornado.websocket.WebSocketHandler"), "http"),
3448
*(Source(_sym(f"{handler}.{method}"), "http", TEXT_KINDS) for handler in _HANDLERS for method in _TEXT_METHODS),
3549
*(Source(_sym(f"{handler}.request"), "http") for handler in _HANDLERS),
50+
*(RequestObject(_sym(f"{handler}.request"), _REQUEST_TEXT) for handler in _HANDLERS),
3651
*(Sink(_sym(f"{handler}.write"), TaintKind.HTML) for handler in _HANDLERS),
3752
*(Sink(_sym(f"{handler}.finish"), TaintKind.HTML) for handler in _HANDLERS),
3853
*(Sink(_sym(f"{handler}.redirect"), TaintKind.REDIRECT, _TARGET_ONLY) for handler in _HANDLERS),

‎src/coretrace_python/taint/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
ModelError,
1818
ModelTable,
1919
NamedParameter,
20+
RequestObject,
2021
RouteRegistrar,
2122
SafeArgument,
2223
Sanitizer,
@@ -45,6 +46,7 @@
4546
"ModelTable",
4647
"NamedParameter",
4748
"RegisteredRoutes",
49+
"RequestObject",
4850
"RouteRegistrar",
4951
"Routes",
5052
"SafeArgument",

‎src/coretrace_python/taint/engine.py‎

Lines changed: 39 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@
7474
from coretrace_python.semantic.symbols import SymbolAnalysis, SymbolId, SymbolTable
7575
from coretrace_python.source import SourceSpan
7676
from coretrace_python.taint.models import (
77+
TEXT_KINDS,
7778
EntryPoint,
7879
ModelTable,
7980
SecurityModelAnalysis,
@@ -84,6 +85,9 @@
8485
from coretrace_python.taint.routes import RegisteredRoutes, Routes
8586
from coretrace_python.taint.templates import EscapedTemplates
8687

88+
# What only a structure carries, and text does not.
89+
_STRUCTURED = TaintKind.ALL & ~TEXT_KINDS
90+
8791

8892
@dataclass(frozen=True)
8993
class Taint:
@@ -274,19 +278,42 @@ def instruction(self, instruction: Instruction, state: Mapping[Key, Taint]) -> T
274278
taint = Taint.none()
275279
symbol = self.symbols.get(instruction.result) if instruction.result else None
276280
if symbol is not None:
277-
source = self.models.source_covering(symbol)
278-
if source is not None:
279-
taint = Taint(source.kinds, frozenset({source}))
281+
taint = self.covered(symbol)
280282
if isinstance(instruction, Symbol | Compare):
281283
return taint
282284
for operand in instruction.operands():
283-
taint = taint.join(state.get(operand, Taint.none()))
285+
operand_taint = state.get(operand, Taint.none())
286+
if isinstance(instruction, GetAttr):
287+
operand_taint = self.attribute(operand_taint, instruction.attribute)
288+
taint = taint.join(operand_taint)
284289
if isinstance(instruction, BuildList | BuildTuple | BuildDict | BuildSet):
285290
# ``[*xs]`` and ``{**d}`` copy the contents of what they unpack.
286291
for unpacked in instruction.unpacked:
287292
taint = taint.join(self.deep(unpacked, state))
288293
return taint
289294

295+
def covered(self, symbol: SymbolId) -> Taint:
296+
"""The taint of the source covering ``symbol``, if any. Below a request source, as
297+
``self.request.GET`` is, it is the taint of the request attribute read."""
298+
299+
source = self.models.source_covering(symbol)
300+
if source is None:
301+
return Taint.none()
302+
taint = Taint(source.kinds, frozenset({source}))
303+
if symbol == source.symbol:
304+
return taint
305+
read = symbol.canonical_name.removeprefix(f"{source.symbol.canonical_name}.").split(".")[0]
306+
return self.attribute(taint, read)
307+
308+
def attribute(self, taint: Taint, name: str) -> Taint:
309+
"""What attribute ``name`` of a value carrying ``taint`` carries: text when every
310+
source of the value is a request object listing ``name`` among its text attributes."""
311+
312+
requests = [self.models.request_object(source.symbol) for source in taint.sources]
313+
if taint and all(request is not None and name in request.text for request in requests):
314+
return taint.without(_STRUCTURED)
315+
return taint
316+
290317
def call(self, call: Call, state: dict[Key, Taint], flows: list[TaintFlow]) -> Taint:
291318
arguments = tuple(self.deep(a, state) for a in call.arguments)
292319
keywords = Taint.none()
@@ -420,11 +447,7 @@ def external(
420447
if cleared:
421448
return everything.without(TaintKind(cleared))
422449
# A method on a tainted object returns tainted data (``request.args.get``).
423-
everything = everything.join(state.get(call.callee, Taint.none()))
424-
source = self.models.source_covering(symbol)
425-
if source is not None:
426-
return everything.join(Taint(source.kinds, frozenset({source})))
427-
return everything
450+
return everything.join(state.get(call.callee, Taint.none())).join(self.covered(symbol))
428451

429452
def guarded(self, sink: Sink | None, arguments: Arguments) -> Sink | None:
430453
"""The sink as this call makes it: an argument declared safe (``yaml.load`` with
@@ -777,7 +800,8 @@ def parameter_sources(
777800
entry point (``self`` excepted for a method), including one registered elsewhere
778801
(``routes``), and every parameter annotated with a typed-parameter symbol. An entry
779802
point's parameter annotated with scalars is text: FastAPI validates it before the
780-
handler runs, and a scalar cannot hold a query operator."""
803+
handler runs, and a scalar cannot hold a query operator. So are the URL parameters
804+
a view receives after a request object."""
781805

782806
owner = _owner(module, function)
783807
sources: dict[int, Source] = {}
@@ -786,10 +810,13 @@ def parameter_sources(
786810
entry = function_entry_point(function, module, models, scopes, symbols, instances, routes)
787811
if entry is not None:
788812
first = 1 if owner is not None else 0
813+
request = models.request_object(entry.symbol)
789814
for index in range(first, len(function.parameters)):
790815
annotation = function.parameters[index].annotation
791-
scalar = annotation is not None and _scalar(annotation, symbols, enclosing)
792-
kinds = entry.kinds & ~TaintKind.NOSQL if scalar else entry.kinds
816+
text = (request is not None and index > first) or (
817+
annotation is not None and _scalar(annotation, symbols, enclosing)
818+
)
819+
kinds = entry.kinds & ~_STRUCTURED if text else entry.kinds
793820
sources[index] = Source(entry.symbol, entry.label, kinds)
794821
for index, parameter in enumerate(function.parameters):
795822
if parameter.annotation is None:

0 commit comments

Comments
 (0)