[issue13515] Consistent documentation practices for security concerns and considerations
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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Changes by Ezio Melotti ezio.melo...@gmail.com: -- assignee: docs@python - ezio.melotti resolution: - fixed stage: commit review - committed/rejected status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Changes by Ezio Melotti ezio.melo...@gmail.com: -- stage: patch review - commit review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Antoine Pitrou added the comment: Patch looks fine to me. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Changes by Ezio Melotti ezio.melo...@gmail.com: -- nosy: +christian.heimes type: - enhancement ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Ezio Melotti ezio.melo...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Changes by Tshepang Lekhonkhobe tshep...@gmail.com: -- nosy: +tshepang ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Ezio Melotti ezio.melo...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Antoine Pitrou pit...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Georg Brandl ge...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Antoine Pitrou pit...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Ezio Melotti ezio.melo...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Changes by Ezio Melotti ezio.melo...@gmail.com: Added file: http://bugs.python.org/file23843/warnnew.png ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Changes by Ezio Melotti ezio.melo...@gmail.com: Added file: http://bugs.python.org/file23844/warnold.png ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Antoine Pitrou pit...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Georg Brandl ge...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Raymond Hettinger raymond.hettin...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Ezio Melotti ezio.melo...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Nick Coghlan ncogh...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Ezio Melotti ezio.melo...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Antoine Pitrou pit...@free.fr added the comment: I agree 100% with Ezio here. -- nosy: +pitrou ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
Nick Coghlan ncogh...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13515] Consistent documentation practices for security concerns and considerations
New submission from Nick Coghlan ncogh...@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 rep...@bugs.python.org http://bugs.python.org/issue13515 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
