Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .agents/skills/powershell-security-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ Read `.github/instructions/powershell-security.instructions.md` first, unless it
- Secrets and credentials: SEC-01 to SEC-08, and SEC-50 to SEC-53 where the code uses a secret
vault. Search for literals that look like passwords, tokens, keys, and connection strings,
including in comments, defaults, and test data.
- Web requests that carry a credential: SEC-09. Look for a request that does not pass
`-MaximumRedirection 0`, and for `-FollowRelLink` and `-PreserveAuthorizationOnRedirect`.
- Command construction: SEC-10. Look for `Invoke-Expression`, `[scriptblock]::Create()`,
`Start-Process` with a built argument string, and strings passed to `cmd /c` or `pwsh -Command`.
- Paths: SEC-12. Look for input joined into a path that is then read, written, or deleted.
Expand Down
2 changes: 2 additions & 0 deletions .claude/skills/powershell-security-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ Read `.github/instructions/powershell-security.instructions.md` first, unless it
- Secrets and credentials: SEC-01 to SEC-08, and SEC-50 to SEC-53 where the code uses a secret
vault. Search for literals that look like passwords, tokens, keys, and connection strings,
including in comments, defaults, and test data.
- Web requests that carry a credential: SEC-09. Look for a request that does not pass
`-MaximumRedirection 0`, and for `-FollowRelLink` and `-PreserveAuthorizationOnRedirect`.
- Command construction: SEC-10. Look for `Invoke-Expression`, `[scriptblock]::Create()`,
`Start-Process` with a built argument string, and strings passed to `cmd /c` or `pwsh -Command`.
- Paths: SEC-12. Look for input joined into a path that is then read, written, or deleted.
Expand Down
4 changes: 4 additions & 0 deletions .github/instructions/powershell-cicd.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -388,6 +388,10 @@ the deployment only for the main branch and the publish only for a version tag.
The matrix lists the operating systems that the project declares. Windows PowerShell 5.1 is one more
job (CIC-03). PowerShell 7.4 and 7.5 are past end of support and stay out of every matrix (CIC-04).

GitHub's hosted runners carry PowerShell 7.6, the LTS release, so `shell: pwsh` runs 7.6 there and
a job that tests on PowerShell 7.7 has to install it first. That was the state of the Ubuntu 24.04,
Windows Server 2025, and macOS 15 images on 2026-11-17.

### Release, signing, and deployment (CIC-18 to CIC-20)

- Versioning: the next semantic version is derived from the commit messages (PRQ-10 to PRQ-12), a
Expand Down
4 changes: 2 additions & 2 deletions .github/instructions/powershell-modules.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ A Gallery version is in use from the moment it uploads. It can be unlisted but n
passed every local check and then shipped the wrong content or failed at the upload.

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

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

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

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

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

**PRQ-12.** GitHub renders a line break inside a paragraph or a list item of a pull request
description or a comment as a line break. It joins the lines of a Markdown file in a repository,
so text that is wrapped like the repository's files reads as short broken lines once it is posted.
Measured on 2026-11-18 with GitHub's Markdown API: `gfm` mode, which is how a comment is rendered,
gave one `<br>` for each wrapped line, and `markdown` mode, which is how a file is rendered, gave
none. A description wrapped at 100 columns was shown with 67 such breaks.

**PRQ-20, PRQ-21.** Commit messages and pull requests are permanent records. They are read months
later by reviewers and maintainers who never saw the conversation that produced the change.

Expand Down
172 changes: 172 additions & 0 deletions .github/instructions/powershell-security.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ These rules apply to every `.ps1` and `.psm1` file.
- **SEC-08** Hold sensitive data in a `SecureString`. A script that a person runs interactively
reads it with `Read-Host -AsSecureString`; a function or an unattended script does not prompt
(SEC-05).
- **SEC-09** A web request that carries a credential MUST pass `-MaximumRedirection 0`, so that a
redirect is an error, and MUST NOT be paged with `-FollowRelLink`. Follow a redirect or a link in
the function, and send the credential again only when the address has the scheme, host, and port
of the first request.

