From 5d2a4ebc99ba2459da5f7b208abb11ba8e533ae5 Mon Sep 17 00:00:00 2001
From: Tom Kuson <mail@tjkuson.me>
Date: Mon, 7 Aug 2023 04:48:36 +0100
Subject: [PATCH] Add documentation to `subprocess-with[out]-shell-equals-true`
 rules (#6373)

---
 .../flake8_bandit/rules/shell_injection.rs    | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/crates/ruff/src/rules/flake8_bandit/rules/shell_injection.rs b/crates/ruff/src/rules/flake8_bandit/rules/shell_injection.rs
index 2b5715d18d2ad..93e6c0c27ea6a 100644
--- a/crates/ruff/src/rules/flake8_bandit/rules/shell_injection.rs
+++ b/crates/ruff/src/rules/flake8_bandit/rules/shell_injection.rs
@@ -10,6 +10,31 @@ use crate::{
     checkers::ast::Checker, registry::Rule, rules::flake8_bandit::helpers::string_literal,
 };
 
+/// ## What it does
+/// Check for method calls that initiate a subprocess with a shell.
+///
+/// ## Why is this bad?
+/// Starting a subprocess with a shell can allow attackers to execute arbitrary
+/// shell commands. Consider starting the process without a shell call and
+/// sanitize the input to mitigate the risk of shell injection.
+///
+/// ## Example
+/// ```python
+/// import subprocess
+///
+/// subprocess.run("ls -l", shell=True)
+/// ```
+///
+/// Use instead:
+/// ```python
+/// import subprocess
+///
+/// subprocess.run(["ls", "-l"])
+/// ```
+///
+/// ## References
+/// - [Python documentation: `subprocess` — Subprocess management](https://docs.python.org/3/library/subprocess.html)
+/// - [Common Weakness Enumeration: CWE-78](https://cwe.mitre.org/data/definitions/78.html)
 #[violation]
 pub struct SubprocessPopenWithShellEqualsTrue {
     seems_safe: bool,
@@ -28,6 +53,30 @@ impl Violation for SubprocessPopenWithShellEqualsTrue {
     }
 }
 
+/// ## What it does
+/// Check for method calls that initiate a subprocess without a shell.
+///
+/// ## Why is this bad?
+/// Starting a subprocess without a shell can prevent attackers from executing
+/// arbitrary shell commands; however, it is still error-prone. Consider
+/// validating the input.
+///
+/// ## Known problems
+/// Prone to false positives as it is difficult to determine whether the
+/// passed arguments have been validated ([#4045]).
+///
+/// ## Example
+/// ```python
+/// import subprocess
+///
+/// cmd = input("Enter a command: ").split()
+/// subprocess.run(cmd)
+/// ```
+///
+/// ## References
+/// - [Python documentation: `subprocess` — Subprocess management](https://docs.python.org/3/library/subprocess.html)
+///
+/// [#4045]: https://github.com/astral-sh/ruff/issues/4045
 #[violation]
 pub struct SubprocessWithoutShellEqualsTrue;