classification
Title: Consistent documentation practices for security concerns and considerations
Type: enhancement Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: christian.heimes, docs@python, eric.araujo, ezio.melotti, georg.brandl, ncoghlan, pitrou, python-dev, r.david.murray, rhettinger, tshepang
Priority: normal Keywords: patch

Created on 2011-12-01 07:53 by ncoghlan, last changed 2013-10-21 00:14 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue13515.diff ezio.melotti, 2011-12-03 18:14 Patch to make the CSS of warnings and notes less evident.
warnnew.png ezio.melotti, 2011-12-03 18:14 Screenshot with the new CSS
warnold.png ezio.melotti, 2011-12-03 18:14 Screenshot with the old CSS
issue13515-devguide.diff ezio.melotti, 2013-05-01 12:44
Messages (22)
msg148710 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-12-01 07:53
This issue proposes that we adopt and apply some standard practices when documenting modules that have potential security implications and other cross-cutting errors that may affect multiple interfaces within the module.

Accordingly, the main target is the "Documenting Python" meta-docs, proposing the addition of a new subsection to the Style Guide, with an update to the subprocess module documentation serving as the exemplar of a new recommended style:

======================
2.6 Security Considerations (and Other Concerns)
------------------------------------------------

Some modules provided with Python are inherently exposed to security issues (e.g. shell injection vulnerabilities) due to the purpose of the module (e.g. subprocess invocation). Littering the documentation of these modules with red warning boxes for problems that are due to the task at hand, rather than specifically to Python's support for that task, doesn't make for a good reading experience.

Instead, these security concerns should be gathered into a dedicated "Security Considerations" section within the module's documentation, and cross-referenced from the documentation of affected interfaces with in-line text similar to "Please refer to the :ref:`security-considerations` section for important information on how to avoid common mistakes".

Similarly, if there is a common error that affects many interfaces in a module (e.g. OS level pipe buffers filling up and stalling child processes), these can be documented in a "Common Errors" section and cross-referenced rather than repeated for every affected interface.
======================


(based on the thread at http://mail.python.org/pipermail/python-dev/2011-December/114717.html)
msg148711 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-01 08:10
Grouping the common warnings in a "Security Considerations" section sounds OK, but the warnings should still be visible IMHO.

In my experience, people:
 1) jump right to the doc for the function they are using;
 2) read the example and try to figure out how it works;
 3) if that fails, they read the text.

An inline text with a simple link might then pass unnoticed.  OTOH littering the doc with red boxes is far too noticeable.  Maybe we should use something in between (e.g. a "lighter" CSS for the warnings or a small warning icon).
msg148717 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-12-01 11:46
While I acknowledge the point (it's the reason I *didn't* remove those warnings in my recent major update to the subprocess docs), Raymond's right that scattering warnings everywhere in the docs for modules like subprocess isn't the right answer either. For a lot of things people use those modules for (i.e. private scripts with no untrusted user input) the warnings are excessive.

There's only so much we can do to protect novice programmers being given tasks beyond their experience, and only so much readability we should sacrifice in the name of educating people about general programming issues that aren't specific to Python.
msg148718 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-01 12:12
I think we are mixing a few different things here:
1) the content of the warning(s);
2) the position of the warning(s);
3) the style of the warning(s);

Duplicating the same content in each warning is bad, so a specific section that summarizes the problem is good.
Having at least a note with a link to the "Security consideration" section in each affected function is good too, because without them people won't notice it.
Having big red scary boxes is bad, because people are scared of big red things (especially scary ones), and our goal here is to warn, not to scare.

I think the problem with the subprocess doc is that there are many warnings and that they are big and red (and scary).  IMHO changing the style of the warning would already be a step forward the "clean look" advocated by Raymond.  Grouping redundant text and possibly rephrasing it a bit would do the rest.
msg148719 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-12-01 13:14
I agree 100% with Ezio here.
msg148720 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-12-01 13:37
Yep, using notes rather than simple inline links would also be fine with me. So, with "in-line text" changed to "a ReST note", what do people otherwise think about the proposed style guide addition?
msg148775 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-12-02 21:32
Please propose a concrete new styling for the warnings; I think that should be done regardless of the other points.
msg148777 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-12-02 21:47
Also consider writing a security howto guide so that the docs don't become littered with warnings.
msg148811 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-12-03 17:16
For the record, the SSL module has a separate security considerations section:
http://docs.python.org/dev/library/ssl.html#security-considerations
msg148813 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-03 18:14
Attached a patch to make the CSS used for warnings and notes less evident by removing the red/gray background color.
msg148814 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-12-03 18:18
> Attached a patch to make the CSS used for warnings and notes less
> evident by removing the red/gray background color.

