Skip to content

Commit 69208db

Browse files
committed
docs: describe how a page is put together to read Django templates
The usage guide, the module's docstring and the changelog state how pages are put together, how a name several files have and a template including itself are read, and the bounds on a page.
1 parent 1c692ed commit 69208db

3 files changed

Lines changed: 25 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,14 @@
2020
instead of repeating its id (#270), and each result carries its confidence as the
2121
`confidence` property (#271). A flow reaching its sink inside a project function points at
2222
that sink as a related location, which the result's message links to (#271).
23+
- Django templates are also read as each page is put together (#273): a variable a
24+
child's `{% block %}` prints inside its parent's `<script>`, an `{% include %}` that ends
25+
the attribute value it stands in, or one of a name several files have outside HTML data,
26+
is reported as `xss` where it was not. So is a template that includes Django's
27+
`django/forms/widgets/attrs.html` inside a tag, which prints attribute names, and a
28+
template including itself inside a tag or a script. A page beyond 8 MiB once put
29+
together, or a template with more than 64 pages, or 16 MiB in all, through names
30+
several files have, is not established and is listed in `Coverage.unread_templates`.
2331
- Plugin API, additive: `Plugin.rules` maps the rules a plugin reports to their
2432
`RuleDescription`, optional, so that third-party plugins describe their own rules;
2533
`Finding.related` lists `RelatedLocation`s (a span and a message). `Report.rules` carries the

‎docs/usage.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -213,8 +213,20 @@ ends there and the browser would never run it. A template including one that end
213213
such a block, a tag or an end tag is not established either: the markup after the
214214
include continues it. A template extending another ends where that one ends. A comment
215215
hides what it holds only up to its first template tag, since an include there may close
216-
it and a condition around its `<!--` may leave it out. A `{% block %}` or
217-
`{% include %}` placed inside a parent's `<script>` is not covered yet (#273).
216+
it and a condition around its `<!--` may leave it out.
217+
218+
Each page is also put together as Django renders it, and read once more (#273): the
219+
templates it extends, each block taking the definition of the most derived one and
220+
`{{ block.super }}` the next one up, and each template it includes in place. What a
221+
child's block prints inside its parent's `<script>`, or what an include puts inside an
222+
attribute, is read where it lands. A name several files have, which Django resolves
223+
through loaders the analyzer does not read, counts as each of them: a page extending it
224+
must escape with each file; an include of it is accepted only in HTML data, never inside
225+
an attribute, a tag, a `<script>` or `<style>` block or a comment, and only when each
226+
file ends in HTML data, nothing of it left open. A template including itself is read the
227+
same way. A page beyond 8 MiB once put together, or a template with more than 64 pages,
228+
or 16 MiB in all, through the files the templates it extends may be, is not established,
229+
and is listed among the templates the analyzer could not read.
218230

219231
The analyzer never assumes escaping where it cannot read the template. That covers a
220232
template file it cannot read, a template named by an expression, a template found

‎src/coretrace_python/taint/templates.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@
1414
leaves open, which once included runs into the markup that follows;
1515
- no include of a template that ends inside a ``<script>`` or ``<style>`` block, a tag
1616
or an end tag, which the markup after the include then continues;
17+
- none of this either once the page is put together as Django renders it, its blocks
18+
and includes in place (``_Composition``): what a block or an include puts inside a
19+
construct of another file is read there (#273);
1720
- no Python file of the project turning autoescaping off.
1821
1922
A comment hides what it holds only up to its first template tag: an include there may

0 commit comments

Comments
 (0)