Skip to content

Commit 51e01d2

Browse files
chore: sync PowerShell standards 2.0.0 (#59)
Co-authored-by: fadwen <110697945+fadwen@users.noreply.github.com>
1 parent 29a5780 commit 51e01d2

8 files changed

Lines changed: 273 additions & 11 deletions

File tree

‎.agents/skills/powershell-security-review/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ Read `.github/instructions/powershell-security.instructions.md` first, unless it
1515
- Secrets and credentials: SEC-01 to SEC-08, and SEC-50 to SEC-53 where the code uses a secret
1616
vault. Search for literals that look like passwords, tokens, keys, and connection strings,
1717
including in comments, defaults, and test data.
18+
- Web requests that carry a credential: SEC-09. Look for a request that does not pass
19+
`-MaximumRedirection 0`, and for `-FollowRelLink` and `-PreserveAuthorizationOnRedirect`.
1820
- Command construction: SEC-10. Look for `Invoke-Expression`, `[scriptblock]::Create()`,
1921
`Start-Process` with a built argument string, and strings passed to `cmd /c` or `pwsh -Command`.
2022
- Paths: SEC-12. Look for input joined into a path that is then read, written, or deleted.

‎.claude/skills/powershell-security-review/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ Read `.github/instructions/powershell-security.instructions.md` first, unless it
1515
- Secrets and credentials: SEC-01 to SEC-08, and SEC-50 to SEC-53 where the code uses a secret
1616
vault. Search for literals that look like passwords, tokens, keys, and connection strings,
1717
including in comments, defaults, and test data.
18+
- Web requests that carry a credential: SEC-09. Look for a request that does not pass
19+
`-MaximumRedirection 0`, and for `-FollowRelLink` and `-PreserveAuthorizationOnRedirect`.
1820
- Command construction: SEC-10. Look for `Invoke-Expression`, `[scriptblock]::Create()`,
1921
`Start-Process` with a built argument string, and strings passed to `cmd /c` or `pwsh -Command`.
2022
- Paths: SEC-12. Look for input joined into a path that is then read, written, or deleted.

‎.github/instructions/powershell-cicd.instructions.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -388,6 +388,10 @@ the deployment only for the main branch and the publish only for a version tag.
388388
The matrix lists the operating systems that the project declares. Windows PowerShell 5.1 is one more
389389
job (CIC-03). PowerShell 7.4 and 7.5 are past end of support and stay out of every matrix (CIC-04).
390390

391+
GitHub's hosted runners carry PowerShell 7.6, the LTS release, so `shell: pwsh` runs 7.6 there and
392+
a job that tests on PowerShell 7.7 has to install it first. That was the state of the Ubuntu 24.04,
393+
Windows Server 2025, and macOS 15 images on 2026-11-17.
394+
391395
### Release, signing, and deployment (CIC-18 to CIC-20)
392396

393397
- Versioning: the next semantic version is derived from the commit messages (PRQ-10 to PRQ-12), a

‎.github/instructions/powershell-modules.instructions.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ A Gallery version is in use from the moment it uploads. It can be unlisted but n
215215
passed every local check and then shipped the wrong content or failed at the upload.
216216

217217
**MOD-10, MOD-11.** When the repository is the module root, publishing that folder packs the working
218-
tree. Measured with Microsoft.PowerShell.PSResourceGet 1.2.0: the package contains `.git`, the tests,
218+
tree. Measured with Microsoft.PowerShell.PSResourceGet 1.2.0 and 1.3.1: the package contains `.git`, the tests,
219219
and the build scripts. Measured on one module: 313 files and 975 KB, all 213 files of `.git` among
220220
them, against 46 files and 507 KB for the module itself. A staging folder ships only what the
221221
allowlist names:
@@ -309,7 +309,7 @@ foreach ($measurement in $measurements) {
309309

310310
A module that exports cmdlets or DSC resources gains further tags of the same kind.
311311

312-
**MOD-13.** `IconUri = ''` is not "no icon". Measured with PSResourceGet 1.2.0, the pack fails with
312+
**MOD-13.** `IconUri = ''` is not "no icon". Measured with PSResourceGet 1.2.0 and 1.3.1, the pack fails with
313313
`IconUrl cannot be empty`, and the message names neither the manifest nor the key. `ProjectUri = ''`
314314
and `LicenseUri = ''` fail the same way. Have the rehearsal check for an empty URI key:
315315

‎.github/instructions/powershell-pull-requests.instructions.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,10 @@ before it.
3131
- **PRQ-11** The type is `feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `ci`, `build`, or `chore`,
3232
and a release is `release: X.Y.Z`. The subject is imperative, lower case, has no trailing period,
3333
and is at most 72 characters.
34-
- **PRQ-12** Wrap the body at 72 columns and explain why the change was needed. Mark a breaking
35-
change with `!` after the type or scope and a `BREAKING CHANGE:` footer that says what a caller
36-
must do.
34+
- **PRQ-12** Wrap the body of a commit message at 72 columns and explain why the change was needed.
35+
Mark a breaking change with `!` after the type or scope and a `BREAKING CHANGE:` footer that says
36+
what a caller must do. A pull request description or a comment MUST NOT be wrapped that way:
37+
write each paragraph and each list item on one line.
3738
- **PRQ-13** Commits, titles, pull request bodies, and files MUST NOT carry AI tool attribution: no
3839
`Co-Authored-By` trailer for a tool and no "Generated with" footer.
3940

@@ -91,6 +92,13 @@ if ([int]$behind -gt 0) {
9192
`feat(graph)`, `fix(release)`, `docs(pester)`. The subject says what the change does, not which
9293
files it touched.
9394

95+
**PRQ-12.** GitHub renders a line break inside a paragraph or a list item of a pull request
96+
description or a comment as a line break. It joins the lines of a Markdown file in a repository,
97+
so text that is wrapped like the repository's files reads as short broken lines once it is posted.
98+
Measured on 2026-11-18 with GitHub's Markdown API: `gfm` mode, which is how a comment is rendered,
99+
gave one `<br>` for each wrapped line, and `markdown` mode, which is how a file is rendered, gave
100+
none. A description wrapped at 100 columns was shown with 67 such breaks.
101+
94102
**PRQ-20, PRQ-21.** Commit messages and pull requests are permanent records. They are read months
95103
later by reviewers and maintainers who never saw the conversation that produced the change.
96104

‎.github/instructions/powershell-security.instructions.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ These rules apply to every `.ps1` and `.psm1` file.
3535
- **SEC-08** Hold sensitive data in a `SecureString`. A script that a person runs interactively
3636
reads it with `Read-Host -AsSecureString`; a function or an unattended script does not prompt
3737
(SEC-05).
38+
- **SEC-09** A web request that carries a credential MUST pass `-MaximumRedirection 0`, so that a
39+
redirect is an error, and MUST NOT be paged with `-FollowRelLink`. Follow a redirect or a link in
40+
the function, and send the credential again only when the address has the scheme, host, and port
41+
of the first request.
3842

3943
### Input and execution
4044

@@ -170,6 +174,174 @@ foreach ($key in $context.Keys) {
170174
}
171175
```
172176

177+
**SEC-09.** Measured on PowerShell 7.6.10 and 7.7.0, against a local server that answers as two
178+
hosts:
179+
180+
| Where the request goes | `Authorization` header | A key in another header, such as `X-Api-Key` |
181+
| --- | --- | --- |
182+
| A link followed by `-FollowRelLink` | Not sent, since PowerShell 7.6.5 | Sent, to another host as well |
183+
| The same with `-PreserveAuthorizationOnRedirect` | Sent, to another host as well | Sent, to another host as well |
184+
| The target of a redirect | Not sent | Sent, to another host as well |
185+
186+
With `-FollowRelLink` alone, every page after the first is requested as an anonymous caller. The
187+
service refuses, or answers with only what an anonymous caller may see, and then no error is raised.
188+
With `-PreserveAuthorizationOnRedirect`, the credential goes wherever a reply points. Windows
189+
PowerShell 5.1 has no `-FollowRelLink`, and it treats a redirect as the last row says.
190+
191+
A redirect does the same to any request, paged or not: the cmdlet follows it without the
192+
`Authorization` header, to the same host as well. The caller gets an error where the address needs
193+
the credential, and the answer for an anonymous caller, with no error, where it does not. A key in
194+
another header goes with the redirect to any host. A credential passed as `-Credential` alone was
195+
not sent to the other host, and that request ended with an error. With `-UseDefaultCredentials`,
196+
the versions differ. When the other host asked for Windows authentication, PowerShell 7 did not
197+
answer and ended with an error, and Windows PowerShell 5.1 began to authenticate there as the
198+
current user. The test server ended that exchange after its first message.
199+
200+
With `-MaximumRedirection 0`, no request reaches the address that the redirect names, on all three
201+
versions. PowerShell 7 raises the refused redirect as an error whose exception carries the reply,
202+
with the address in `Response.Headers.Location`. Windows PowerShell 5.1, and PowerShell 7 with
203+
`-SkipHttpErrorCheck`, return the reply, with the address in `Headers['Location']`, and write a
204+
non-terminating error, so `-ErrorAction Stop` loses the address. A service that redirects by
205+
design, such as a download that answers with a signed address on another host, is followed in the
206+
function, and the credential goes with it only to the scheme, host, and port of the first request.
207+
208+
The function below follows the links itself and lets no redirect be followed. `$Request` holds the
209+
parameters of `Invoke-WebRequest`, the credential among them. The function and its tests are files
210+
in the standards repository, under `standards/examples`:
211+
212+
```powershell
213+
function Get-PagedResponse {
214+
<#
215+
.SYNOPSIS
216+
Gets every page of a paged web request that carries a credential.
217+
218+
.DESCRIPTION
219+
Requests the first page, follows each link that a reply marks as rel="next" in its Link header,
220+
and writes the body of each page as text. The credential in the request is sent with every
221+
page, and only to the scheme, host, and port of the first request. A next link to another
222+
host, a next link to a page that was already requested, a redirect, and a failed request each
223+
end the function with a terminating error.
224+
225+
.PARAMETER Request
226+
The parameters of Invoke-WebRequest for the first page, as a hashtable. It must have a Uri key,
227+
and it holds the credential, for example in Headers, or in Authentication and Token. The
228+
function sets UseBasicParsing, ErrorAction, and MaximumRedirection itself.
229+
230+
.EXAMPLE
231+
Get-PagedResponse -Request @{ Uri = 'https://api.example.com/items'; Headers = $headers } | ConvertFrom-Json
232+
233+
Gets every page of the item list and converts each one from JSON. $headers holds the
234+
Authorization header.
235+
236+
.INPUTS
237+
None.
238+
239+
.OUTPUTS
240+
System.String. The body of each page.
241+
#>
242+
[CmdletBinding()]
243+
[OutputType([string])]
244+
param(
245+
[Parameter(Mandatory)]
246+
[ValidateScript({ $_.ContainsKey('Uri') })]
247+
[hashtable]$Request
248+
)
249+
250+
$firstUri = [uri]$Request['Uri']
251+
$pageRequest = $Request.Clone()
252+
$pageRequest['UseBasicParsing'] = $true
253+
$pageRequest['ErrorAction'] = 'Stop'
254+
# Invoke-WebRequest follows a redirect without the Authorization header, and the page then
255+
# arrives as an anonymous caller sees it. With this value a redirect is an error instead.
256+
$pageRequest['MaximumRedirection'] = 0
257+
$requestedUris = [System.Collections.Generic.HashSet[string]]::new()
258+
$pageUri = $firstUri
259+
while ($null -ne $pageUri) {
260+
$null = $requestedUris.Add($pageUri.AbsoluteUri)
261+
$pageRequest['Uri'] = $pageUri
262+
try {
263+
$response = Invoke-WebRequest @pageRequest
264+
} catch {
265+
# PowerShell 7 puts the refused reply on the exception. Windows PowerShell 5.1 has no
266+
# reply there and names the error instead.
267+
$status = 0
268+
$reply = $_.Exception.PSObject.Properties['Response']
269+
if ($null -ne $reply -and $null -ne $reply.Value) {
270+
$status = [int]$reply.Value.StatusCode
271+
}
272+
$isRedirect = ($status -in 301, 302, 303, 307, 308 -or
273+
$_.FullyQualifiedErrorId -like 'MaximumRedirectExceeded*')
274+
if (-not $isRedirect) {
275+
$PSCmdlet.ThrowTerminatingError($_)
276+
}
277+
278+
# The address is reported without its query string, which can carry a token.
279+
$target = $pageUri.GetLeftPart([System.UriPartial]::Path)
280+
$message = "The request for '$target' was answered with a redirect. It was not followed."
281+
$exception = [System.InvalidOperationException]::new($message, $_.Exception)
282+
$category = [System.Management.Automation.ErrorCategory]::InvalidResult
283+
$errorRecord = [System.Management.Automation.ErrorRecord]::new(
284+
$exception, 'PageRedirected', $category, $target)
285+
$PSCmdlet.ThrowTerminatingError($errorRecord)
286+
}
287+
288+
# A body whose content type is not a text type, such as application/vnd.api+json, is bytes.
289+
if ($response.Content -is [byte[]]) {
290+
[System.Text.Encoding]::UTF8.GetString($response.Content)
291+
} else {
292+
$response.Content
293+
}
294+
295+
# The header value is a string on Windows PowerShell 5.1 and a list of strings on PowerShell 7.
296+
$linkText = ($response.Headers.GetEnumerator() |
297+
Where-Object -Property Key -EQ -Value 'Link' |
298+
ForEach-Object { $_.Value }) -join ','
299+
$nextUri = $null
300+
foreach ($link in $linkText -split ',\s*(?=<)') {
301+
$match = [regex]::Match($link, '^\s*<([^>]+)>.*\brel="?[^";]*\bnext\b')
302+
if ($match.Success) {
303+
$nextUri = [uri]::new($pageUri, $match.Groups[1].Value)
304+
break
305+
}
306+
}
307+
308+
$errorId = $null
309+
if ($null -ne $nextUri) {
310+
$sameOrigin = ($nextUri.Scheme -eq $firstUri.Scheme -and $nextUri.Host -eq $firstUri.Host -and
311+
$nextUri.Port -eq $firstUri.Port)
312+
if (-not $sameOrigin) {
313+
$errorId = 'NextPageOnAnotherHost'
314+
$category = [System.Management.Automation.ErrorCategory]::SecurityError
315+
$message = "The next page is on another host, '$($nextUri.Host)'. It was not requested."
316+
} elseif ($requestedUris.Contains($nextUri.AbsoluteUri)) {
317+
$errorId = 'NextPageAlreadyRequested'
318+
$category = [System.Management.Automation.ErrorCategory]::InvalidResult
319+
$message = 'The next link names a page that was already requested. It was not requested again.'
320+
}
321+
}
322+
323+
if ($null -ne $errorId) {
324+
$exception = [System.InvalidOperationException]::new($message)
325+
$target = $nextUri.GetLeftPart([System.UriPartial]::Path)
326+
$errorRecord = [System.Management.Automation.ErrorRecord]::new(
327+
$exception, $errorId, $category, $target)
328+
$PSCmdlet.ThrowTerminatingError($errorRecord)
329+
}
330+
331+
$pageUri = $nextUri
332+
}
333+
}
334+
```
335+
336+
Run on PowerShell 7.7.0, PowerShell 7.6.10, and Windows PowerShell 5.1 under strict mode, against the
337+
same server. Three pages arrived with the credential on each, whether the link was absolute or
338+
relative, stood among other relations, or came in a header named `link`. Each of these ended the
339+
function with an error and without a further request: a next link on another host, a next link
340+
back to the first page, and a redirect, at the first page or at a later one. The function reports
341+
the redirect as `PageRedirected` on all three versions, where the errors of the cmdlet differ. A
342+
body with the content type `application/vnd.api+json` arrived as text, where `Invoke-WebRequest`
343+
returns bytes.
344+
173345
**SEC-10.** Arguments passed as an array reach a native executable as separate arguments, so input
174346
cannot add switches or commands:
175347

0 commit comments

Comments
 (0)