pipe/lines: simplify explanation for need for quotes (#84816)

* do not mention subprocess.Popen, it is an implementation detail
* use "shell injection vulnerability" to describe the problem that is
  well-known, or easily searched for on $search_engine and do not link
  to a 3rd-party site that is also specific to a tool for Python
This commit is contained in:
Martin Krizek
2025-03-12 17:04:31 +01:00
committed by GitHub
parent 4efb01c2f3
commit 9821a4de2f
2 changed files with 10 additions and 10 deletions
+7 -5
View File
@@ -16,14 +16,12 @@ DOCUMENTATION = """
description: command(s) to run
required: True
notes:
- The given commands are passed to a shell for execution, therefore all variables that are part of the commands and
come from a remote/untrusted source MUST be sanitized using the P(ansible.builtin.quote#filter) filter to avoid
shell injection vulnerabilities. See the example section.
- Like all lookups, this runs on the Ansible controller and is unaffected by other keywords such as 'become'.
If you need to use different permissions, you must change the command or run Ansible as another user.
- Alternatively, you can use a shell/command task that runs against localhost and registers the result.
- Lines lookup internally invokes Popen with shell=True (this is required and intentional).
This type of invocation is considered a security issue if appropriate care is not taken to sanitize any user provided or variable input.
It is strongly recommended to pass user input or variable input via quote filter before using with pipe lookup.
See example section for this.
Read more about this L(Bandit B602 docs,https://bandit.readthedocs.io/en/latest/plugins/b602_subprocess_popen_with_shell_equals_true.html)
- The directory of the play is used as the current working directory.
"""
@@ -32,6 +30,10 @@ EXAMPLES = """
ansible.builtin.debug: msg="{{ item }} is an output line from running cat on /etc/motd"
with_lines: cat /etc/motd
- name: Always use quote filter to make sure your variables are safe to use with shell
ansible.builtin.debug: msg="{{ item }} is an output line from running given command"
with_lines: "cat {{ file_name | quote }}"
- name: More useful example of looping over a command result
ansible.builtin.shell: "/usr/bin/frobnicate {{ item }}"
with_lines:
+3 -5
View File
@@ -15,14 +15,12 @@ DOCUMENTATION = r"""
description: command(s) to run.
required: True
notes:
- The given command is passed to a shell for execution, therefore all variables that are part of the command and
come from a remote/untrusted source MUST be sanitized using the P(ansible.builtin.quote#filter) filter to avoid
shell injection vulnerabilities. See the example section.
- Like all lookups this runs on the Ansible controller and is unaffected by other keywords, such as become,
so if you need to different permissions you must change the command or run Ansible as another user.
- Alternatively you can use a shell/command task that runs against localhost and registers the result.
- Pipe lookup internally invokes Popen with shell=True (this is required and intentional).
This type of invocation is considered a security issue if appropriate care is not taken to sanitize any user provided or variable input.
It is strongly recommended to pass user input or variable input via quote filter before using with pipe lookup.
See example section for this.
Read more about this L(Bandit B602 docs,https://bandit.readthedocs.io/en/latest/plugins/b602_subprocess_popen_with_shell_equals_true.html)
- The directory of the play is used as the current working directory.
"""