From 60e494507f7ab9b9d9159fa8472bb148d0f51830 Mon Sep 17 00:00:00 2001 From: fadwen <110697945+fadwen@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:44:25 +0000 Subject: [PATCH] chore: sync PowerShell standards 2.0.0 --- .../powershell-security-review/SKILL.md | 2 + .../powershell-security-review/SKILL.md | 2 + .../powershell-cicd.instructions.md | 4 + .../powershell-modules.instructions.md | 4 +- .../powershell-pull-requests.instructions.md | 14 +- .../powershell-security.instructions.md | 172 ++++++++++++++++++ .../powershell-version.instructions.md | 84 ++++++++- .../powershell-security-review/SKILL.md | 2 + 8 files changed, 273 insertions(+), 11 deletions(-) diff --git a/.agents/skills/powershell-security-review/SKILL.md b/.agents/skills/powershell-security-review/SKILL.md index 9e79603..4e069ea 100644 --- a/.agents/skills/powershell-security-review/SKILL.md +++ b/.agents/skills/powershell-security-review/SKILL.md @@ -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. diff --git a/.claude/skills/powershell-security-review/SKILL.md b/.claude/skills/powershell-security-review/SKILL.md index 9e79603..4e069ea 100644 --- a/.claude/skills/powershell-security-review/SKILL.md +++ b/.claude/skills/powershell-security-review/SKILL.md @@ -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. diff --git a/.github/instructions/powershell-cicd.instructions.md b/.github/instructions/powershell-cicd.instructions.md index 68720fb..9b949ca 100644 --- a/.github/instructions/powershell-cicd.instructions.md +++ b/.github/instructions/powershell-cicd.instructions.md @@ -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 diff --git a/.github/instructions/powershell-modules.instructions.md b/.github/instructions/powershell-modules.instructions.md index 2d8dc40..1356e91 100644 --- a/.github/instructions/powershell-modules.instructions.md +++ b/.github/instructions/powershell-modules.instructions.md @@ -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: @@ -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: diff --git a/.github/instructions/powershell-pull-requests.instructions.md b/.github/instructions/powershell-pull-requests.instructions.md index 2b9defa..b82b8c0 100644 --- a/.github/instructions/powershell-pull-requests.instructions.md +++ b/.github/instructions/powershell-pull-requests.instructions.md @@ -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. @@ -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 `
` 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. diff --git a/.github/instructions/powershell-security.instructions.md b/.github/instructions/powershell-security.instructions.md index 7e555d9..133fb7a 100644 --- a/.github/instructions/powershell-security.instructions.md +++ b/.github/instructions/powershell-security.instructions.md @@ -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 @@ -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: diff --git a/.github/instructions/powershell-version.instructions.md b/.github/instructions/powershell-version.instructions.md index 81720da..78b4a45 100644 --- a/.github/instructions/powershell-version.instructions.md +++ b/.github/instructions/powershell-version.instructions.md @@ -11,9 +11,10 @@ description: "PowerShell target version, support lifecycle, and version-dependen These rules apply to every `.ps1`, `.psm1`, and `.psd1` file. They say which PowerShell version to write for and which features that version has. -The dates and version numbers on this page were checked against Microsoft's documentation on -2026-11-15. A version is supported until its end-of-support date; compare that date with today's -date instead of relying on the wording here. +The dates and version numbers on this page were checked against Microsoft's documentation, the +PowerShell releases on GitHub, and the .NET release index on 2026-11-17. A version is supported +until its end-of-support date; compare that date with today's date instead of relying on the +wording here. ## Rules @@ -49,11 +50,17 @@ date instead of relying on the wording here. | Version | Type | Released | End of support | Runtime | | --- | --- | --- | --- | --- | +| 7.7 | Stable | 10-Nov-2026 | 14-Nov-2028 | .NET 11 | | 7.6 | LTS | 18-Mar-2026 | 14-Nov-2028 | .NET 10 | | 7.5 | Stable | 23-Jan-2025 | 10-Nov-2026 | .NET 9 | | 7.4 | LTS | 16-Nov-2023 | 10-Nov-2026 | .NET 8 | | 5.1 | Windows component | Aug-2016 | Follows the Windows lifecycle | .NET Framework 4.x | +PowerShell 7.7 is a Stable release, so the default target stays 7.6, the LTS release (VER-01). Both +end support on the same day. Microsoft's lifecycle page did not yet list 7.7 on 2026-11-17: its +release date here is that of the release on GitHub, and its end of support is the date that the +.NET release index gives for .NET 11, which the lifecycle of PowerShell follows. + Versions 6.x and 7.0 to 7.3 ended support earlier. Windows PowerShell 5.1 ships with Windows and is still supported, but it receives no new features: treat it as a compatibility target, never as the version to design for. @@ -67,6 +74,7 @@ moving to the current LTS. Do not silently change the project's declared target. | --- | --- | --- | | New automation, CI, containers | 7.6 | `PowerShellVersion = '7.6'`, `CompatiblePSEditions = @('Core')` | | Module for machines that may not have PowerShell 7 | 5.1 | `PowerShellVersion = '5.1'`, `CompatiblePSEditions = @('Desktop', 'Core')` | +| Code that needs a feature added in 7.7 | 7.7 | `PowerShellVersion = '7.7'`, `CompatiblePSEditions = @('Core')` | ```powershell #requires -Version 7.6 @@ -76,6 +84,11 @@ When the project declares no target and it is not clear which row applies, ask b code. If the question cannot be asked, VER-01 applies: write for 7.6 and say that the target was assumed. +PowerShell 7.7 is opt-in. Use a feature that 7.7 added only when the project declares 7.7, with +`#requires -Version 7.7` or `PowerShellVersion = '7.7'`; without that declaration the target is 7.6 +(VER-01, VER-04). Code written for 7.6 is also run on 7.7 by anyone who has installed it, so check +it against the behaviour that 7.7 changed, which is listed below. + `#requires -Version 7.0` is obsolete, because that version is retired. To say "any PowerShell 7", name the lowest supported version: 7.6 since 10-Nov-2026, when 7.4 and 7.5 left support. @@ -132,6 +145,23 @@ so one helper can take every command of the module with it. | Redirection to a variable | `Get-Item -LiteralPath $path 2>&1 > variable:itemResult` | | `PipelineStopToken` on `Cmdlet` | For binary cmdlets: a `CancellationToken` that is signalled when the pipeline stops | +### Added in PowerShell 7.7 + +Code that targets 7.6 MUST NOT use these (VER-04). Each was run on PowerShell 7.7.0 and is absent +from PowerShell 7.6.10 and Windows PowerShell 5.1. A comparison of every command and parameter that +7.6.10 and 7.7.0 ship found nothing else added outside PSResourceGet, and nothing removed. + +| Feature | Use on 7.6 | +| --- | --- | +| `New-TemporaryDirectory` | `[System.IO.Directory]::CreateTempSubdirectory()`. On 5.1, `New-Item -ItemType Directory` with a path made from `[System.IO.Path]::GetTempPath()` and `[System.IO.Path]::GetRandomFileName()`. | +| `Join-Path -Extension` | `[System.IO.Path]::ChangeExtension()` on the joined path. With an empty extension it leaves the dot, as in `file.`, where `-Extension ''` removes the dot too. | +| `-ExcludeProperty` on `Format-Table`, `Format-List`, `Format-Wide`, and `Format-Custom` | `Select-Object -Property * -ExcludeProperty ` before the formatting command | +| `[WildcardPattern]::ToRegex()` | Match with the pattern's own `IsMatch()` method | +| `$PSApplicationOutputEncoding`, the encoding used to read the output of a native executable | Set `[Console]::OutputEncoding`, and restore it in `finally` | + +Assigning `$PSApplicationOutputEncoding` on 7.6 raises no error and changes nothing: it creates an +ordinary variable, and the output is still read with `[Console]::OutputEncoding`. + ### Promoted from experimental These features are always on from the version shown. Do not tell users to enable them with @@ -144,12 +174,29 @@ These features are always on from the version shown. Do not tell users to enable `PSRedirectToVariable` is the redirection to a variable in the table above. +PowerShell 7.7 promotes no feature. `PSLoadAssemblyFromNativeCode`, +`PSSerializeJSONLongEnumAsNumber`, and `PSProfileDSCResource` are still experimental in it. + ### Behaviour that changed Code MUST NOT depend on the older behaviour. +Each row for 7.7 was measured on PowerShell 7.7.0, and the older behaviour on PowerShell 7.6.10 and +Windows PowerShell 5.1. The rows for 7.6.5, 7.6.7, and 7.6.10 are servicing releases of 7.6: they +were measured on 7.6.10, and 7.7.0 behaves the same way. + | Version | Change | | --- | --- | +| 7.7 | `New-Guid` returns a version 7 UUID, which begins with the time it was created. Earlier versions return a random version 4 UUID. Where the kind matters, call `[guid]::NewGuid()` for version 4, or `[guid]::CreateVersion7()` for version 7, which Windows PowerShell 5.1 does not have. A GUID identifies something; it is not a secret, and from 7.7 part of it can be worked out from the time. | +| 7.7 | `-NoTypeInformation` on `Export-Csv` and `ConvertTo-Csv` is obsolete: it has no effect, and it writes a warning each time it is passed. Windows PowerShell 5.1 still writes a `#TYPE` line without it. See the note on CSV type information below. | +| 7.7 | `Export-Csv -Append -NoHeader` is a terminating error. On 7.6 the pair is accepted and writes the rows without a header. | +| 7.7 | `Format-Table`, `Format-List`, and `Format-Custom` reject `-Property $null` and an empty array. Earlier versions accept `$null` and show every property. Add the parameter to a splat only when it has a value. | +| 7.7 | `Get-ChildItem -Path '*.md' -Recurse -Name` also returns the matches in subfolders. On 7.6 and 5.1 it returns only those in the starting folder, while `-Filter '*.md'` recurses on every version (STY-43). | +| 7.7 | `Resolve-Path -Relative` writes `.\.config\app.json` for a name that starts with a dot. On 7.6 and 5.1 it writes `.config\app.json`. | +| 7.7 | `Get-Help` prints the `.NOTES` text one blank line below its heading and indented by four spaces, like the other sections. On 7.6 and 5.1 there are two blank lines and eight spaces, so a test that compares help text exactly gets a different result. | +| 7.6.10 | `New-FileCatalog -CatalogVersion 1`, and `Test-FileCatalog` on a version 1 catalog, write a warning, because version 1 uses SHA-1. Windows PowerShell 5.1 (build 26100) writes one too. | +| 7.6.7 | `Test-Json` fetches a schema that another schema refers to by URL only when `-FetchExternalReference` is passed. Without it the reference is an error, `UnresolvedJsonSchemaRef`, and the result is `$false` for valid input as well. | +| 7.6.5 | `Invoke-RestMethod` and `Invoke-WebRequest` send the `Authorization` header with the first request only. A link followed by `-FollowRelLink` is requested without it, as the target of a redirect is, unless `-PreserveAuthorizationOnRedirect` is passed. A function that sends a credential follows the links itself (SEC-09). | | 7.6 | The `ThreadJob` module is now `Microsoft.PowerShell.ThreadJob`. Call `Start-ThreadJob` without a module prefix; `ThreadJob\Start-ThreadJob` and a `RequiredModules` entry for `ThreadJob` no longer resolve. Where a prefix or an entry is needed, write `Microsoft.PowerShell.ThreadJob\Start-ThreadJob` and `@{ ModuleName = 'Microsoft.PowerShell.ThreadJob'; ModuleVersion = '2.2.0' }`. | | 7.6 | `Join-Path -ChildPath` accepts an array. An array that used to be joined into one segment is now treated as several segments. | | 7.6 | `[WildcardPattern]::Escape()` escapes a lone backtick correctly. Code that escaped twice to work around the old result now escapes too much. | @@ -159,6 +206,25 @@ Code MUST NOT depend on the older behaviour. | 7.5 | `Select-String` returns `LineNumber` as `[ulong]`. | | 7.4 | `Test-Json` accepts only strictly valid JSON and no longer supports Draft 4 schemas. | +**CSV type information.** On 7.7.0 each call that passes the switch writes +`Parameter 'NoTypeInformation' is obsolete`, followed by the reason. Code that also runs on Windows +PowerShell 5.1 passes the switch only there: + +```powershell +$exportParameters = @{ + LiteralPath = $csvPath + Encoding = 'utf8' +} +if ($PSVersionTable.PSVersion -lt [version]'6.0') { + # Windows PowerShell 5.1 writes a #TYPE line unless this switch is passed. + $exportParameters['NoTypeInformation'] = $true +} +$rows | Export-Csv @exportParameters +``` + +Run on PowerShell 7.7.0, PowerShell 7.6.10, and Windows PowerShell 5.1: no warning, and the file +starts with the header line on all three. + ### Windows PowerShell commands that are not part of PowerShell 7 (VER-06) | Do not use | Use instead | @@ -219,9 +285,9 @@ function Invoke-ModuleWebRequest { try { if ($script:canSkipHttpErrorCheck) { - $response = Invoke-WebRequest @Request -SkipHttpErrorCheck -ErrorAction Stop + $response = Invoke-WebRequest @Request -SkipHttpErrorCheck -MaximumRedirection 0 -ErrorAction Stop } else { - $response = Invoke-WebRequest @Request -UseBasicParsing -ErrorAction Stop + $response = Invoke-WebRequest @Request -UseBasicParsing -MaximumRedirection 0 -ErrorAction Stop } $status = [int]$response.StatusCode $body = $response.Content @@ -266,6 +332,9 @@ The message names the status and the request URI. The URI is written without its which can carry a token, and the body goes into the exception's `Data`, not into the message, because a reply can carry personal data (SEC-06). +Both calls pass `-MaximumRedirection 0`, which SEC-09 requires of a request that carries a +credential. A redirect then ends the function with the error of the cmdlet, on both versions. + ## Detecting the version and operating system (VER-07, VER-10) ```powershell @@ -335,6 +404,9 @@ publisher, as it ships Pester 3.4.0. | PSScriptAnalyzer | 1.25.0 | | | Pester | 6.2.0 | See `.github/instructions/powershell-pester.instructions.md` | | Microsoft.PowerShell.PlatyPS | 1.0.3 | See `.github/instructions/powershell-platyps.instructions.md` | -| Microsoft.PowerShell.PSResourceGet | 1.2.0 | Included with PowerShell 7.6 | +| Microsoft.PowerShell.PSResourceGet | 1.2.0 | Included with PowerShell 7.6. PowerShell 7.6.10 includes 1.2.1, and 7.7.0 includes 1.3.1. | | Microsoft.PowerShell.ThreadJob | 2.2.0 | Included with PowerShell 7.6 | | PSReadLine | 2.4.5 | Included with PowerShell 7.6 | + +PSScriptAnalyzer 1.25.0 and Pester 6.2.0 run on PowerShell 7.7.0 as well: the quality gate of the +standards repository passes under it. diff --git a/.github/skills/powershell-security-review/SKILL.md b/.github/skills/powershell-security-review/SKILL.md index 9e79603..4e069ea 100644 --- a/.github/skills/powershell-security-review/SKILL.md +++ b/.github/skills/powershell-security-review/SKILL.md @@ -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.