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.
///
/// ## Why is this bad?
/// The `subprocess` module provides more powerful facilities for spawning new
/// processes and retrieving their results; using that module is preferable to
/// using these functions.
/// Invoking any kind of external executable via a function call can pose
/// security risks if arbitrary variables are passed to the executable, or if
/// 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
/// ```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:
/// ```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)
/// [start-process-with-a-shell]: https://docs.astral.sh/ruff/rules/start-process-with-a-shell/#start-process-with-a-shell-s605
#[violation]
pub struct StartProcessWithNoShell;
@ -480,7 +486,7 @@ impl From<&Expr> for Safety {
///
/// ## Examples
/// ```python
/// import subprocess
/// import os
///
/// os.system("/bin/ls")
/// os.system("./bin/ls")