Reorg security docs and add more WDAC content (#11416)

* Reorg security docs and add more WDAC content * fix broken links * fix broken links * Apply suggestions from code review Co-authored-by: Mike F. Robbins <mike.robbins@microsoft.com> --------- Co-authored-by: Mike F. Robbins <mike.robbins@microsoft.com>
MicrosoftDocs · Sep 23, 2024 · bf63c8b · bf63c8b
1 parent 22bb84c
commit bf63c8b
Show file tree

Hide file tree

Showing 8 changed files with 590 additions and 165 deletions.
diff --git a/redir/.openpublishing.redirection.json b/redir/.openpublishing.redirection.json
@@ -11,10 +11,15 @@
       "source_path": "../reference/docs-conceptual/dev-cross-plat/security/securing-restricted-sessions.md"
     },
     {
-      "redirect_document_id": true,
-      "redirect_url": "/powershell/scripting/security/application-control",
+      "redirect_document_id": false,
+      "redirect_url": "/powershell/scripting/security/app-control/application-control",
       "source_path": "../reference/docs-conceptual/learn/application-control.md"
     },
+    {
+      "redirect_document_id": true,
+      "redirect_url": "/powershell/scripting/security/app-control/application-control",
+      "source_path": "../reference/docs-conceptual/security/application-control.md"
+    },
     {
       "redirect_document_id": true,
       "redirect_url": "/powershell/scripting/security/remoting/ps-remoting-second-hop",

diff --git a/reference/docs-conceptual/security/app-control/application-control.md b/reference/docs-conceptual/security/app-control/application-control.md
@@ -0,0 +1,97 @@
+---
+description: This article explains the features of Windows using Windows Defender Application Control (WDAC) that can be used to secure your PowerShell environment.
+ms.date: 09/19/2024
+title: Use Windows Defender Application Control to secure PowerShell
+---
+# Use Windows Defender Application Control to secure PowerShell
+
+Windows 10 includes two technologies, [Windows Defender Application Control (WDAC)][04] and
+[AppLocker][01] that you can use to control applications. They allow you to create a lockdown
+experience to help secure your PowerShell environment.
+
+**AppLocker** builds on the application control features of Software Restriction Policies. AppLocker
+allows you to create rules to allow or deny apps for specific users or groups. You identify the apps
+based on unique properties of the files.
+
+**WDAC**, introduced with Windows 10, allows you to control which drivers and applications are
+allowed to run on Windows.
+
+PowerShell detects both AppLocker and WDAC system wide policies. AppLocker is deprecated. WDAC is
+the preferred application control system for Windows. WDAC is designed as a security feature under
+the servicing criteria defined by the Microsoft Security Response Center (MSRC).
+
+For more information about AppLocker and WDAC, see [Application Controls for Windows][04] and
+[WDAC and AppLocker feature availability][02].
+
+> [!NOTE]
+> When [choosing between WDAC or AppLocker][03], we recommend that you implement application control
+> using WDAC rather than AppLocker. Microsoft is continually improving WDAC and Microsoft management
+> platforms are extending their support for WDAC. Although AppLocker may continue to receive
+> security fixes, it won't receive feature enhancements.
+
+## WDAC policy enforcement
+
+When PowerShell runs under a WDAC policy, its behavior changes based on the defined security
+policy. Under a WDAC policy, PowerShell runs trusted scripts and modules allowed by the policy in
+`FullLanguage` mode. All other scripts and script blocks are untrusted and run in
+`ConstrainedLanguage` mode. PowerShell throws errors when the untrusted scripts attempt to perform
+actions that aren't allowed in `ConstrainedLanguage` mode. It can be difficult to know why a script
+failed to run correctly in `ConstrainedLanguage` mode.
+
+## WDAC policy auditing
+
+PowerShell 7.4 added a new feature to support WDAC policies in **Audit** mode. In audit mode,
+PowerShell runs the untrusted scripts in `ConstrainedLanguage` mode without errors, but logs messages
+to the event log instead. The log messages describe what restrictions would apply if the policy were
+in **Enforce** mode.
+
+## History of changes
+
+Windows PowerShell 5.1 was the first version of PowerShell to support WDAC. The security features of
+WDAC and AppLocker improve with each new release of PowerShell. The following sections describe how
+this support changed in each version of PowerShell. The changes are cumulative, so the features
+described in the later versions include those from earlier versions.
+
+### Changes in PowerShell 7.4
+
+On Windows, when PowerShell runs under a Windows Defender Application Control (WDAC) policy, its behavior changes based on the defined security policy. Under a WDAC policy, PowerShell runs
+trusted scripts and modules allowed by the policy in `FullLanguage` mode. All other scripts and
+script blocks are untrusted and run in `ConstrainedLanguage` mode. PowerShell throws errors when the
+untrusted scripts attempt to perform disallowed actions. It's difficult to know why a script fails
+to run correctly in `ConstrainedLanguage` mode.
+
+PowerShell 7.4 now supports WDAC policies in **Audit** mode. In audit mode, PowerShell runs the
+untrusted scripts in `ConstrainedLanguage` mode but logs messages to the event log instead of
+throwing errors. The log messages describe what restrictions would apply if the policy were in
+**Enforce** mode.
+
+### Changes in PowerShell 7.3
+
+- PowerShell 7.3 now supports the ability to block or allow PowerShell script files via the WDAC API.
+
+### Changes in PowerShell 7.2
+
+- There was a corner-case scenario in AppLocker where you only have **Deny** rules and constrained
+  mode isn't used to enforce the policy that allows you to bypass the execution policy. Beginning in
+  PowerShell 7.2, a change was made to ensure AppLocker rules take precedence over a
+  `Set-ExecutionPolicy -ExecutionPolicy Bypass` command.
+
+- PowerShell 7.2 now disallows the use of the `Add-Type` cmdlet in a `NoLanguage` mode PowerShell
+  session on a locked down machine.
+
+- PowerShell 7.2 now disallows scripts from using COM objects in AppLocker system lockdown
+  conditions. Cmdlets that use COM or DCOM internally aren't affected.
+
+## Further reading
+
+- For more information about how WDAC works and what restrictions it enforces, see
+  [How WDAC works with PowerShell][06].
+- For more information about securing PowerShell with WDAC, see [How to use WDAC][05].
+
+<!-- link references -->
+[01]: /windows/security/threat-protection/windows-defender-application-control/applocker/what-is-applocker
+[02]: /windows/security/threat-protection/windows-defender-application-control/feature-availability
+[03]: /windows/security/threat-protection/windows-defender-application-control/wdac-and-applocker-overview#choose-when-to-use-wdac-or-applocker
+[04]: /windows/security/threat-protection/windows-defender-application-control/windows-defender-application-control
+[05]: how-to-use-wdac.md
+[06]: how-wdac-works.md
diff --git a/reference/docs-conceptual/security/app-control/how-to-use-wdac.md b/reference/docs-conceptual/security/app-control/how-to-use-wdac.md
@@ -0,0 +1,171 @@
+---
+description: This article explains how to configure and use WDAC to secure PowerShell.
+ms.date: 09/19/2024
+title: How to use WDAC to secure PowerShell
+---
+# How to use WDAC to secure PowerShell
+
+This article describes how to set up a **Windows Defender Application Control** (WDAC) policy. You
+can configure the policy to enforce or audit the policy's rule. In audit mode, PowerShell behavior
+doesn't change but it logs Event ID 16387 messages to the `PowerShellCore/Analytic` event log. In
+enforcement mode, PowerShell applies the policy's restrictions.
+
+This article assumes you're using a test machine so that you can test PowerShell behavior
+under a machine wide WDAC policy before you deploy the policy in your environment.
+
+## Create a WDAC policy
+
+A WDAC policy is described in an XML file, which contains information about policy options, files
+allowed, and signing certificates recognized by the policy. When the policy is applied, only
+approved files are allowed to load and run. PowerShell either blocks unapproved script files from
+running or runs them in `ConstrainedLanguage` mode, depending on policy options.
+
+You create and manipulate WDAC policy using the **ConfigCI** module, which is available on all
+supported Windows versions. This Windows PowerShell module can be used in Windows PowerShell 5.1
+or in PowerShell 7 through the **Windows Compatibility** layer. It's easier to use this module in
+Windows PowerShell. The policy you create can be applied to any version of PowerShell.
+
+## Steps to create a WDAC policy
+
+For testing, you just need to create a default policy and a self signed code signing certificate.
+
+1. Create a default policy
+
+   ```powershell
+   New-CIPolicy -Level PcaCertificate -FilePath .\SystemCIPolicy.xml -UserPEs
+   ```
+
+   This command creates a default policy file called `SystemCIPolicy.xml` that allows all Microsoft
+   code-signed files to run.
+
+   > [!NOTE]
+   > Running this command can take up to two hours because it must scan the entire test machine.
+
+1. Disable Audit Mode in default policy
+
+   A new policy is always created in `Audit` mode. To test policy enforcement, you need to disable
+   Audit mode when you apply the policy. Edit the `SystemCIPolicy.xml` file using a text editor
+   like `notepad.exe` or Visual Studio Code (VS Code). Comment out the `Audit mode` option.
+
+   ```XML
+   <!--
+   <Rule>
+     <Option>Enabled:Audit Mode</Option>
+   </Rule>
+   -->
+   ```
+
+1. Create a self-signed code signing certificate
+
+   You need a code signing certificate to sign any test binaries or script files that you want to
+   run on your test machine. The `New-SelfSignedCertificate` is provided by the **PKI** module. For
+   best results, you should run this command in Windows PowerShell 5.1.
+
+   ```powershell
+   $newSelfSignedCertificateSplat = @{
+       DnsName = $env:COMPUTERNAME
+       CertStoreLocation = "Cert:\CurrentUser\My\"
+       Type = 'CodeSigningCert'
+   }
+   $cert = New-SelfSignedCertificate @newSelfSignedCertificateSplat
+   Export-Certificate -Cert $cert -FilePath c:\certs\signing.cer
+   Import-Certificate -FilePath C:\certs\signing.cer -CertStoreLocation "Cert:\CurrentUser\Root\"
+   $cert = Get-ChildItem Cert:\CurrentUser\My\ -CodeSigningCert
+
+   dir c:\bin\powershell\pwsh.exe | Set-AuthenticodeSignature -Certificate $cert
+   ```
+
+1. Add the code signing certificate to the policy
+
+   Use the following command to add the new code signing certificate to the policy.
+
+   ```powershell
+   Add-SignerRule -FilePath .\SystemCIPolicy.xml -CertificatePath c:\certs\signing.cer -User
+   ```
+
+1. Convert the XML policy file to a policy enforcement binary file
+
+   Finally, you need to convert the XML file to a binary file used by WDAC to apply a policy.
+
+   ```powershell
+   ConvertFrom-CIPolicy -XmlFilePath .\SystemCIPolicy.xml -BinaryFilePath .\SIPolicy.p7b
+   ```
+
+1. Apply the WDAC policy
+
+   To apply the policy to your test machine, copy the `SIPolicy.p7b` file to the required system
+   location, `C:\Windows\System32\CodeIntegrity`.
+
+   > [!NOTE]
+   > Some policies definition must be copied to a subfolder such as
+   > `C:\Windows\System32\CodeIntegrity\CiPolicies`. For more information, see
+   > [WDAC Admin Tips & Known Issues][01].
+
+1. Disable the WDAC policy
+
+   To disable the policy, rename the `SIPolicy.p7b` file. If you need to do more testing, you can
+   change the name back to reenable the policy.
+
+   ```powershell
+   Rename-Item -Path .\SIPolicy.p7b -NewName .\SIPolicy.p7b.off
+   ```
+
+## Test using WDAC policy auditing
+
+PowerShell 7.4 added a new feature to support WDAC policies in **Audit** mode. In audit mode,
+PowerShell runs the untrusted scripts in `ConstrainedLanguage` mode without errors, but logs
+messages to the event log instead. The log messages describe what restrictions would apply if the
+policy were in **Enforce** mode.
+
+### Viewing audit events
+
+PowerShell logs audit events to the **PowerShellCore/Analytic** event log. The log isn't enabled by
+default. To enable the log, open the **Windows Event Viewer**, right-click on the
+**PowerShellCore/Analytic** log and select **Enable Log**.
+
+Alternatively, you can run the following command from an elevated PowerShell session.
+
+```powershell
+wevtutil.exe sl PowerShellCore/Analytic /enabled:true /quiet
+```
+
+You can view the events in the Windows Event Viewer or use the `Get-WinEvent` cmdlet to retrieve the
+events.
+
+```powershell
+Get-WinEvent -LogName PowerShellCore/Analytic -Oldest |
+    Where-Object Id -eq 16387 | Format-List
+```
+
+```Output
+TimeCreated  : 4/19/2023 10:11:07 AM
+ProviderName : PowerShellCore
+Id           : 16387
+Message      : WDAC Audit.
+
+    Title: Method or Property Invocation
+    Message: Method or Property 'WriteLine' on type 'System.Console' invocation will not
+        be allowed in ConstrainedLanguage mode.
+        At C:\scripts\Test1.ps1:3 char:1
+        + [System.Console]::WriteLine("pwnd!")
+        + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    FullyQualifiedId: MethodOrPropertyInvocationNotAllowed
+```
+
+The event message includes the script position where the restriction would be applied. This
+information helps you understand where you need to change your script so that it runs under the WDAC
+policy.
+
+> [!IMPORTANT]
+> Once you have reviewed the audit events, you should disable the Analytic log. Analytic logs grow
+> quickly and consume large amounts of disk space.
+
+### Viewing audit events in the PowerShell debugger
+
+If you set the `$DebugPreference` variable to `Break` for an interactive PowerShell session,
+PowerShell breaks into the command-line script debugger at the current location in the script where
+the audit event occurred. The breakpoint allows you to debug your code and inspect the current state
+of the script in real time.
+
+<!-- link references -->
+[01]: /windows/security/application-security/application-control/windows-defender-application-control/operations/known-issues