Rework `S606` (`start-process-with-no-shell`) docs to make clear the security motivations (#13658)

Helps with #13614. This docs rewrite draws on the [documentation for the
original bandit
rule](https://bandit.readthedocs.io/en/latest/plugins/b606_start_process_with_no_shell.html).
This commit is contained in:
Alex Waygood 2024-10-07 13:31:01 +01:00 committed by GitHub
parent 31ca1c3064
commit 27ac34d683
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 18 additions and 12 deletions

View File

@ -191,22 +191,28 @@ impl Violation for StartProcessWithAShell {
/// Checks for functions that start a process without a shell. /// Checks for functions that start a process without a shell.
/// ///
/// ## Why is this bad? /// ## Why is this bad?
/// The `subprocess` module provides more powerful facilities for spawning new /// Invoking any kind of external executable via a function call can pose
/// processes and retrieving their results; using that module is preferable to /// security risks if arbitrary variables are passed to the executable, or if
/// using these functions. /// the input is otherwise unsanitised or unvalidated.
///
/// This rule specifically flags functions in the `os` module that spawn
/// subprocesses *without* the use of a shell. Note that these typically pose a
/// much smaller security risk than subprocesses that are started *with* a
/// shell, which are flagged by [`start-process-with-a-shell`] (`S605`). This
/// gives you the option of enabling one rule while disabling the other if you
/// decide that the security risk from these functions is acceptable for your
/// use case.
/// ///
/// ## Example /// ## Example
/// ```python /// ```python
/// os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg") /// import os
///
///
/// def insecure_function(arbitrary_user_input: str):
/// os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", arbitrary_user_input)
/// ``` /// ```
/// ///
/// Use instead: /// [start-process-with-a-shell]: https://docs.astral.sh/ruff/rules/start-process-with-a-shell/#start-process-with-a-shell-s605
/// ```python
/// subprocess.Popen(["/bin/mycmd", "myarg"])
/// ```
///
/// ## References
/// - [Python documentation: Replacing the `os.spawn` family](https://docs.python.org/3/library/subprocess.html#replacing-the-os-spawn-family)
#[violation] #[violation]
pub struct StartProcessWithNoShell; pub struct StartProcessWithNoShell;
@ -480,7 +486,7 @@ impl From<&Expr> for Safety {
/// ///
/// ## Examples /// ## Examples
/// ```python /// ```python
/// import subprocess /// import os
/// ///
/// os.system("/bin/ls") /// os.system("/bin/ls")
/// os.system("./bin/ls") /// os.system("./bin/ls")