### Input and execution

Expand Down Expand Up @@ -170,6 +174,174 @@ foreach ($key in $context.Keys) {
}
```

**SEC-09.** Measured on PowerShell 7.6.10 and 7.7.0, against a local server that answers as two
hosts:

| Where the request goes | `Authorization` header | A key in another header, such as `X-Api-Key` |
| --- | --- | --- |
| A link followed by `-FollowRelLink` | Not sent, since PowerShell 7.6.5 | Sent, to another host as well |
| The same with `-PreserveAuthorizationOnRedirect` | Sent, to another host as well | Sent, to another host as well |
| The target of a redirect | Not sent | Sent, to another host as well |

With `-FollowRelLink` alone, every page after the first is requested as an anonymous caller. The
service refuses, or answers with only what an anonymous caller may see, and then no error is raised.
With `-PreserveAuthorizationOnRedirect`, the credential goes wherever a reply points. Windows
PowerShell 5.1 has no `-FollowRelLink`, and it treats a redirect as the last row says.

A redirect does the same to any request, paged or not: the cmdlet follows it without the
`Authorization` header, to the same host as well. The caller gets an error where the address needs
the credential, and the answer for an anonymous caller, with no error, where it does not. A key in
another header goes with the redirect to any host. A credential passed as `-Credential` alone was
not sent to the other host, and that request ended with an error. With `-UseDefaultCredentials`,
the versions differ. When the other host asked for Windows authentication, PowerShell 7 did not
answer and ended with an error, and Windows PowerShell 5.1 began to authenticate there as the
current user. The test server ended that exchange after its first message.

With `-MaximumRedirection 0`, no request reaches the address that the redirect names, on all three
versions. PowerShell 7 raises the refused redirect as an error whose exception carries the reply,
with the address in `Response.Headers.Location`. Windows PowerShell 5.1, and PowerShell 7 with
`-SkipHttpErrorCheck`, return the reply, with the address in `Headers['Location']`, and write a
non-terminating error, so `-ErrorAction Stop` loses the address. A service that redirects by
design, such as a download that answers with a signed address on another host, is followed in the
function, and the credential goes with it only to the scheme, host, and port of the first request.

The function below follows the links itself and lets no redirect be followed. `$Request` holds the
parameters of `Invoke-WebRequest`, the credential among them. The function and its tests are files
in the standards repository, under `standards/examples`:

```powershell
function Get-PagedResponse {
<#
.SYNOPSIS
Gets every page of a paged web request that carries a credential.

.DESCRIPTION
Requests the first page, follows each link that a reply marks as rel="next" in its Link header,
and writes the body of each page as text. The credential in the request is sent with every
page, and only to the scheme, host, and port of the first request. A next link to another
host, a next link to a page that was already requested, a redirect, and a failed request each
end the function with a terminating error.

.PARAMETER Request
The parameters of Invoke-WebRequest for the first page, as a hashtable. It must have a Uri key,
and it holds the credential, for example in Headers, or in Authentication and Token. The
function sets UseBasicParsing, ErrorAction, and MaximumRedirection itself.

.EXAMPLE
Get-PagedResponse -Request @{ Uri = 'https://api.example.com/items'; Headers = $headers } | ConvertFrom-Json

Gets every page of the item list and converts each one from JSON. $headers holds the
Authorization header.

.INPUTS
None.

.OUTPUTS
System.String. The body of each page.
#>
[CmdletBinding()]
[OutputType([string])]
param(
[Parameter(Mandatory)]
[ValidateScript({ $_.ContainsKey('Uri') })]
[hashtable]$Request
)

$firstUri = [uri]$Request['Uri']
$pageRequest = $Request.Clone()
$pageRequest['UseBasicParsing'] = $true
$pageRequest['ErrorAction'] = 'Stop'
# Invoke-WebRequest follows a redirect without the Authorization header, and the page then
# arrives as an anonymous caller sees it. With this value a redirect is an error instead.
$pageRequest['MaximumRedirection'] = 0
$requestedUris = [System.Collections.Generic.HashSet[string]]::new()
$pageUri = $firstUri
while ($null -ne $pageUri) {
$null = $requestedUris.Add($pageUri.AbsoluteUri)
$pageRequest['Uri'] = $pageUri
try {
$response = Invoke-WebRequest @pageRequest
} catch {
# PowerShell 7 puts the refused reply on the exception. Windows PowerShell 5.1 has no
# reply there and names the error instead.
$status = 0
$reply = $_.Exception.PSObject.Properties['Response']
if ($null -ne $reply -and $null -ne $reply.Value) {
$status = [int]$reply.Value.StatusCode
}
$isRedirect = ($status -in 301, 302, 303, 307, 308 -or
$_.FullyQualifiedErrorId -like 'MaximumRedirectExceeded*')
if (-not $isRedirect) {
$PSCmdlet.ThrowTerminatingError($_)
}

# The address is reported without its query string, which can carry a token.
$target = $pageUri.GetLeftPart([System.UriPartial]::Path)
$message = "The request for '$target' was answered with a redirect. It was not followed."
$exception = [System.InvalidOperationException]::new($message, $_.Exception)
$category = [System.Management.Automation.ErrorCategory]::InvalidResult
$errorRecord = [System.Management.Automation.ErrorRecord]::new(
$exception, 'PageRedirected', $category, $target)
$PSCmdlet.ThrowTerminatingError($errorRecord)
}

# A body whose content type is not a text type, such as application/vnd.api+json, is bytes.
if ($response.Content -is [byte[]]) {
[System.Text.Encoding]::UTF8.GetString($response.Content)
} else {
$response.Content
}

# The header value is a string on Windows PowerShell 5.1 and a list of strings on PowerShell 7.
$linkText = ($response.Headers.GetEnumerator() |
Where-Object -Property Key -EQ -Value 'Link' |
ForEach-Object { $_.Value }) -join ','
$nextUri = $null
foreach ($link in $linkText -split ',\s*(?=<)') {
$match = [regex]::Match($link, '^\s*<([^>]+)>.*\brel="?[^";]*\bnext\b')
if ($match.Success) {
$nextUri = [uri]::new($pageUri, $match.Groups[1].Value)
break
}
}

$errorId = $null
if ($null -ne $nextUri) {
$sameOrigin = ($nextUri.Scheme -eq $firstUri.Scheme -and $nextUri.Host -eq $firstUri.Host -and
$nextUri.Port -eq $firstUri.Port)
if (-not $sameOrigin) {
$errorId = 'NextPageOnAnotherHost'
$category = [System.Management.Automation.ErrorCategory]::SecurityError
$message = "The next page is on another host, '$($nextUri.Host)'. It was not requested."
} elseif ($requestedUris.Contains($nextUri.AbsoluteUri)) {
$errorId = 'NextPageAlreadyRequested'
$category = [System.Management.Automation.ErrorCategory]::InvalidResult
$message = 'The next link names a page that was already requested. It was not requested again.'
}
}

if ($null -ne $errorId) {
$exception = [System.InvalidOperationException]::new($message)
$target = $nextUri.GetLeftPart([System.UriPartial]::Path)
$errorRecord = [System.Management.Automation.ErrorRecord]::new(
$exception, $errorId, $category, $target)
$PSCmdlet.ThrowTerminatingError($errorRecord)
}

$pageUri = $nextUri
}
}
```

Run on PowerShell 7.7.0, PowerShell 7.6.10, and Windows PowerShell 5.1 under strict mode, against the
same server. Three pages arrived with the credential on each, whether the link was absolute or
relative, stood among other relations, or came in a header named `link`. Each of these ended the
function with an error and without a further request: a next link on another host, a next link
back to the first page, and a redirect, at the first page or at a later one. The function reports
the redirect as `PageRedirected` on all three versions, where the errors of the cmdlet differ. A
body with the content type `application/vnd.api+json` arrived as text, where `Invoke-WebRequest`
returns bytes.

**SEC-10.** Arguments passed as an array reach a native executable as separate arguments, so input
cannot add switches or commands:

Expand Down
Loading