Skip to content

Commit 75a8e45

Browse files
TravisEz13TravisEz13
committed
Draft policy RFC
1 parent 9cdb1ef commit 75a8e45

File tree

1 file changed

+236
-0
lines changed

1 file changed

+236
-0
lines changed

‎1-Draft/RFCXXXX-Policy.md

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
---
2+
RFC: RFCnnnn
3+
Author: travisez13
4+
Status: Draft
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 reliable way to 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+
## Specification
23+
24+
`PowerShell 7` should be configured using the following schemes:
25+
26+
- On Windows - Group Policy Objects (GPO), Group Policy Preferences (GPP) and settings files.
27+
- On Unix - settings files.
28+
29+
The settings files have `JSON` format.
30+
31+
**Warning** The settings files differ from `PowerShell 7` _profile_ files, which are PowerShell scripts run at startup.
32+
33+
Configuration schemes allow to customize `PowerShell 7` in the most flexible way:
34+
35+
- Enterprise system administrators can use GPO,
36+
GPP and computer-wide settings files to apply approved configuration settings and mandatory security settings in a centralized manner.
37+
The same settings can be applied at user, application or startup levels.
38+
- Developers and consumers can use user, application and startup level settings files.
39+
40+
### Configuration defaults
41+
42+
PowerShell 7 has hard-coded defaults for all configuration options.
43+
44+
The default values must be `secure-by-default`.
45+
46+
For release versions hard-coded defaults must be the same as ones in re-installed configuration files. For preview versions they may vary (ex., enable experimental features and so on).
47+
48+
If during startup PowerShell 7 cannot read system configuration files it fails to startup.
49+
50+
If during startup PowerShell 7 cannot read user configuration files it uses _hardcoded_ defaults.
51+
52+
If during operation PowerShell 7 cannot read configuration files it continue to use _current_ (runtime) configuration values.
53+
54+
### Settings locations
55+
56+
`PowerShell 7` settings are grouped into `Policy settings` and `Regular settings`.
57+
Regular settings are normal configuration settings.
58+
Regular settings can be treated as default values.
59+
Policy settings is high priority and overlap regular settings.
60+
Policy settings are used by administrators to centrally manage applications.
61+
62+
| Location | Policy settings | Regular settings |
63+
|--------------|-----------------------------------------------------------|------------------------------------------------------------|
64+
| File section | "PowerShell": { "PolicySettings": {...} } | "PowerShell": { "RegularSettings": {...} } |
65+
| File section | "OtherPowerShellApplication": { "PolicySettings": {...} } | "OtherPowerShellApplication": { "RegularSettings": {...} } |
66+
| Registry key | Software\Policies\PowerShellCore | Software\PowerShellCore |
67+
68+
### Policy settings Setting Fall-Back
69+
70+
#### Motivation - Policy Setting Fall-Back
71+
72+
This is to allow Fall-back to Windows PowerShell policies.
73+
74+
#### Implementation
75+
76+
For Policy Settings,
77+
each policy should have a `Use Windows PowerShell Policy` which will indicate that the policy should the read from
78+
`SOFTWARE\Policies\Microsoft\Windows\PowerShell` instead of `Software\Policies\PowerShellCore`.
79+
80+
### Precedence of applying settings
81+
82+
Because a configuration setting can be in several schemes, the setting wins according to the priority of its scheme.
83+
84+
#### Precedence for Policy settings in descending order
85+
86+
| Scheme | Windows | Unix |
87+
|-----------------------------|------------------------------------------------------|------------------------------------------------------|
88+
| GPO -> Computer Policy | HKLM\Software\Policies\PowerShellCore | /etc/powershell.config.json |
89+
| GPO -> User Policy | HKCU\Software\Policies\PowerShellCore | See `Comment A` below |
90+
| File -> Computer-Wide | %ProgramFiles%/PowerShell/powershell.config.json | /opt/Microsoft/powershell/powershell.config.json |
91+
| File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` |
92+
| File -> User-Wide | %APPDATA%/powershell.config.json | %XDG_CONFIG_HOME%/powershell.config.json |
93+
| File -> Application-Wide | $apphome/powershell.config.json | $apphome/powershell.config.json |
94+
95+
Defaults:
96+
97+
`%APPDATA%` - `C:\Users\useraccount\AppData\Roaming`
98+
99+
`%XDG_CONFIG_HOME%` - `HOME/.config`
100+
101+
#### Parameter `-settingsfile`
102+
103+
With `-settingsfile` parameter users can assign custom settings from the config file and overwrite user-wide and application-wide settings.
104+
105+
##### Computer-wide and user policy settings
106+
107+
**No** user can overwrite computer-wide and user policy settings using `-settingsfile`
108+
109+
#### Priorities for Regular settings in descending order
110+
111+
| Scheme | Windows | Unix |
112+
|-----------------------------|------------------------------------------------------|------------------------------------------------------|
113+
| File -> Application-Startup | pwsh -settingsfile `somepath/powershell.config.json` | pwsh -settingsfile `somepath/powershell.config.json` |
114+
| File -> Application-Wide | $apphome\powershell.config.json | $apphome/powershell.config.json |
115+
| File -> User-Wide | %APPDATA%\powershell.config.json | ~/powershell.config.json |
116+
| File -> Computer-Wide | %ProgramFiles%\PowerShell\powershell.config.json | /opt/Microsoft/powershell/powershell.config.json |
117+
| GPO -> User Config | HKCU\Software\PowerShellCore | See `Comment A` below |
118+
| GPO -> Computer Config | HKLM\Software\PowerShellCore | /etc/powershell.config.json |
119+
120+
### Configuration settings
121+
122+
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.
123+
124+
#### Registry keys and settings
125+
126+
| Key | SubKey | Option | Type | Precedence |
127+
|----------------------------------|-----------------------------|------------------------------------|--------|---------------------|
128+
| Software\Policies\PowerShellCore | - | - | | |
129+
| Software\PowerShellCore | - | - | | |
130+
| | | ExecutionPolicy | String | Computer, Then User |
131+
| | ConsoleSessionConfiguration | EnableConsoleSessionConfiguration | DWORD | User, then Computer |
132+
| | ConsoleSessionConfiguration | ConsoleSessionConfigurationName | String | User, then Computer |
133+
| | ModuleLogging | EnableModuleLogging | DWORD | Computer, Then User |
134+
| | ModuleLogging | ModuleNames | String | Computer, Then User |
135+
| | ProtectedEventLogging | EncryptionCertificate | DWORD | Computer Wide |
136+
| | ScriptBlockLogging | EnableScriptBlockInvocationLogging | DWORD | Computer, Then User |
137+
| | ScriptBlockLogging | EnableScriptBlockLogging | DWORD | Computer, Then User |
138+
| | Transcription | EnableTranscripting | DWORD | Computer, Then User |
139+
| | Transcription | EnableInvocationHeader | DWORD | Computer, Then User |
140+
| | Transcription | OutputDirectory | String | Computer, Then User |
141+
| | UpdatableHelp | DefaultSourcePath | String | Computer Wide |
142+
143+
#### JSON file settings format
144+
145+
```json
146+
{
147+
"PowerShell": {
148+
"RegularSettings": {
149+
"ConsoleSessionConfiguration": {
150+
"EnableConsoleSessionConfiguration": true,
151+
"ConsoleSessionConfigurationName": "name"
152+
},
153+
"ProtectedEventLogging": {
154+
"EnableProtectedEventLogging": false,
155+
"EncryptionCertificate": [
156+
"Joe"
157+
]
158+
},
159+
"ScriptBlockLogging": {
160+
"EnableScriptBlockInvocationLogging": true,
161+
"EnableScriptBlockLogging": false
162+
},
163+
"ScriptExecution": {
164+
"ExecutionPolicy": "RemoteSigned",
165+
"PipelineMaxStackSizeMB": 10
166+
},
167+
"Transcription": {
168+
"EnableTranscripting": true,
169+
"EnableInvocationHeader": true,
170+
"OutputDirectory": "c:\\tmp"
171+
},
172+
"UpdatableHelp": {
173+
"DefaultSourcePath": "f:\\temp"
174+
}
175+
},
176+
177+
"PoliciesSettings": {
178+
...
179+
}
180+
},
181+
182+
"OtherPowerShellApplication": {
183+
"RegularSettings": {
184+
...
185+
},
186+
"PolicySettings": {
187+
...
188+
}
189+
}
190+
```
191+
192+
## Alternate Proposals and Considerations
193+
194+
### Automatically resolve Windows PowerShell policy conflicts
195+
196+
We could attempt to resolve policy conflicts between PowerShell 7 policy and Windows PowerShell policy.
197+
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).
198+
199+
### Allow admins to overwrite computer-wide settings
200+
201+
In System Lock-down mode, we attempt to protect from the admin,
202+
so allowing computer-wide or policy setting to be overwritten at the command-line is dangerous.
203+
204+
We could try to check for System Lock-down mode and
205+
admin user and allow `-settingsfile` to overwrite computer-wide settings.
206+
207+
But, performing the system lock-down check this early would hurt startup performance.
208+
209+
I don't recommend this approach.
210+
211+
### Comment A
212+
213+
Mainly for Unix we'd add `Users` section to computer wide JSON file (`/etc/powershell.config.json`) to allow administrators set policies and regular settings on user level base
214+
215+
```json
216+
{
217+
"PowerShell": {
218+
"RegularSettings": {
219+
...
220+
},
221+
"PolicySettings": {
222+
...
223+
},
224+
"Users": {
225+
"Smith": {
226+
"PowerShell": {
227+
"RegularSettings": {
228+
...
229+
},
230+
"PolicySettings": {
231+
...
232+
}
233+
}
234+
}
235+
}
236+
```

0 commit comments

Comments
 (0)