diff --git a/redir/.openpublishing.redirection.json b/redir/.openpublishing.redirection.json index 948f125e45cd..d12a25a2e161 100644 --- 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 new file mode 100644 index 000000000000..56b473edf6f3 --- /dev/null +++ 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]. + + +[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 new file mode 100644 index 000000000000..482139c24fb9 --- /dev/null +++ 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 + + ``` + +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. + + +[01]: /windows/security/application-security/application-control/windows-defender-application-control/operations/known-issues diff --git a/reference/docs-conceptual/security/app-control/how-wdac-works.md b/reference/docs-conceptual/security/app-control/how-wdac-works.md new file mode 100644 index 000000000000..980f2a3ab4c9 --- /dev/null +++ b/reference/docs-conceptual/security/app-control/how-wdac-works.md @@ -0,0 +1,254 @@ +--- +description: This article explains how WDAC works to secure PowerShell and the restrictions it imposes. +ms.date: 09/19/2024 +title: How WDAC works with PowerShell +--- +# How WDAC works with PowerShell + +This article explains how **Windows Defender Application Control** (WDAC) secures PowerShell and the +restrictions it imposes. The secure behavior of PowerShell varies based on the version of Windows +and PowerShell you're using. + +## How PowerShell detects a system lockdown policy + +PowerShell detects both **AppLocker** and **Windows Defender Application Control** (WDAC) system +wide polices. AppLocker is deprecated. WDAC is the preferred application control system for +Windows. + +### Legacy WDAC policy enforcement detection + +PowerShell uses the legacy WDAC `WldpGetLockdownPolicy` API to discover two things: + +- System wide policy enforcement: `None`, `Audit`, `Enforce` +- Individual file policy: `None`, `Audit` (allowed by policy), `Enforce` (not allowed by policy) + +All versions of PowerShell (v5.1 - v7.x) support this WDAC policy detection. + +### Latest WDAC policy enforcement detection + +WDAC introduced new APIs in recent versions of Windows. Beginning with version 7.3, PowerShell uses +the new `WldpCanExecuteFile` API to decide how a file should be handled. Windows PowerShell 5.1 +doesn't support this new API. The new API takes precedence over the legacy API for individual files. +However, PowerShell continues to use the legacy API to get the system wide policy configuration. If +the new API isn't available, PowerShell falls back to the old API behavior. + +The new API provides the following information for each file: + +- `WLDP_CAN_EXECUTE_ALLOWED` +- `WLDP_CAN_EXECUTE_BLOCKED` +- `WLDP_CAN_EXECUTE_REQUIRE_SANDBOX` + +## PowerShell behavior under lockdown policy + +PowerShell can run in both interactive and non-interactive modes. + +- In interactive mode, PowerShell is a command-line application that takes users command-line input + as commands or scripts to run. Results are displayed back to the user. +- In non-interactive mode, PowerShell loads modules and runs script files without user + input. Result data streams are either ignored or redirected to a file. + +### Interactive mode running under policy enforcement + +PowerShell runs commands in `ConstrainedLanguage` mode. This mode prevents interactive users from +running certain commands or executing arbitrary code. For more information about the restrictions in +this mode, see the [PowerShell restrictions under lockdown policy][02] section of this article. + +### Noninteractive mode running under policy enforcement + +When PowerShell runs a script or loads a module, it uses the WDAC API to get the policy enforcement +for the file. + +PowerShell version 7.3 or higher uses the `WldpCanExecuteFile` API if available. This API returns one +of the following results: + +- `WLDP_CAN_EXECUTE_ALLOWED`: The file is approved by policy and is used in `FullLanguage` mode + with a few restrictions. +- `WLDP_CAN_EXECUTE_BLOCKED`: The file isn't approved by policy. PowerShell throws an error when the + file is run or loaded. +- `WLDP_CAN_EXECUTE_REQUIRE_SANDBOX`: The file isn't approved by the policy but it can still be run + or loaded in `ConstrainedLanguage` mode. + +In Windows PowerShell 5.1 or if `WldpCanExecuteFile` API isn't available, PowerShell's per file +behavior is: + +- `None`: The file is run loaded in `FullLanguage` mode with a few restrictions. +- `Audit`: The file is run or loaded in `FullLanguage` mode with no restrictions. In PowerShell + 7.4 or higher, the policy logs restriction information to the Windows event logs. +- `Enforce`: The file is run or loaded in `ConstrainedLanguage` mode. + +## PowerShell restrictions under lockdown policy + +When PowerShell detects the system is under a WDAC lockdown policy, it applies restrictions +even if the script is trusted and running in `FullLanguage` mode. These restrictions prevent known +behaviors of PowerShell that could result in arbitrary code execution on a locked-down system. The +lockdown policy enforces the following restrictions: + +- Module dot-sourcing with wildcard function export restriction + + Any module that uses script dot-sourcing and exports functions using wildcard names results + in an error. Blocking wildcard exports prevents script injection from a malicious user who can + plant an untrusted script that gets dot-sourced into a trusted module. The malicious script could then gain access to the trusted module's private functions. + + **Security recommendation:** Never use script dot-sourcing in a module and always export module + functions with explicit names (no wildcard characters). + +- Nested module with wildcard function export restriction + + If a parent module exports functions using function name wildcard characters, PowerShell + removes any function name in a nested module from the function export list. Blocking wildcard exports + from nested modules prevents accidental exporting of dangerous nested functions through wildcard + name matching. + + **Security recommendation:** Always export module functions with explicit names (no wildcard + characters). + +- Interactive shell parameter type conversion + + When the system is locked down, interactive PowerShell sessions run in `ConstrainedLanguage` mode + to prevent arbitrary code execution. Trusted modules loaded into the session run in `FullLanguage` + mode. If a trusted module cmdlet uses complex types for its parameters, type conversion during + parameter binding can fail if the conversion isn't allowed across trust boundaries. The failure + occurs when PowerShell tries to convert a value by running a type constructor. Type constructors + aren't allowed to run in `ConstrainedLanguage` mode. + + In this example, parameter binding type conversion is normally allowed, but fails when run in + `ConstrainedLanguage` mode. The `ConnectionPort` type constructor isn't allowed: + + ```powershell + PS> Create-ConnectionOnPort -Connection 22 + Create-ConnectionOnPort: Cannot bind parameter 'Connection'. Cannot convert the "22" + value of type "System.Int32" to type "ConnectionPort". + ``` + +- `Enter-PSHostProcess` cmdlet disallowed + + The `Enter-PSHostProcess` cmdlet is disabled and throws an error if used. This command is used for + attach-and-debug sessions. It allows you to connect to any other PowerShell session on the local + machine. The cmdlet is disabled to prevent information disclosure and arbitrary code execution. + +## PowerShell restrictions under constrained language mode + +Script or function that isn't approved by the WDAC policy is untrusted. When you run an untrusted +command, PowerShell either blocks the command from running (new behavior) or runs the command in +`ConstrainedLanguage` mode. The following restrictions apply to `ConstrainedLanguage` mode: + +- `Add-Type` cmdlet disallowed + + Blocking `Add-Type` prevents the execution of arbitrary .NET code. + +- `Import-LocalizedData` cmdlet restricted + + Blocking the **SupportedCommand** parameter of `Import-LocalizedData` prevents the execution of + arbitrary code. + +- `Invoke-Expression` cmdlet restricted + + All script blocks passed to the `Invoke-Expression` cmdlet are run in `ConstrainedLanguage` mode + to prevent arbitrary code execution. + +- `New-Object` cmdlet restricted + + The `New-Object` cmdlet is restricted to use only allowed .NET and COM types, to prevent access to + untrusted types. + +- `ForEach-Object` cmdlet restriction + + Type method invocation for variables passed to the `ForeEach-Object` is disallowed for any .NET + type not in the approved list. In general, `ConstrainedLanguage` mode disallows any object method + invocation except for approved .NET types to prevent access to untrusted .NET types. + +- `Export-ModuleMember` cmdlet restriction + + Using `Export-ModuleMember` cmdlet to export functions in a nested module script file where the + child module isn't trusted and the parent module is trusted, results in an error. Blocking this + scenario prevents a malicious untrusted module from exporting dangerous functions from a trusted + module. + +- `New-Module` cmdlet restriction + + When you run `New-Module` in a trusted script, any script block provided by the `ScriptBlock` + parameter is marked to run in `ConstrainedLanguage` mode to prevent the injection of arbitrary + code into a trusted execution context. + +- `Configuration` keyword not allowed + + The `Configuration` language keyword isn't allowed in `ConstrainedLanguage` mode to prevent code + injection attacks. + +- `class` keyword not allowed + + The `class` language keyword isn't allowed in `ConstrainedLanguage` mode to prevent the injection + of arbitrary code. + +- Script Block processing scope restrictions + + Child script blocks aren't allowed to run in parent script block scopes if the script blocks have + different trust levels. For example, you create a child relationship when you dot-source one + script into another. Blocking this scenario prevents an untrusted script from getting access to + dangerous functions in the trusted script scope. + +- Prevent command discovery of untrusted script functions + + PowerShell command discovery doesn't return functions from an untrusted source, such as an + untrusted script or module, to a trusted function. Blocking discovery of untrusted commands + prevents code injection through command planting. + +- Hashtable to object conversion not allowed + + `ConstrainedLanguage` mode blocks hashtable to object conversions in the `Data` sections of + PowerShell data (`.psd1`) files to prevent potential code injection attacks. + +- Automatic type conversion restricted + + `ConstrainedLanguage` mode blocks automatic type conversion except for a small set of approved + safe types to prevent potential code injection attacks. + +- Implicit module function export restriction + + If a module doesn't explicitly export functions, PowerShell implicitly exports all defined module + functions automatically as a convenience feature. In `ConstrainedLanguage` mode, implicit exports + no longer occur when a module is loaded across trust boundaries. Blocking implicit exports + prevents unintended exposure of dangerous module functions not meant for public use. + +- Script files can't be imported as modules + + PowerShell allows you to import script files (`.ps1`) as a module. All defined functions become + publicly accessible. `ConstrainedLanguage` mode blocks importation of script file to prevent + unintended exposure of dangerous script functions. + +- Setting variables `AllScope` restriction + + `ConstrainedLanguage` mode disables the ability to set `AllScope` on variables. Limiting the scope + of variables prevents the variables from interfering with the session state of trusted commands. + +- Type method invocation not allowed + + `ConstrainedLanguage` mode doesn't allow method invocation on unapproved types. Blocking methods on + unapproved types prevents invocation of .NET type methods that might be dangerous or allow code + injection. + +- Type property setters not allowed + + `ConstrainedLanguage` mode restricts invocation of property setters on unapproved types. Blocking + property setters on unapproved types prevents code injection attacks. + +- Type creation not allowed + + `ConstrainedLanguage` mode blocks type creation on unapproved types to block untrusted + constructors that could allow code injection. + +- Module scope operator not allowed + + `ConstrainedLanguage` mode doesn't allow the use of the module scope operator. For example: + `& (Get-Module MyModule) MyFunction`. Blocking the module scope operator prevents access to module + private functions and variables. + +## Further reading + +- For more information about PowerShell language modes, see [about_Language_Modes][01]. +- For information about how to configure and use WDAC, see [How to use WDAC for PowerShell][03]. + + +[01]: /powershell/module/microsoft.powershell.core/about/about_language_modes +[02]: #powershell-behavior-under-lockdown-policy +[03]: how-to-use-wdac.md diff --git a/reference/docs-conceptual/security/application-control.md b/reference/docs-conceptual/security/application-control.md deleted file mode 100644 index 8a0aa9ad945c..000000000000 --- a/reference/docs-conceptual/security/application-control.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -description: You can secure your PowerShell environments on Windows using Windows Defender Application Control (WDAC). -ms.date: 11/30/2023 -title: Using Windows Defender Application Control ---- -# Using Windows Defender Application Control - -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 -contains capabilities and extensions that enable you to create rules to allow or deny apps from -running based on unique identities of files and to specify the users or groups that are allowed to -run those apps. - -> [!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** was introduced with Windows 10 and allows organizations to control the drivers and -applications are allowed to run on their Windows devices. 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]. - -## WDAC policy enforcement - -When PowerShell runs under a WDAC policy, it changes its behavior based on the defined security -policy. Under a WDAC policy, PowerShell runs trusted scripts and modules allowed by the policy in -Full Language mode. All other scripts and script blocks are untrusted and run in Constrained -Language mode. PowerShell throws errors when the untrusted scripts attempt to perform actions that -aren't allowed in Constrained Language mode. It can be difficult to know why a script failed to run -correctly in Constrained Language 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 Constrained Language mode without errors, but logs messages -to the event log instead. The log messages describe what restrictions would apply if the policy was -in **Enforce** mode. - -### Viewing audit events - -PowerShell logs audit events to the **PowerShellCore/Analytic** event log. You must enable -the Analytic log. To enable the Analytic log in the Windows Event Viewer, right-click on the -**PowerShellCore/Analytic** log and select **Enable Log**. - -Or, 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 will break into the command-line script debugger at the current location in the script -where the audit event occurred. This allows you to debug your code and inspect the current state of -the script in real time. - - -[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 diff --git a/reference/docs-conceptual/security/overview.yml b/reference/docs-conceptual/security/overview.yml index 55b235e62cfd..6aeb39700a7e 100644 --- a/reference/docs-conceptual/security/overview.yml +++ b/reference/docs-conceptual/security/overview.yml @@ -73,6 +73,20 @@ landingContent: - text: Auditing and Reporting on JEA url: remoting/jea/audit-and-report.md + # Card + - title: Using WDAC + linkLists: + - linkListType: overview + links: + - text: Using Windows Defender Application Control + url: app-control/application-control.md + - text: How WDAC works with PowerShell + url: app-control/how-wdac-works.md + - linkListType: how-to-guide + links: + - text: How to use WDAC to secure PowerShell + url: app-control/how-to-use-wdac.md + # Card - title: Managing secrets linkLists: diff --git a/reference/docs-conceptual/security/security-features.md b/reference/docs-conceptual/security/security-features.md index a287dd0d87c0..d8331ef8dc2f 100644 --- a/reference/docs-conceptual/security/security-features.md +++ b/reference/docs-conceptual/security/security-features.md @@ -1,6 +1,6 @@ --- description: PowerShell has several features designed to improve the security of your scripting environment. -ms.date: 07/08/2024 +ms.date: 09/19/2024 title: PowerShell security features --- # PowerShell security features @@ -33,12 +33,12 @@ converted to a plain text string. For a full discussion about using **SecureStri ## Module and script block logging Module Logging allows you to enable logging for selected PowerShell modules. This setting is -effective in all sessions on the computer. Pipeline execution events for the specified modules are -recorded in the Windows PowerShell log in Event Viewer. +effective in all sessions on the computer. PowerShell records pipeline execution events for the +specified modules in the Windows PowerShell log in Event Viewer. Script Block Logging enables logging for the processing of commands, script blocks, functions, and -scripts - whether invoked interactively, or through automation. This information is logged to the -**Microsoft-Windows-PowerShell/Operational** event log. +scripts - whether invoked interactively, or through automation. PowerShell logs this information to +the **Microsoft-Windows-PowerShell/Operational** event log. For more information, see the following articles: @@ -48,8 +48,8 @@ For more information, see the following articles: ## AMSI Support -The Windows Antimalware Scan Interface (AMSI) is an API that allows application actions to be passed -to an antimalware scanner, such as Windows Defender, to be scanned for malicious payloads. Beginning +The Windows Antimalware Scan Interface (AMSI) is an API that allows applications to pass actions to +an antimalware scanner, such as Windows Defender, to scan for malicious payloads. Beginning with PowerShell 5.1, PowerShell running on Windows 10 (and higher) passes all script blocks to AMSI. PowerShell 7.3 extends the data that's sent to AMSI for inspection. It now includes all invocations @@ -59,75 +59,53 @@ For more information about AMSI, see [How AMSI helps][09]. ## Constrained language mode -**ConstrainedLanguage** mode protects your system by limiting the cmdlets and .NET types that can be -used in a PowerShell session. For a full description, see [about_Language_Modes][04]. +**ConstrainedLanguage** mode protects your system by limiting the cmdlets and .NET types +allowed in a PowerShell session. For a full description, see [about_Language_Modes][04]. ## Application Control Windows 10 includes two technologies, [Windows Defender Application Control (WDAC)][08] and -[AppLocker][07] that you can use to control applications. They allow you to create a lockdown -experience to help secure your PowerShell environment. +[AppLocker][07] that you can use to control applications. PowerShell detects if a system wide +application control policy is being enforced. The policy applies certain behaviors when running +script blocks, script files, or loading module files to prevent arbitrary code execution on the +system. + +WDAC is designed as a security feature under the servicing criteria defined by the Microsoft +Security Response Center (MSRC). WDAC is the preferred application control system for Windows. For more information about how PowerShell supports AppLocker and WDAC, see [Using Windows Defender Application Control][10]. -### Changes in PowerShell 7.4 - -On Windows, when PowerShell runs under a Windows Defender Application Control (WDAC) policy, it -changes its behavior based on the defined security policy. Under a WDAC policy, PowerShell runs -trusted scripts and modules allowed by the policy in Full Language mode. All other scripts and -script blocks are untrusted and run in Constrained Language 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 Constrained Language mode. - -PowerShell 7.4 now supports WDAC policies in **Audit** mode. In audit mode, PowerShell runs the -untrusted scripts in Constrained Language mode but logs messages to the event log instead of -throwing errors. The log messages describe what restrictions would apply if the policy was 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. +## Software Bill of Materials (SBOM) -### Changes in PowerShell 7.2 +Beginning with PowerShell 7.2, all install packages contain a Software Bill of Materials (SBOM). The +PowerShell team also produces SBOMs for modules that they own but ship independently from +PowerShell. -- 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. +You can find SBOM files in the following locations: -- PowerShell 7.2 now disallows the use of the `Add-Type` cmdlet in a **NoLanguage** mode PowerShell - session on a locked down machine. +- In PowerShell, find the SBOM at `$PSHOME/_manifest/spdx_2.2/manifest.spdx.json`. +- For modules, find the SBOM in the module's folder under `_manifest/spdx_2.2/manifest.spdx.json`. -- PowerShell 7.2 now disallows scripts from using COM objects in AppLocker system lock down - conditions. Cmdlets that use COM or DCOM internally aren't affected. +The creation and publishing of the SBOM is the first step to modernize Federal Government +cybersecurity and enhance software supply chain security. For more information about this initiative, +see the blog post [Generating Software Bills of Materials (SBOMs) with SPDX at Microsoft][11]. -### Security Servicing Criteria +## Security Servicing Criteria -PowerShell follows the [Microsoft Security Servicing Criteria for Windows][12]. The table below -outlines the features that meet the servicing criteria and those that do not. +PowerShell follows the [Microsoft Security Servicing Criteria for Windows][12]. Only security +features meet the criteria for servicing. -| Feature | Type | -| ------------------------------------------ | ---------------- | -| System Lockdown - with WDAC | Security Feature | -| Constrained language mode - with WDAC | Security Feature | -| System Lockdown - with AppLocker | Defense in Depth | -| Constrained language mode - with AppLocker | Defense in Depth | -| Execution Policy | Defense in Depth | +Security features -## Software Bill of Materials (SBOM) - -Beginning with PowerShell 7.2, all install packages contain a Software Bill of Materials (SBOM). The -SBOM is found at `$PSHOME/_manifest/spdx_2.2/manifest.spdx.json`. The creation and publishing of the -SBOM is the first step to modernize Federal Government cybersecurity and enhance software supply -chain security. +- System Lockdown with WDAC +- Constrained language mode with WDAC -The PowerShell team is also producing SBOMs for modules that they own but ship separately from -PowerShell. SBOMs will be added in the next release of the module. For modules, the SBOM is -installed in the module's folder under `_manifest/spdx_2.2/manifest.spdx.json`. +Defense in depth features -For more information about this initiative, see the blog post -[Generating Software Bills of Materials (SBOMs) with SPDX at Microsoft][11]. +- System Lockdown with AppLocker +- Constrained language mode with AppLocker +- Execution Policy [01]: /dotnet/fundamentals/runtime-libraries/system-security-securestring @@ -139,6 +117,6 @@ For more information about this initiative, see the blog post [07]: /windows/security/threat-protection/windows-defender-application-control/applocker/what-is-applocker [08]: /windows/security/threat-protection/windows-defender-application-control/windows-defender-application-control [09]: /windows/win32/amsi/how-amsi-helps -[10]: application-control.md +[10]: app-control/application-control.md [11]: https://devblogs.microsoft.com/engineering-at-microsoft/generating-software-bills-of-materials-sboms-with-spdx-at-microsoft/ [12]: https://www.microsoft.com/msrc/windows-security-servicing-criteria diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 414a52c55986..78472580a71f 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -303,12 +303,16 @@ items: href: security/overview.yml - name: PowerShell security features href: security/security-features.md - - name: Using Application Control - href: security/application-control.md + - name: Secure PowerShell with WDAC + items: + - name: Using Application Control + href: security/app-control/application-control.md + - name: How WDAC works with PowerShell + href: security/app-control/how-wdac-works.md + - name: How to use WDAC to secure PowerShell + href: security/app-control/how-to-use-wdac.md - name: Preventing script injection attacks href: security/preventing-script-injection.md - - name: Securing a restricted PowerShell remoting session - href: security/securing-restricted-sessions.md - name: PowerShell remoting items: - name: Just Enough Administration (JEA) @@ -339,6 +343,8 @@ items: href: security/remoting/winrm-security.md - name: Making the second hop in PowerShell Remoting href: security/remoting/ps-remoting-second-hop.md + - name: Securing a restricted PowerShell remoting session + href: security/securing-restricted-sessions.md - name: PowerShell Remoting FAQ href: security/remoting/powershell-remoting-faq.yml - name: Desired State Configuration (DSC)