Mercurial > p > roundup > code
annotate doc/tracker_templates.txt @ 8575:b1024bf0d9f7
feature: add nonceless/tokenless CSRF protection
Add tokenless CSRF protection following:
https://words.filippo.io/csrf/
Must be enabled using use_tokenless_csrf_protection in config.ini. By
default it's off. If enabled the older csrf_* settings are ignored.
The allowed_api_origins setting is still used for Origin comparisons.
This should also improve performance as a nonce isn't required so
generating random nonce and saving it to the otks database is
eliminated.
doc/admin_guide.txt, doc/reference.txt doc/upgrading.txt
doc updates.
roundup/configuration.py
add use_tokenless_csrf_protection setting.
move allowed_api_origins directly after
use_tokenless_csrf_protection and before the older csrf_* settings.
It's used by both of them.
Rewrite description of allowed_api_origins as its applied to all
URLs with tokenless protection, not just API URLs.
roundup/anypy/urllib_.py
import urlsplit, it is used in new code.
urlparse() is less efficient and splits params out of the path
component.
Since Roundup doesn't require that params be split from the path. I
expect future patch will replace urlparse() with urlsplit() globally
and not need urlparse().
roundup/cgi/client.py
add handle_csrf_tokenless() and call from handle_csrf() if
use_tokenless_csrf_protection is enabled.
refactor code that expires csrf tokens when used with the wrong
methods (i.e. GET) into expire_exposed_keys(). Call same from
handle_csrf and handle_csrf_tokenless. Also improve logging if this
happens including both Referer and Origin headers if available.
Arguably we dont care about CSRF tokens exposed via
GET/HEAD/OPTIONS in the tokenless case, but this cleans them up in
case the admin has to switch back. At some future date we can
delete all the nonce based CSRF from 2018.
Update handle_csrf() docstring about calling/returning
handle_csrf_tokenless() when enabled. Call
expire_exposed_keys(method) if token is supplied with wrong method.
roundup/cgi/templating.py
disable nonce generation/save and always return "0" when
use_tokenless_csrf_protection enabled.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sun, 19 Apr 2026 20:50:07 -0400 |
| parents | 3614cd64f4c4 |
| children |
| rev | line source |
|---|---|
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
1 ========================= |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
2 Roundup Tracker Templates |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
3 ========================= |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
4 |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
5 The templates distributed with Roundup are stored in the "share" directory |
|
2826
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
6 nominated by Python. On Unix this is typically |
|
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
7 ``/usr/share/roundup/templates/`` (or ``/usr/local/share...``) and |
|
8313
3614cd64f4c4
build: issue2551397: remove support for python 3.6
John Rouillard <rouilj@ieee.org>
parents:
7744
diff
changeset
|
8 on Windows this is ``c:\python38\share\roundup\templates\``. |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
9 |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
10 The template loading looks in four places to find the templates: |
|
2826
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
11 |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
12 1. *share* - eg. ``<prefix>/share/roundup/templates/*``. |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
13 This should be the standard place to find them when Roundup is |
|
6728
f83e19465b70
Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents:
6727
diff
changeset
|
14 installed running setup.py from source. |
|
f83e19465b70
Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents:
6727
diff
changeset
|
15 2. ``install_dir``/../<prefix>/share/....``, where prefix is the |
|
6739
00fe67eb8a91
Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents:
6728
diff
changeset
|
16 Python's ``sys.prefix``. ``sys.base_prefix`` or |
|
00fe67eb8a91
Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents:
6728
diff
changeset
|
17 `sys.base_prefix/local``. This finds templates (and locales) |
|
6728
f83e19465b70
Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents:
6727
diff
changeset
|
18 installed by pip. E.G. in a virtualenv located at (``sys.prefix``): |
|
f83e19465b70
Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents:
6727
diff
changeset
|
19 ``/tools/roundup``, roundup would be at: |
|
8313
3614cd64f4c4
build: issue2551397: remove support for python 3.6
John Rouillard <rouilj@ieee.org>
parents:
7744
diff
changeset
|
20 ``/tools/roundup/lib/python3.7/site-packages/roundup``. The |
|
6728
f83e19465b70
Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents:
6727
diff
changeset
|
21 templates would be at: |
|
8313
3614cd64f4c4
build: issue2551397: remove support for python 3.6
John Rouillard <rouilj@ieee.org>
parents:
7744
diff
changeset
|
22 ``/tools/roundup/lib/python3.7/site-packages/tools/roundup/share/roundup/templates/``. (Replace 3.7 with the Python version you are running.) |
|
6739
00fe67eb8a91
Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents:
6728
diff
changeset
|
23 3. ``<roundup.admin.__file__>/../../share/roundup/templates/*``. |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
24 This will be used if Roundup's run in the distro (aka. source) |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
25 directory. |
|
6728
f83e19465b70
Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents:
6727
diff
changeset
|
26 4. ``<current working dir>/*``. |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
27 This is for when someone unpacks a 3rd-party template. |
|
6728
f83e19465b70
Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents:
6727
diff
changeset
|
28 5. ``<current working dir>``. |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
29 This is for someone who "cd"s to the 3rd-party template dir. |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
30 |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
31 Templates contain: |
|
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
32 |
|
2826
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
33 - modules ``schema.py`` and ``initial_data.py`` |
|
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
34 - directories ``html``, ``detectors`` and ``extensions`` |
|
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
35 (with appropriate contents) |
|
7744
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
36 - optional directory ``lib`` which contains modules used by the other |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
37 tracker components |
|
5762
b76be13e027e
issue2551029: Jinja2 template install error.
John Rouillard <rouilj@ieee.org>
parents:
4557
diff
changeset
|
38 - optional ``config_ini.ini`` file. It is structured like a tracker's |
|
b76be13e027e
issue2551029: Jinja2 template install error.
John Rouillard <rouilj@ieee.org>
parents:
4557
diff
changeset
|
39 ``config.ini`` but contains only headers (e.g. ``[main]``) and |
|
7744
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
40 *required* parameters that are different from defaults. For example:: |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
41 |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
42 [main] |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
43 template_engine = jinja2 |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
44 |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
45 static_files = static |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
46 |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
47 These settings override the default values in the tracker's |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
48 ``config.ini`` when using roundup-admin to install a template. |
|
2826
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
49 - template "marker" file ``TEMPLATE-INFO.txt``, which contains |
|
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
50 the name of the template, a description of the template |
|
eb0015a2caa5
template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents:
2133
diff
changeset
|
51 and its intended audience. |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
52 |
|
7744
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
53 An example TEMPLATE-INFO.txt: |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
54 |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
55 .. code-block:: text |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
56 |
|
7744
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
57 Name: classic |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
58 Description: This is a generic issue tracker that may be used to |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
59 track bugs, feature requests, project issues or any |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
60 number of other types of issues. Most users of |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
61 Roundup will find that this template suits them, |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
62 with perhaps a few customisations. |
|
6985f0ff3df3
doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents:
6739
diff
changeset
|
63 Intended-For: All first-time Roundup users |
|
2133
f01befe8a7fe
*** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff
changeset
|
64 |
