Add notes about module.run_command to coding guidelines.

1 files changed, 20 insertions, 6 deletions

diff --git a/CODING_GUIDELINES.md b/CODING_GUIDELINES.md
index 7860fb2481..1ba5d5035e 100644
--- a/CODING_GUIDELINES.md
+++ b/CODING_GUIDELINES.md
@@ -66,8 +66,10 @@ Functions and Methods
 
   * In general, functions should not be 'too long' and should describe a meaningful amount of work
   * When code gets too nested, that's usually the sign the loop body could benefit from being a function
+  * Parts of our existing code are not the best examples of this at times. 
   * Functions should have names that describe what they do, along with docstrings
   * Functions should be named with_underscores
+  * "Don't repeat yourself" is generally a good philosophy
 
 Variables
 =========
@@ -76,6 +78,15 @@ Variables
   * Ansible python code uses identifiers like 'ClassesLikeThis and variables_like_this
   * Module parameters should also use_underscores and not runtogether
 
+Module Security
+===============
+
+  * Modules must take steps to avoid passing user input from the shell and always check return codes
+  * always use module.run_command instead of subprocess or Popen or os.system -- this is mandatory
+  * if you use need the shell you must pass use_unsafe_shell=True to module.run_command
+  * if you do not need the shell, avoid using the shell
+  * any variables that can come from the user input with use_unsafe_shell=True must be wrapped by pipes.quote(x)
+
 Misc Preferences
 ================
 
@@ -149,16 +160,19 @@ All contributions to the core repo should preserve original licenses and new con
 Module Documentation
 ====================
 
-All module pull requests must include a DOCUMENTATION docstring (YAML format, see other modules for examples) as well as an EXAMPLES docstring, which
-is free form.  
+All module pull requests must include a DOCUMENTATION docstring (YAML format, 
+see other modules for examples) as well as an EXAMPLES docstring, which is free form.  
 
-When adding new modules, any new parameter must have a "version_added" attribute.  When submitting a new module, the module should have a "version_added"
-attribute in the pull request as well, set to the current development version.
+When adding new modules, any new parameter must have a "version_added" attribute.  
+When submitting a new module, the module should have a "version_added" attribute in the 
+pull request as well, set to the current development version.
 
 Be sure to check grammar and spelling.
 
-It's frequently the case that modules get submitted with YAML that isn't valid, so you can run "make webdocs" from the checkout to preview your module's documentation.
-If it fails to build, take a look at your DOCUMENTATION string or you might have a Python syntax error in there too.
+It's frequently the case that modules get submitted with YAML that isn't valid, 
+so you can run "make webdocs" from the checkout to preview your module's documentation. 
+If it fails to build, take a look at your DOCUMENTATION string 
+or you might have a Python syntax error in there too.
 
 Python Imports
 ==============