Skip to content

Commit 0c467cf

Browse files
sdwheelersdwheeler
committed
Reorg security docs and add more WDAC content
1 parent 22bb84c commit 0c467cf

File tree

8 files changed

+592
-165
lines changed

8 files changed

+592
-165
lines changed

‎redir/.openpublishing.redirection.json‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,15 @@
1111
"source_path": "../reference/docs-conceptual/dev-cross-plat/security/securing-restricted-sessions.md"
1212
},
1313
{
14-
"redirect_document_id": true,
15-
"redirect_url": "/powershell/scripting/security/application-control",
14+
"redirect_document_id": false,
15+
"redirect_url": "/powershell/scripting/security/app-control/application-control",
1616
"source_path": "../reference/docs-conceptual/learn/application-control.md"
1717
},
18+
{
19+
"redirect_document_id": true,
20+
"redirect_url": "/powershell/scripting/security/app-control/application-control",
21+
"source_path": "../reference/docs-conceptual/security/application-control.md"
22+
},
1823
{
1924
"redirect_document_id": true,
2025
"redirect_url": "/powershell/scripting/security/remoting/ps-remoting-second-hop",

‎reference/docs-conceptual/security/app-control/application-control.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
description: This article explains the features of Windows using Windows Defender Application Control (WDAC) that can be used to secure your PowerShell environment.
3+
ms.date: 09/19/2024
4+
title: Use Windows Defender Application Control to secure PowerShell
5+
---
6+
# Use Windows Defender Application Control to secure PowerShell
7+
8+
Windows 10 includes two technologies, [Windows Defender Application Control (WDAC)][04] and
9+
[AppLocker][01] that you can use to control applications. They allow you to create a lockdown
10+
experience to help secure your PowerShell environment.
11+
12+
**AppLocker** builds on the application control features of Software Restriction Policies. AppLocker
13+
allows you to create rules to allow or deny apps for specific users or groups. You identify the apps
14+
based on unique properties of the files.
15+
16+
**WDAC**, introduced with Windows 10, allows you to control which drivers and applications are
17+
allowed to run on Windows.
18+
19+
PowerShell detects both AppLocker and WDAC system wide policies. AppLocker is a deprecated. WDAC is
20+
the preferred application control system for Windows. WDAC is designed as a security feature under
21+
the servicing criteria defined by the Microsoft Security Response Center (MSRC).
22+
23+
For more information about AppLocker and WDAC, see [Application Controls for Windows][04] and
24+
[WDAC and AppLocker feature availability][02].
25+
26+
> [!NOTE]
27+
> When [choosing between WDAC or AppLocker][03], we recommend that you implement application control
28+
> using WDAC rather than AppLocker. Microsoft is continually improving WDAC and Microsoft management
29+
> platforms are extending their support for WDAC. Although AppLocker may continue to receive
30+
> security fixes, it won't receive feature enhancements.
31+
32+
## WDAC policy enforcement
33+
34+
When PowerShell runs under a WDAC policy, it changes its behavior based on the defined security
35+
policy. Under a WDAC policy, PowerShell runs trusted scripts and modules allowed by the policy in
36+
`FullLanguage` mode. All other scripts and script blocks are untrusted and run in
37+
`ConstrainedLanguage` mode. PowerShell throws errors when the untrusted scripts attempt to perform
38+
actions that aren't allowed in `ConstrainedLanguage` mode. It can be difficult to know why a script
39+
failed to run correctly in `ConstrainedLanguage` mode.
40+
41+
## WDAC policy auditing
42+
43+
PowerShell 7.4 added a new feature to support WDAC policies in **Audit** mode. In audit mode,
44+
PowerShell runs the untrusted scripts in `ConstrainedLanguage` mode without errors, but logs messages
45+
to the event log instead. The log messages describe what restrictions would apply if the policy was
46+
in **Enforce** mode.
47+
48+
## History of changes
49+
50+
Windows PowerShell 5.1 was the first version of PowerShell to support WDAC. The security features of
51+
WDAC and AppLocker improve with each new release of PowerShell. The following sections describe how
52+
this support changed in each version of PowerShell. The changes are cumulative, so the features
53+
described in the later versions include the features from the earlier versions.
54+
55+
### Changes in PowerShell 7.4
56+
57+
On Windows, when PowerShell runs under a Windows Defender Application Control (WDAC) policy, it
58+
changes its behavior based on the defined security policy. Under a WDAC policy, PowerShell runs
59+
trusted scripts and modules allowed by the policy in `FullLanguage` mode. All other scripts and
60+
script blocks are untrusted and run in `ConstrainedLanguage` mode. PowerShell throws errors when the
61+
untrusted scripts attempt to perform disallowed actions. It's difficult to know why a script fails
62+
to run correctly in `ConstrainedLanguage` mode.
63+
64+
PowerShell 7.4 now supports WDAC policies in **Audit** mode. In audit mode, PowerShell runs the
65+
untrusted scripts in `ConstrainedLanguage` mode but logs messages to the event log instead of
66+
throwing errors. The log messages describe what restrictions would apply if the policy was in
67+
**Enforce** mode.
68+
69+
### Changes in PowerShell 7.3
70+
71+
- PowerShell 7.3 now supports the ability to block or allow PowerShell script files via the WDAC API.
72+
73+
### Changes in PowerShell 7.2
74+
75+
- There was a corner-case scenario in AppLocker where you only have **Deny** rules and constrained
76+
mode isn't used to enforce the policy that allows you to bypass the execution policy. Beginning in
77+
PowerShell 7.2, a change was made to ensure AppLocker rules take precedence over a
78+
`Set-ExecutionPolicy -ExecutionPolicy Bypass` command.
79+
80+
- PowerShell 7.2 now disallows the use of the `Add-Type` cmdlet in a `NoLanguage` mode PowerShell
81+
session on a locked down machine.
82+
83+
- PowerShell 7.2 now disallows scripts from using COM objects in AppLocker system lockdown
84+
conditions. Cmdlets that use COM or DCOM internally aren't affected.
85+
86+
## Further reading
87+
88+
- For more information about how WDAC works and what restrictions it enforces, see
89+
[How WDAC works with PowerShell][06].
90+
- For more information about using securing PowerShell with WDAC, see [How to use WDAC][05].
91+
92+
<!-- link references -->
93+
[01]: /windows/security/threat-protection/windows-defender-application-control/applocker/what-is-applocker
94+
[02]: /windows/security/threat-protection/windows-defender-application-control/feature-availability
95+
[03]: /windows/security/threat-protection/windows-defender-application-control/wdac-and-applocker-overview#choose-when-to-use-wdac-or-applocker
96+
[04]: /windows/security/threat-protection/windows-defender-application-control/windows-defender-application-control
97+
[05]: how-to-use-wdac.md
98+
[06]: how-wdac-works.md

‎reference/docs-conceptual/security/app-control/how-to-use-wdac.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
description: This article explains how to configure and use WDAC to secure PowerShell.
3+
ms.date: 09/19/2024
4+
title: How to use WDAC to secure PowerShell
5+
---
6+
# How to use WDAC to secure PowerShell
7+
8+
This article describes how to set up a **Windows Defender Application Control** (WDAC) policy. You
9+
can configure the policy to enforce or audit the policy's rule. In audit mode, PowerShell behavior
10+
doesn't change but it logs Event ID 16387 messages to the `PowerShellCore/Analytic` event log. In
11+
enforcement mode, PowerShell applies the policy's restrictions.
12+
13+
This article assumes you're using a test machine so that you can test PowerShell behavior
14+
under a machine wide WDAC policy before you deploy the policy in your environment.
15+
16+
## Create a WDAC policy
17+
18+
A WDAC policy is described in an XML file, which contains information about policy options, files
19+
allowed, and signing certificates recognized by the policy. When the policy is applied, only
20+
approved files are allowed to load and run. PowerShell either blocks unapproved script files from
21+
running or runs them in `ConstrainedLanguage` mode, depending on policy options.
22+
23+
You create and manipulate WDAC policy using the **ConfigCI** module, which is available on all
24+
supported Windows version. This Windows PowerShell module that can be used in Windows PowerShell 5.1
25+
or in PowerShell 7 through the **Windows Compatibility** layer. It's easier to use this module in
26+
Windows PowerShell. The policy you create can be applied to any version of PowerShell.
27+
28+
## Steps to create a WDAC policy
29+
30+
For testing, you just need to create a default policy and a self signed code signing certificate.
31+
32+
1. Create a default policy
33+
34+
```powershell
35+
New-CIPolicy -Level PcaCertificate -FilePath .\SystemCIPolicy.xml -UserPEs
36+
```
37+
38+
This command creates a default policy file called `SystemCIPolicy.xml` that allows all Microsoft
39+
code-signed files to run.
40+
41+
> [!NOTE]
42+
> Running this command can take up to two hours because it must scan the entire test machine.
43+
44+
1. Disable Audit Mode in default policy
45+
46+
A new policy is always created in `Audit` mode. To test policy enforcement, you need to disable
47+
Audit mode when you apply the the policy. Edit the `SystemCIPolicy.xml` file using text editor
48+
like `notepad.exe` or Visual Studio Code (VS Code). Comment out the `Audit mode` option.
49+
50+
```XML
51+
<!--
52+
<Rule>
53+
<Option>Enabled:Audit Mode</Option>
54+
</Rule>
55+
-->
56+
```
57+
58+
1. Create a self-signed code signing certificate
59+
60+
You need a code signing certificate to sign any test binaries or script files that you want to
61+
run on your test machine. The `New-SelfSignedCertificate` is provided by the **PKI** module. For
62+
best results, you should run this command in Windows PowerShell 5.1.
63+
64+
```powershell
65+
$newSelfSignedCertificateSplat = @{
66+
DnsName = $env:COMPUTERNAME
67+
CertStoreLocation = "Cert:\CurrentUser\My\"
68+
Type = 'CodeSigningCert'
69+
}
70+
$cert = New-SelfSignedCertificate @newSelfSignedCertificateSplat
71+
Export-Certificate -Cert $cert -FilePath c:\certs\signing.cer
72+
Import-Certificate -FilePath C:\certs\signing.cer -CertStoreLocation "Cert:\CurrentUser\Root\"
73+
$cert = Get-ChildItem Cert:\CurrentUser\My\ -CodeSigningCert
74+
75+
dir c:\bin\powershell\pwsh.exe | Set-AuthenticodeSignature -Certificate $cert
76+
```
77+
78+
1. Add the code signing certificate to the policy
79+
80+
Use the following command to add the new code signing certificate to the policy.
81+
82+
```powershell
83+
Add-SignerRule -FilePath .\SystemCIPolicy.xml -CertificatePath c:\certs\signing.cer -User
84+
```
85+
86+
1. Convert the XML policy file to a policy enforcement binary file
87+
88+
Finally, you need to convert the XML file to a binary file used by WDAC to apply a policy.
89+
90+
```powershell
91+
ConvertFrom-CIPolicy -XmlFilePath .\SystemCIPolicy.xml -BinaryFilePath .\SIPolicy.p7b
92+
```
93+
94+
1. Apply the WDAC policy
95+
96+
To apply the policy to your test machine, copy the `SIPolicy.p7b` file to the required system
97+
location, `C:\Windows\System32\CodeIntegrity`.
98+
99+
> [!NOTE]
100+
> Some policies definition must be copied to a subfolder such as
101+
> `C:\Windows\System32\CodeIntegrity\CiPolicies`. For more information, see
102+
> [WDAC Admin Tips & Known Issues][01].
103+
104+
1. Disable the WDAC policy
105+
106+
To disable the policy, rename the `SIPolicy.p7b` file. If you need to do more testing, you can
107+
change the name back to reenable the policy.
108+
109+
```powershell
110+
Rename-Item -Path .\SIPolicy.p7b -NewName .\SIPolicy.p7b.off
111+
```
112+
113+
## Test using WDAC policy auditing
114+
115+
PowerShell 7.4 added a new feature to support WDAC policies in **Audit** mode. In audit mode,
116+
PowerShell runs the untrusted scripts in `ConstrainedLanguage` mode without errors, but logs
117+
messages to the event log instead. The log messages describe what restrictions would apply if the
118+
policy was in **Enforce** mode.
119+
120+
### Viewing audit events
121+
122+
PowerShell logs audit events to the **PowerShellCore/Analytic** event log. The log isn't enabled by
123+
default. To enable the log, open the **Windows Event Viewer**, right-click on the
124+
**PowerShellCore/Analytic** log and select **Enable Log**.
125+
126+
Alternatively, you can run the following command from an elevated PowerShell session.
127+
128+
```powershell
129+
wevtutil.exe sl PowerShellCore/Analytic /enabled:true /quiet
130+
```
131+
132+
You can view the events in the Windows Event Viewer or use the `Get-WinEvent` cmdlet to retrieve the
133+
events.
134+
135+
```powershell
136+
Get-WinEvent -LogName PowerShellCore/Analytic -Oldest |
137+
Where-Object Id -eq 16387 | Format-List
138+
```
139+
140+
```Output
141+
TimeCreated : 4/19/2023 10:11:07 AM
142+
ProviderName : PowerShellCore
143+
Id : 16387
144+
Message : WDAC Audit.
145+
146+
Title: Method or Property Invocation
147+
Message: Method or Property 'WriteLine' on type 'System.Console' invocation will not
148+
be allowed in ConstrainedLanguage mode.
149+
At C:\scripts\Test1.ps1:3 char:1
150+
+ [System.Console]::WriteLine("pwnd!")
151+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152+
FullyQualifiedId: MethodOrPropertyInvocationNotAllowed
153+
```
154+
155+
The event message includes the script position where the restriction would be applied. This
156+
information helps you understand where you need to change your script so that it runs under the WDAC
157+
policy.
158+
159+
> [!IMPORTANT]
160+
> Once you have reviewed the audit events, you should disable the Analytic log. Analytic logs grow
161+
> quickly and consume large amounts of disk space.
162+
163+
### Viewing audit events in the PowerShell debugger
164+
165+
If you set the `$DebugPreference` variable to `Break` for an interactive PowerShell session,
166+
PowerShell breaks into the command-line script debugger at the current location in the script where
167+
the audit event occurred. The breakpoint allows you to debug your code and inspect the current state
168+
of the script in real time.
169+
170+
<!-- link references -->
171+
[01]: /windows/security/application-security/application-control/windows-defender-application-control/operations/known-issues

0 commit comments

Comments
 (0)