[issue13515] Consistent documentation practices for security concerns and considerations
New submission from Nick Coghlan <ncoghlan@gmail.com>: 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) ---------- assignee: docs@python components: Documentation messages: 148710 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Consistent documentation practices for security concerns and considerations _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: 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). ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment: I agree 100% with Ezio here. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Georg Brandl <georg@python.org> added the comment: Please propose a concrete new styling for the warnings; I think that should be done regardless of the other points. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Also consider writing a security howto guide so that the docs don't become littered with warnings. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment: For the record, the SSL module has a separate security considerations section: http://docs.python.org/dev/library/ssl.html#security-considerations ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Attached a patch to make the CSS used for warnings and notes less evident by removing the red/gray background color. ---------- keywords: +patch Added file: http://bugs.python.org/file23842/issue13515.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: Added file: http://bugs.python.org/file23843/warnnew.png _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: Added file: http://bugs.python.org/file23844/warnold.png _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Antoine Pitrou <pitrou@free.fr> added the comment:
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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment:
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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Georg Brandl <georg@python.org> added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: The new theme of the docs should solve the issue about the scary red boxes, but the original report is still valid. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +christian.heimes type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Ezio Melotti added the comment: 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. ---------- components: +Devguide -Documentation stage: needs patch -> patch review Added file: http://bugs.python.org/file30092/issue13515-devguide.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- stage: patch review -> commit review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Nick Coghlan added the comment: 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) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
R. David Murray added the comment: Probably. Otherwise people are going to go look at the subprocess docs as an example...and they don't follow it. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Antoine Pitrou added the comment: Patch looks fine to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Ezio Melotti added the comment: We could use the SSL docs[0] as example instead of subprocess. [0]: http://docs.python.org/3/library/ssl.html#security-considerations ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Roundup Robot added the comment: New changeset 8bb5f4301e01 by Ezio Melotti in branch 'default': #13515: document security-related documentation practices. http://hg.python.org/devguide/rev/8bb5f4301e01 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: commit review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13515> _______________________________________
participants (9)
-
Antoine Pitrou -
Ezio Melotti
-
Georg Brandl
-
Nick Coghlan
-
R. David Murray
-
Raymond Hettinger
-
Roundup Robot
-
Tshepang Lekhonkhobe
-
Éric Araujo