Skip to content

Commit dd5aebc

Browse files
patchback[bot]jborean93Akasurdesamccann
authored
Document Windows App Control Feature (#2654) (#2929)
* Add documentation for App Control for Windows * Update script for better Python detection * Another passthrough and update script * Linting fixes * Update docs/docsite/rst/os_guide/windows_app_control.rst * Remove inlined script in favour of hyperlink * Update docs/docsite/rst/os_guide/windows_app_control.rst * Fix up from review comments * Try and fix admonition content block * Use github URL for PowerShell script --------- (cherry picked from commit 4f63297) Co-authored-by: Jordan Borean <[email protected]> Co-authored-by: Abhijeet Kasurde <[email protected]> Co-authored-by: Sandra McCann <[email protected]>
1 parent 9942d1c commit dd5aebc

File tree

3 files changed

+563
-0
lines changed

3 files changed

+563
-0
lines changed

‎docs/docsite/rst/os_guide/intro_windows.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ This is an index of all the topics covered in this guide.
1313
.. toctree::
1414
:maxdepth: 1
1515

16+
windows_app_control
1617
windows_dsc
1718
windows_performance
1819
windows_ssh
@@ -161,6 +162,8 @@ While not all connection plugins require the connection user to be a member of t
161162
Learning Ansible's configuration management language
162163
:ref:`developing_modules`
163164
How to write modules
165+
:ref:`windows_app_control`
166+
Using Ansible with Windows App Control managed hosts
164167
:ref:`windows_dsc`
165168
Using Ansible with Windows Desired State Configuration
166169
:ref:`windows_performance`

‎docs/docsite/rst/os_guide/windows_app_control.rst

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
.. _windows_app_control:
2+
3+
Windows App Control
4+
===================
5+
`Windows App Control <https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/>`_, formerly known as Windows Defender Application Control (``WDAC``), is a security feature of Windows that can be used to restrict what executables and scripts can be run on a Windows host. In the past, enabling WDAC will cause Ansible to fail when running on the Windows host. Starting with Ansible 2.19 and the ``ansible.windows`` collection at ``3.1.0``, Ansible can now run on Windows hosts with WDAC enabled.
6+
7+
.. admonition:: Experimental functionality
8+
9+
The App Control implementation is considered an experimental feature and can change in future releases. It is not possible to ensure all PowerShell modules will work with App Control enabled and that a module might enable arbitrary code to run in a way not typically allowed by App Control. It is recommended to test all modules with WDAC enabled before using them in production.
10+
11+
.. contents::
12+
:local:
13+
14+
Requirements for Ansible to work with App Control
15+
-------------------------------------------------
16+
Ansible requires the target Windows version to be Windows Server 2019 or Windows 10 Build 1803 or later. This is because the ``Dynamic Code Security`` feature added in that Windows version is required to allow Ansible to run tasks on the Windows host.
17+
18+
The first step towards enabling App Control is to create a code signing certificate that will be used to sign the scripts used by Ansible. While this certificate can be self signed, it is recommended that it is issued by a trusted certificate authority used in your organization. How to generate this certificate is outside the scope of this documentation. Once the certificate is setup, the policy file must be generated and applied to the Windows host.
19+
20+
Setting up App Control and configuring policies is not covered under the documentation here. Please read through the Microsoft documentation for `Application Control for Windows <https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/>`_ or `Application Control with PowerShell <https://learn.microsoft.com/en-us/powershell/scripting/security/app-control/how-to-use-app-control?view=powershell-7.5>`_ to understand how to configure App Control and set up policies. The `App Control for Business Wizard <https://learn.microsoft.com/en-us/windows/security/application-security/application-control/app-control-for-business/design/appcontrol-wizard>`_ is a tool that can simplify policy generation through a more user friendly GUI.
21+
22+
When setting up a policy it is recommended to configure Ansible as a supplemental policy so it can be easily modified and applied where Ansible will be used. Whether you use a supplemental or just a base policy for trusting the certificate used by Ansible, the base policy must have the following options set:
23+
24+
* User Mode Code Integrity (``0 Enabled:UMCI``) is enabled
25+
* Disable Script Enforcement (``11 Disabled:Script Enforcement``) is not enabled
26+
* Dynamic Code Security (``19 Enabled:Dynamic Code Security``) is enabled
27+
28+
The policy then should then add the certificate as a trusted publisher to the ``User Mode Signing Scenario``, for example this is an example policy configuration that contains a trusted publisher:
29+
30+
.. code-block:: text
31+
32+
<SiPolicy>
33+
...
34+
<Signers>
35+
<Signer Name="Some Signer" ID="ID_SIGNER_S_0">
36+
<CertRoot Type="TBS" Value="1DBF60AFC6313593EDB09B6C6239BE493FF3461D4BD6D0A8C6E1723A12C06438F471BB7F6BAA73BD142D0698CEFF9DBB" />
37+
<CertPublisher Value="Some Publisher" />
38+
</Signer>
39+
</Signers>
40+
<SigningScenarios>
41+
<SigningScenario ID="ID_SIGNINGSCENARIO_KMCI" FriendlyName="Kernel Mode Signing Scenario" Value="131">
42+
<ProductSigners />
43+
</SigningScenario>
44+
<SigningScenario ID="ID_SIGNINGSCENARIO_UMCI" FriendlyName="User Mode Signing Scenario" Value="12">
45+
<ProductSigners>
46+
<AllowedSigners>
47+
<AllowedSigner SignerId="ID_SIGNER_S_0" />
48+
</AllowedSigners>
49+
</ProductSigners>
50+
</SigningScenario>
51+
</SigningScenarios>
52+
...
53+
</SiPolicy>
54+
55+
Once the policy is created and the certificate that will be used to sign the Ansible content is trusted by the Windows host, the policy can be applied.
56+
57+
.. Warning::
58+
As Ansible typically runs tasks as an Administrator, it is important that the policy is signed and is applied so that Ansible cannot unset the policy through a task like ``win_file`` or ``win_regedit``.
59+
60+
How to Sign Ansible Content
61+
---------------------------
62+
Once the code signing certificate has been generated and trusted by the Windows host, it can be used to sign the scripts that Ansible will run. The PowerShell script `New-AnsiblePowerShellSignature.ps1 <https://raw.githubusercontent.com/ansible/ansible-documentation/refs/heads/devel/examples/scripts/New-AnsiblePowerShellSignature.ps1>`_ can be used to sign both the execution wrapper used by Ansible to invoke modules and any PowerShell modules inside an Ansible collection. It requires the following to run:
63+
64+
* PowerShell 7.4 or later
65+
* The `OpenAuthenticode <https://github.com/jborean93/PowerShell-OpenAuthenticode>`_ PowerShell module
66+
* Python with Ansible and the required collections installed
67+
* Access to the certificate and private key trusted by the App Control policy, typically as a PFX file
68+
69+
.. note::
70+
The ``New-AnsiblePowerShellSignature`` function is not officially supported and is marked as a tech preview.
71+
72+
To sign the Ansible PowerShell wrapper scripts, and modules in a collection, the following PowerShell script can be used with the loaded function from above:
73+
74+
.. code-block:: powershell
75+
76+
$certPassword = Read-Host "Enter the password for the certificate" -AsSecureString
77+
$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new(
78+
"wdac-cert.pfx"
79+
$certPassword)
80+
81+
$signingParams = @{
82+
Certificate = $cert
83+
84+
Collection = @(
85+
# Includes all the builtin execution wrappers and scripts needed for Ansible
86+
'ansible.builtin'
87+
88+
# Add any remaining collections used in the playbook like microsoft.ad, community.windows, etc.
89+
'ansible.windows'
90+
'microsoft.ad'
91+
'microsoft.iis'
92+
'community.windows'
93+
)
94+
95+
# The URL of the Authenticode timestamp server to use for timestamping
96+
# the signature.
97+
# https://learn.microsoft.com/en-us/windows/win32/seccrypto/time-stamping-authenticode-signatures
98+
TimeStampServer = '...'
99+
}
100+
New-AnsiblePowerShellSignature @signingParams -Verbose
101+
102+
The ``ansible.builtin`` collection refers to the builtin execution scripts used in Ansible. Any other collection with PowerShell modules used in the playbook should be added to the ``-Collection`` parameter. The script will generate the ``powershell_signatures.psd1`` script signed by the certificate and contains the hashes of all the modules in the collection that should be trusted to run. It will also generate the signature for Ansible's execution wrapper script in the Ansible installation directory so that Ansible can automatically run the script trusted by the App Control policy. The current behavior of ``New-AnsiblePowerShellSignature`` is to sign all the modules in the collection and the Ansible execution wrapper script even if they could include an escape hatch. It is recommended to skip any modules using the ``-Skip`` parameter that are not needed in the playbook, for example:
103+
104+
.. code-block:: powershell
105+
106+
New-AnsiblePowerShellSignature ... -Skip @(
107+
'ansible.windows.win_dsc'
108+
'ansible.windows.win_timezone'
109+
)
110+
111+
Any PowerShell content that is not part of a collection, like custom scripts or code used in ``ansible.windows.win_powershell``, must be signed manually using the ``Set-AuthenticodeSignature`` cmdlet on Windows or ``Set-OpenAuthenticodeSignature`` through ``OpenAuthenticode`` module on Linux. It is important that these signed scripts are used in a way that will not modify the contents of the script or else the signature will be invalidated. For example the ``ansible.builtin.script`` module will copy the script file to the target host as is leaving the signature intact but using the ``ansible.builtin.file`` lookup will strip any remaining newline characters unless the ``rstrip=False`` option is used.
112+
113+
Known Module Differences
114+
------------------------
115+
When App Control is enabled, some modules may not work, or behave differently, even if signed. Some of the known differences are:
116+
117+
* ``ansible.windows.win_command`` can only execute executables trusted by the App Control policy. If the executable is not trusted, the module will fail
118+
* ``ansible.windows.win_shell`` will run all code in Constrained Language Mode (``CLM``) which is highly restricted and may cause some scripts to fail
119+
* ``ansible.windows.win_powershell`` will run in CLM by default unless the provided script is signed
120+
* ``ansible.builtin.script`` will run in CLM by default unless the provided script is signed
121+
* ``ansible.windows.win_package`` can only run executables trusted by the App Control policy so may or may not work depending on the executable
122+
* ``ansible.windows.win_updates`` is currently not supported and will not work
123+
124+
Other modules that start sub-processes or rely on unsigned PowerShell content will most likely not work with App Control enabled.
125+
126+
If trying to run a PowerShell script with ``ansible.windows.win_powershell`` or ``ansible.builtin.script``, the script itself must be signed or else it will be run in CLM.
127+
128+
.. code-block:: yaml
129+
130+
- name: Test out LanguageMode
131+
ansible.windows.win_powershell:
132+
script: $ExecutionContext.SessionState.LanguageMode
133+
134+
It is important that when referencing a signed script that the script is not modified in any way. This means the line endings and whitespace that were present when it was signed must be the same when Ansible uses the signed script.
135+
136+
.. note::
137+
Ansible will always load the script with the UTF-8 encoding even if no Byte Order Mark (``BOM``) is present. It is important that the script was encoded with UTF-8 without a BOM when it was signed so that the signature stays valid. If the script was signed with a different encoding, the signature could be invalidated or PowerShell may interpret it with different characters.
138+
139+
When referencing a signed script in Ansible, it is important that it is used in a way that does not modify the contents of the script which would break the signature. For example you should have the signed script in the local ``files`` directory associated with the playbook/tasks and reference in one of the following ways:
140+
141+
.. code-block:: yaml
142+
143+
- name: Run signed script through the script module
144+
ansible.builtin.script: signed-script.ps1
145+
146+
- name: Run signed script through win_powershell as a path
147+
ansible.windows.win_powershell:
148+
path: signed-script.ps1
149+
150+
- name: Run signed script through win_powershell as inline content
151+
ansible.windows.win_powershell:
152+
# rstrip=False is important so the last \r\n of the signature is not removed.
153+
script: "{{ lookup('ansible.builtin.file', 'signed-script.ps1', rstrip=False) }}"

0 commit comments

Comments
 (0)