| msg148710 - (view) |
Author: Alyssa Coghlan (ncoghlan) *  |
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) * |
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: Alyssa Coghlan (ncoghlan) * |
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) * |
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) * |
Date: 2011-12-01 13:14 |
| I agree 100% with Ezio here. |
|
|
| msg148720 - (view) |
Author: Alyssa Coghlan (ncoghlan) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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 . 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: Alyssa Coghlan (ncoghlan) * |
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) * |
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) * |
Date: 2013-05-07 13:11 |
| Patch looks fine to me. |
|
|
| msg188658 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
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)  |
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 |
|
|
