Skip to content

Commit c1c7c66

Browse files
TravisEz13joeyaiello
TravisEz13
authored and
joeyaiello
committed
RFC0041 - PowerShell Core Policy (#180)
* Draft policy RFC * Address steve's feedback * Update RFCXXXX-Policy.md Apply suggestions from code review Co-Authored-By: Ilya <[email protected]> Update 1-Draft/RFCXXXX-Policy.md Update 1-Draft/RFCXXXX-Policy.md Co-Authored-By: Ilya <[email protected]> * offline updates * Apply suggestions from code review * Apply suggestions from code review * Apply suggestions from code review * Apply suggestions from code review * Apply suggestions from code review * offline updates * remove accidental new behavior. * Update RFCXXXX-Policy.md * Update 1-Draft/RFCXXXX-Policy.md * Update 1-Draft/RFCXXXX-Policy.md * Apply suggestions from code review * Update RFCXXXX-Policy.md * Update 1-Draft/RFCXXXX-Policy.md * Change "regular settings" to "non-policy" in Policy RFC * Prepare policy RFC for acceptance
1 parent afb8338 commit c1c7c66

File tree

1 file changed

+262
-0
lines changed

1 file changed

+262
-0
lines changed

‎2-Draft-Accepted/RFC0041-Policy.md

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
---
2+
RFC: RFC0041
3+
Author: travisez13
4+
Status: Draft-Accepted
5+
SupercededBy: N/A
6+
Version: 0.1
7+
Area: Engine
8+
Comments Due: 6/30/2019
9+
---
10+
11+
# `PowerShell Core` Policy
12+
13+
## Motivation
14+
15+
Consumers, developers, and enterprise system administrators should be able to flexibly and reliably configure PowerShell 7.
16+
17+
## Acknowledgement
18+
19+
I based this off of @iSazonov 's RFC, for just a slightly different purpose.
20+
[PR #111](https://github.com/PowerShell/PowerShell-RFC/pull/111)
21+
22+
## Goals
23+
24+
1. Specify how PowerShell 7 will deal with having both Windows PowerShell and PowerShell Core Group Policy.
25+
- This is covered in [Policy settings Setting Fall-Back](#policy-settings-setting-fall-back).
26+
1. Define how the `pwsh -settingsfile` switch should behave.
27+
- This is covered in [Parameter `-settingsfile`](#Parameter--settingsfile)
28+
1. Specify where setting will be read from on various supported platforms.
29+
30+
## Definitions
31+
32+
- **Computer-Wide settings/policy** - setting or policy applied to an operating system environment (OSE), affecting all users of the OSE.
33+
- **Per-User settings/policy** - setting or policy applied to a specific user of an OSE, and not applied to the OSE as a whole.
34+
35+
## Specification
36+
37+
`PowerShell 7` should be configured using the following schemes:
38+
39+
- On Windows - Group Policy Objects (GPO), and settings files.
40+
- On Unix - settings files.
41+
42+
The settings files have `JSON` format.
43+
44+
**Warning** The settings files differ from `PowerShell 7` _profile_ files, which are PowerShell scripts run at startup.
45+
46+
Configuration schemes allow to customize `PowerShell 7` in the most flexible way:
47+
48+
- Enterprise system administrators can use GPO,
49+
Computer-wide settings files to apply approved configuration settings and mandatory security settings in a centralized manner.
50+
Most settings can be applied either to the user or computer-wide.
51+
We will cover the precedence of these in [Registry keys and settings](#registry-keys-and-settings).
52+
- Developers and consumers can use user, or computer-wide level setting files.
53+
54+
### Configuration defaults
55+
56+
PowerShell 7 has hard-coded defaults for all configuration policies and settings.
57+
58+
The default values must be `secure-by-default`.
59+
60+
For release versions hard-coded defaults must be the same as ones in pre-installed configuration files. For preview versions they may vary (ex., enable experimental features and so on).
61+
62+
Computer-wide configuration includes security sensitive setting,
63+
and failing to read those setting, for example if the file is locked or corrupted, could result in an insecure system.
64+
So, if during startup, PowerShell 7 cannot read settings files from the Computer-Wide scope,
65+
it fails to startup.
66+
Because registry reads are more atomic,
67+
this is not an issue for group policy settings,
68+
but if we faced the same issues for these settings the solution would be the similar.
69+
70+
If during startup PowerShell 7 cannot read user configuration files it uses _hardcoded_ defaults and emits a warning.
71+
72+
PowerShell 7 does not update configuration values from modified configuration files during a given session after the configuration has been loaded.
73+
74+
### Settings locations
75+
76+
`PowerShell 7` settings are grouped into `Policy settings` and `Non-policy settings`.
77+
Regular settings are normal configuration settings.
78+
Regular settings can be treated as default and recommended values.
79+
Policy settings have a higher precedence than regular settings.
80+
See [Precedence for Policy settings in descending order](#precedence-for-policy-settings-in-descending-order).
81+
Policy settings are used by administrators to centrally manage PowerShell.
82+
83+
| Location | Policy settings | Regular settings |
84+
|--------------|-----------------------------------------------------------|------------------------------------------------------------|
85+
| File section | "PowerShell": { "PolicySettings": {...} } | "PowerShell": { "RegularSettings": {...} } |
86+
| Registry key | Software\Policies\PowerShellCore | Not Applicable |
87+
88+
### Policy settings Setting Fall-Back
89+
90+
#### Motivation - Policy Setting Fall-Back
91+
92+
Help to transition from Windows PowerShell to PowerShell 7.
93+
94+
#### Implementation
95+
96+
For Policy Settings,
97+
each policy should have a `Use Windows PowerShell Policy` which will indicate that the policy should the read from
98+
`SOFTWARE\Policies\Microsoft\Windows\PowerShell` instead of `Software\Policies\PowerShellCore`.
99+
The default in Group Policy is to have no policy, so it would not fall back to Windows PowerShell Policy, or apply PowerShell 7 policy.
100+
101+
### Precedence of applying settings
102+
103+
Because a configuration setting can be in several schemes, the setting wins according to the priority of its scheme.
104+
105+
#### Precedence for Computer-Wide settings in descending order
106+
107+
Note, this is listed as `Computer, Then User` in [Registry keys and settings](#registry-keys-and-settings).
108+
109+
| Scheme | Windows | Unix |
110+
|-----------------------------|------------------------------------------------------|------------------------------------------------------|
111+
| GPO -> Computer Policy | HKLM\Software\Policies\PowerShellCore | See [Moving configuration out of PSHome][moving] |
112+
| GPO -> User Policy | HKCU\Software\Policies\PowerShellCore | %XDG_CONFIG_HOME%/powershell.config.json |
113+
| File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` |
114+
| File -> Computer-Wide | See [Moving configuration out of PSHome][moving] | [Moving configuration out of PSHome][moving] |
115+
| File -> User-Wide | %APPDATA%/powershell.config.json | %XDG_CONFIG_HOME%/powershell.config.json |
116+
117+
Defaults:
118+
119+
`%APPDATA%` - `C:\Users\useraccount\AppData\Roaming`
120+
121+
`%XDG_CONFIG_HOME%` - `HOME/.config`
122+
123+
#### Parameter `-settingsfile`
124+
125+
With `-settingsfile` parameter users can assign custom settings from the config file and overwrite user-wide settings.
126+
127+
##### More definitions
128+
129+
- System Lock-down mode:
130+
When Windows Defender Application Control or AppLocker force PowerShell into Constrained Language mode and
131+
only trusted code runs in Full Language mode.
132+
See [PowerShell Constrained Language Mode](https://devblogs.microsoft.com/powershell/powershell-constrained-language-mode/)
133+
134+
##### Computer-wide and per-user policy settings
135+
136+
Admin/root users can overwrite computer-wide and per-user policy settings using `-settingsfile`,
137+
only when not in System Lock-down mode.
138+
139+
This will have performance impact on startup, but only when `-settingsfile` is specified.
140+
141+
#### Precedence for Per-user settings in descending order
142+
143+
Note, this is listed as `User, then Computer` in [Registry keys and settings](#registry-keys-and-settings).
144+
145+
| Scheme | Windows | Unix |
146+
|-----------------------------|------------------------------------------------------|------------------------------------------------------|
147+
| GPO -> User Config | HKCU\Software\PowerShellCore | %XDG_CONFIG_HOME%/powershell.config.json |
148+
| GPO -> Computer Config | HKLM\Software\PowerShellCore | See [Moving configuration out of PSHome][moving] |
149+
| File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` |
150+
| File -> User-Wide | %APPDATA%\powershell.config.json | %XDG_CONFIG_HOME%/powershell.config.json |
151+
| File -> Computer-Wide | See [Moving configuration out of PSHome][moving] | /opt/Microsoft/powershell/powershell.config.json |
152+
153+
#### Precedence for UpdatableHelp in descending order
154+
155+
Note, this is listed as `Computer` in [Registry keys and settings](#registry-keys-and-settings).
156+
157+
| Scheme | Windows | Unix |
158+
|-----------------------------|------------------------------------------------------|------------------------------------------------------|
159+
| GPO -> Computer Config | HKLM\Software\PowerShellCore | See [Moving configuration out of PSHome][moving] |
160+
| File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` |
161+
| File -> Computer-Wide | See [Moving configuration out of PSHome][moving] | /opt/Microsoft/powershell/powershell.config.json |
162+
163+
### Configuration settings
164+
165+
A set of configuration settings in GPO scheme and file scheme for policy settings and regular settings is the same. This allows to discover and configure settings in the simplest and fastest way.
166+
167+
#### Registry keys and settings
168+
169+
Notes:
170+
171+
- All policies are in `Software\Policies\PowerShellCore`.
172+
- `ExecutionPolicy` is not in any SubKey.
173+
174+
| SubKey | Option | Type | Precedence |
175+
|-----------------------------|------------------------------------|--------|---------------------|
176+
| - | - | | |
177+
| - | - | | |
178+
| | ExecutionPolicy | String | Computer, Then User |
179+
| ConsoleSessionConfiguration | EnableConsoleSessionConfiguration | DWORD | User, then Computer |
180+
| ConsoleSessionConfiguration | ConsoleSessionConfigurationName | String | User, then Computer |
181+
| ModuleLogging | EnableModuleLogging | DWORD | Computer, Then User |
182+
| ModuleLogging | ModuleNames | String | Computer, Then User |
183+
| ProtectedEventLogging | EncryptionCertificate | DWORD | Computer Wide |
184+
| ScriptBlockLogging | EnableScriptBlockInvocationLogging | DWORD | Computer, Then User |
185+
| ScriptBlockLogging | EnableScriptBlockLogging | DWORD | Computer, Then User |
186+
| Transcription | EnableTranscripting | DWORD | Computer, Then User |
187+
| Transcription | EnableInvocationHeader | DWORD | Computer, Then User |
188+
| Transcription | OutputDirectory | String | Computer, Then User |
189+
| UpdatableHelp | DefaultSourcePath | String | Computer Wide |
190+
191+
I filed [#9632](https://github.com/PowerShell/PowerShell/issues/9632) on UpdatableHelp-DefaultSourcePath to make it allow Per-user settings.
192+
193+
#### JSON file settings format
194+
195+
```json
196+
{
197+
"PowerShell": {
198+
"RegularSettings": {
199+
"ConsoleSessionConfiguration": {
200+
"EnableConsoleSessionConfiguration": true,
201+
"ConsoleSessionConfigurationName": "name"
202+
},
203+
"ProtectedEventLogging": {
204+
"EnableProtectedEventLogging": false,
205+
"EncryptionCertificate": [
206+
"Joe"
207+
]
208+
},
209+
"ScriptBlockLogging": {
210+
"EnableScriptBlockInvocationLogging": true,
211+
"EnableScriptBlockLogging": false
212+
},
213+
"ScriptExecution": {
214+
"ExecutionPolicy": "RemoteSigned",
215+
"PipelineMaxStackSizeMB": 10
216+
},
217+
"Transcription": {
218+
"EnableTranscripting": true,
219+
"EnableInvocationHeader": true,
220+
"OutputDirectory": "c:\\tmp"
221+
},
222+
"UpdatableHelp": {
223+
"DefaultSourcePath": "f:\\temp"
224+
}
225+
},
226+
227+
"PoliciesSettings": {
228+
...
229+
}
230+
}
231+
}
232+
```
233+
234+
## Alternate Proposals and Considerations
235+
236+
### Automatically resolve Windows PowerShell policy conflicts
237+
238+
#### Motivation - Automatically policy
239+
240+
This is a description of the alternative to [Policy settings Setting Fall-Back](#policy-settings-setting-fall-back).
241+
The main purpose of describing the alternative is to describe why it should not be pursued.
242+
243+
#### Description
244+
245+
PowerShell could attempt to resolve policy conflicts between PowerShell 7 policy and Windows PowerShell policy.
246+
This would make the `Precedence for Policy settings` not just a simple list but a complex set of rules that would not be easily understood. See [this conversation](https://github.com/PowerShell/PowerShell/issues/9309?#issuecomment-480643922).
247+
248+
### Allowing environment variable in the JSON
249+
250+
A new RFC should be drafted about how to allow environment variables in the values in the JSON.
251+
This would allow consistent files across platforms.
252+
253+
### Moving configuration out of PSHome
254+
255+
Per issues [9278](https://github.com/PowerShell/PowerShell/issues/9278) we need to move configuration out of PSHome,
256+
follow that issue for issues related to new locations of files.
257+
258+
[moving]:#moving-configuration-out-of-pshome
259+
260+
### Allowing Regular settings from the registry in Windows
261+
262+
This is out of scope of this RFCs

0 commit comments

Comments
 (0)