This really years for an icon, IMO. A bit more indenting would be good,
too, so that it stands out clearly from the rest of the text.
msg149171 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-12-10 16:45
Note sure about icon vs. text (“Warning:”) vs. colors.  I think an icon would be as scary as the current big color boxes.  I like Ezio’s change + Antoine’s indenting suggestion.
msg149174 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-10 17:35
> I think an icon would be as scary as the current big color boxes.
Especially if I design it.

Georg, is the patch ok if I add a bit of indentation as suggested by Antoine?
msg149177 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-12-10 17:59
> Note sure about icon vs. text (“Warning:”) vs. colors.  I think an
> icon would be as scary as the current big color boxes.  I like Ezio’s
> change + Antoine’s indenting suggestion.

An icon will only be scary if you chopse a scary one. A "warning" icon
can simply be an exclamation mark or something (*). It would be less
prominent than a box with a red background, while still clearly
separating the warning from the rest of the text (something which a too
small indentation does not).

Icons or drawings also make text documents less austere, which is a good
thing. There are lots of free icon sets out there, so Ezio doesn't have
to train his art skills ;)

(*) to get an idea, search "exclamation mark icon" with Google Images
msg149178 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-12-10 18:43
I don't really like the combination of the left bar and the background color.  What about making the left bar thicker, and leaving out the background color?
msg163056 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-06-17 11:33
The new theme of the docs should solve the issue about the scary red boxes, but the original report is still valid.
msg188215 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-01 12:44
Attached a patch that includes the section proposed by Nick in the first message.  I also changed "in-line text" with "a note" as suggested in msg148720.  I didn't specify a "ReST note" because I think that depending on the situation, an actual warning, a note, or even an in-line text might be acceptable.
msg188645 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-05-07 12:36
The new section looks good to me.

Would it be appropriate to explicitly note that this is a relatively recent change of policy, so most of the stdlib docs don't actually follow it? (and patches to bring them into line would be reasonable)
msg188646 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-05-07 12:49
Probably.  Otherwise people are going to go look at the subprocess docs as an example...and they don't follow it.
msg188647 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-05-07 13:11
Patch looks fine to me.
msg188658 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-07 14:02
We could use the SSL docs[0] as example instead of subprocess.

[0]: http://docs.python.org/3/library/ssl.html#security-considerations
msg200665 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-10-21 00:14
New changeset 8bb5f4301e01 by Ezio Melotti in branch 'default':
#13515: document security-related documentation practices.
http://hg.python.org/devguide/rev/8bb5f4301e01
History
Date User Action Args
2013-10-21 00:14:50ezio.melottisetstatus: open -> closed
assignee: docs@python -> ezio.melotti
resolution: fixed
stage: commit review -> resolved
2013-10-21 00:14:19python-devsetnosy: + python-dev
messages: + msg200665
2013-05-07 14:02:57ezio.melottisetmessages: + msg188658
2013-05-07 13:11:26pitrousetmessages: + msg188647
2013-05-07 12:49:24r.david.murraysetnosy: + r.david.murray
messages: + msg188646
2013-05-07 12:36:49ncoghlansetmessages: + msg188645
2013-05-07 08:26:30ezio.melottisetstage: patch review -> commit review
2013-05-01 12:44:05ezio.melottisetfiles: + issue13515-devguide.diff

messages: + msg188215
components: + Devguide, - Documentation
stage: needs patch -> patch review
2013-02-01 05:25:55ezio.melottisetnosy: + christian.heimes
type: enhancement
2012-06-17 11:33:12ezio.melottisetmessages: + msg163056
2012-06-05 07:55:00tshepangsetnosy: + tshepang
2011-12-10 18:43:12georg.brandlsetmessages: + msg149178
2011-12-10 17:59:33pitrousetmessages: + msg149177
2011-12-10 17:35:39ezio.melottisetmessages: + msg149174
2011-12-10 16:45:41eric.araujosetnosy: + eric.araujo
messages: + msg149171
2011-12-03 18:18:34pitrousetmessages: + msg148814
2011-12-03 18:14:52ezio.melottisetfiles: + warnold.png
2011-12-03 18:14:36ezio.melottisetfiles: + warnnew.png
2011-12-03 18:14:04ezio.melottisetfiles: + issue13515.diff
keywords: + patch
messages: + msg148813
2011-12-03 17:16:21pitrousetmessages: + msg148811
2011-12-02 21:47:50rhettingersetnosy: + rhettinger
messages: + msg148777
2011-12-02 21:32:31georg.brandlsetnosy: + georg.brandl
messages: + msg148775
2011-12-01 13:37:14ncoghlansetmessages: + msg148720
2011-12-01 13:14:46pitrousetnosy: + pitrou
messages: + msg148719
2011-12-01 12:12:50ezio.melottisetmessages: + msg148718
2011-12-01 11:46:57ncoghlansetmessages: + msg148717
2011-12-01 08:10:21ezio.melottisetnosy: + ezio.melotti
messages: + msg148711
2011-12-01 07:53:36ncoghlancreate