From 13f0ba09ae3f7995579fbd64827c6988554fa86d Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Wed, 10 Aug 2022 12:06:53 -0500 Subject: [PATCH 1/5] (AB-4960) Run expectations workflow every 30m (#89) This change reduces the frequency the expectations GHA runs from once every 10 minutes to once every 30 minutes to help reduce the frequency of rate limiting. --- .github/workflows/expectations.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/expectations.yml b/.github/workflows/expectations.yml index 750e0673..4bf6ac83 100644 --- a/.github/workflows/expectations.yml +++ b/.github/workflows/expectations.yml @@ -5,7 +5,7 @@ name: Commenting on: schedule: - - cron: 0/10 * * * * + - cron: 0/30 * * * * permissions: contents: read pull-requests: write From 03065d1c38d7e1e82b577d2fe2c266b7b993aa54 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Thu, 11 Aug 2022 12:57:44 -0500 Subject: [PATCH 2/5] (GH-90) Document PSAvoidUsingBrokenHashAlgorithms (#91) This change: - documents the new `PSAvoidUsingBrokenHashAlgorithms` rule for **PSScriptAnalyzer** by updating the rule table and adding a document for the rule. - Resolves #90 - Fixes AB#4996 --- .../Rules/AvoidUsingBrokenHashAlgorithms.md | 48 +++++++++++++++++++ .../PSScriptAnalyzer/Rules/README.md | 1 + reference/docs-conceptual/toc.yml | 2 + 3 files changed, 51 insertions(+) create mode 100644 reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md new file mode 100644 index 00000000..83b75929 --- /dev/null +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md @@ -0,0 +1,48 @@ +--- +description: Avoid using broken hash algorithms +ms.custom: PSSA v1.21.0 +ms.date: 05/31/2022 +ms.topic: reference +title: AvoidUsingBrokenHashAlgorithms +--- +# AvoidUsingBrokenHashAlgorithms + +**Severity Level: Warning** + +## Description + +Avoid using the broken algorithms MD5 or SHA-1. + +## How + +Replace broken algorithms with secure alternatives. MD5 and SHA-1 should be replaced with SHA256, +SHA384, SHA512, or other safer algorithms when possible, with MD5 and SHA-1 only being utilized by +necessity for backwards compatibility. + +## Example 1 + +### Wrong + +```powershell +Get-FileHash foo.txt -Algorithm MD5 +``` + +### Correct + +```powershell +Get-FileHash foo.txt -Algorithm SHA256 +``` + +## Example 2 + +### Wrong + +```powershell +Get-FileHash foo.txt -Algorithm SHA1 +``` + +### Correct + +```powershell +Get-FileHash foo.txt +``` diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/README.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/README.md index ee86175d..528d5ad5 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/README.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/README.md @@ -26,6 +26,7 @@ The PSScriptAnalyzer contains the following rule definitions. | [AvoidSemicolonsAsLineTerminators](./AvoidSemicolonsAsLineTerminators.md) | Warning | No | | | [AvoidShouldContinueWithoutForce](./AvoidShouldContinueWithoutForce.md) | Warning | Yes | | | [AvoidTrailingWhitespace](./AvoidTrailingWhitespace.md) | Warning | Yes | | +| [AvoidUsingBrokenHashAlgorithms](./AvoidUsingBrokenHashAlgorithms.md) | Warning | Yes | | | [AvoidUsingCmdletAliases](./AvoidUsingCmdletAliases.md) | Warning | Yes | Yes2 | | [AvoidUsingComputerNameHardcoded](./AvoidUsingComputerNameHardcoded.md) | Error | Yes | | | [AvoidUsingConvertToSecureStringWithPlainText](./AvoidUsingConvertToSecureStringWithPlainText.md) | Error | Yes | | diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index a3c26b67..f6aee6eb 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -71,6 +71,8 @@ items: href: PSScriptAnalyzer/Rules/AvoidShouldContinueWithoutForce.md - name: AvoidTrailingWhitespace href: PSScriptAnalyzer/Rules/AvoidTrailingWhitespace.md + - name: AvoidUsingBrokenHashAlgorithms + href: PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md - name: AvoidUsingCmdletAliases href: PSScriptAnalyzer/Rules/AvoidUsingCmdletAliases.md - name: AvoidUsingComputerNameHardcoded From e74c14ad0c0365db51ff134d182718f5d0db90e3 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Thu, 18 Aug 2022 08:30:41 -0500 Subject: [PATCH 3/5] (AB-4196) Codify markdownlint (#92) Prior to this change, the repository had no markdownlint configuration. This change adds configuration based on the rules defined in the MicrosoftDocs/PowerShell-Docs project. The root-folder `.markdownlint.json` file specifies the enforced syntax for Markdown files in this project. The root-folder `.markdownlint-cli2.yaml` file governs the behavior of the linter overall. The settings included are minimal and do not effect the editing experience. This file may require iteration for advanced usage later. In every `About` folder for reference content, this change adds a `.markdownlint.json` file. When editing Markdown in VS Code, the editor uses the closest configuration file to the edited document. That allows us to override and specify alternate rules on a per-folder basis. In this change, the configuration files in the `About` folders: - Extend the root configuration. Any settings not specified in these configurations is inherited from the configuration at the project root. - Overrides the `line-length` rule, setting the maximum line length for code blocks to 74 characters and for other text to 79 characters.This is to accomodate the PowerShell Help System's line length requirements. In the `rules` folder for PSScriptAnalyzer's conceptual content, this change adds a `.markdownlint.json` file which ignores the markdownlint rule `no-emphasis-as-heading`. PSSA rules indicate their severity level by a single line of emphasized text. This change is related to AB#4196 and AB#4197. --- .markdownlint-cli2.yaml | 33 +++++ .markdownlint.json | 132 ++++++++++++++++++ .../PSScriptAnalyzer/Rules/.markdownlint.json | 4 + .../About/.markdownlint.json | 12 ++ .../PlatyPS/About/.markdownlint.json | 12 ++ 5 files changed, 193 insertions(+) create mode 100644 .markdownlint-cli2.yaml create mode 100644 .markdownlint.json create mode 100644 reference/docs-conceptual/PSScriptAnalyzer/Rules/.markdownlint.json create mode 100644 reference/ps-modules/Microsoft.PowerShell.Crescendo/About/.markdownlint.json create mode 100644 reference/ps-modules/PlatyPS/About/.markdownlint.json diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 00000000..e3b4e065 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,33 @@ +# Rule definitions live in .markdownlint.json + +# Include a custom rule package +# customRules: +# - markdownlint-rule-titlecase + +# Fix any fixable errors +fix: true + +# Define a custom front matter pattern +# frontMatter: (^---\s*$[^]*?^---\s*$)(\r\n|\r|\n|$) + +# Define glob expressions to use (only valid at root) +# globs: +# - "!*bout.md" + +# Define glob expressions to ignore +ignores: + - breadcrumb + +# Use a plugin to recognize math +# markdownItPlugins: +# - - "@iktakahiro/markdown-it-katex" + +# Disable inline config comments +noInlineConfig: false + +# Disable progress on stdout (only valid at root) +noProgress: true + +# Use a specific formatter (only valid at root) +# outputFormatters: +# - [markdownlint-cli2-formatter-default] diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 00000000..cc5c8d2b --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,132 @@ +{ + "blanks-around-fences": true, + "blanks-around-headers": true, + "blanks-around-lists": true, + "code-block-style": { + "style": "fenced" + }, + "code-fence-style": { + "style": "backtick" + }, + "commands-show-output": true, + "docsmd.alert": true, + "docsmd.codesnippet": true, + "docsmd.column": true, + "docsmd.image": true, + "docsmd.moniker": true, + "docsmd.no-loc": true, + "docsmd.row": true, + "docsmd.securelinks": true, + "docsmd.syntax": true, + "docsmd.video": true, + "docsmd.xref": true, + "docsmd.zone": true, + "emphasis-style": { + "style": "underscore" + }, + "fenced-code-language": false, + "first-line-h1": { + "front_matter_title": "" + }, + "header-increment": true, + "header-start-left": true, + "header-style": { + "style": "atx" + }, + "hr-style": { + "style": "---" + }, + "line-length": { + "code_block_line_length": 90, + "code_blocks": true, + "heading_line_length": 100, + "headings": true, + "line_length": 100, + "stern": true, + "tables": false + }, + "list-indent": true, + "list-marker-space": true, + "no-alt-text": true, + "no-bare-urls": true, + "no-blanks-blockquote": true, + "no-duplicate-header": { + "siblings_only": true + }, + "no-emphasis-as-header": true, + "no-empty-links": true, + "no-hard-tabs": true, + "no-inline-html": { + "allowed_elements": [ + "a", + "br", + "code", + "kbd", + "li", + "properties", + "sup", + "tags", + "ul" + ] + }, + "no-missing-space-atx": true, + "no-missing-space-closed-atx": true, + "no-multiple-blanks": true, + "no-multiple-space-atx": true, + "no-multiple-space-blockquote": true, + "no-multiple-space-closed-atx": true, + "no-reversed-links": true, + "no-space-in-code": true, + "no-space-in-emphasis": true, + "no-space-in-links": true, + "no-trailing-punctuation": { + "punctuation": ".,;:!。，；：！？" + }, + "no-trailing-spaces": { + "br_spaces": 2, + "strict": true + }, + "ol-prefix": { + "style": "one" + }, + "proper-names": { + "code_blocks": false, + "names": [ + "PowerShell", + "IntelliSense", + "Authenticode", + "CentOS", + "Contoso", + "CoreOS", + "Debian", + "Ubuntu", + "openSUSE", + "RHEL", + "JavaScript", + ".NET", + "NuGet", + "VS Code", + "Newtonsoft" + ] + }, + "required-headers": false, + "single-h1": { + "front_matter_title": "", + "level": 1 + }, + "single-trailing-newline": true, + "strong-style": { + "style": "asterisk" + }, + "ul-indent": { + "indent": 2, + "start_indented": false + }, + "ul-start-left": true, + "ul-style": { + "style": "dash" + }, + "link-fragments": true, + "reference-links-images": true, + "link-image-reference-definitions": true +} diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/.markdownlint.json b/reference/docs-conceptual/PSScriptAnalyzer/Rules/.markdownlint.json new file mode 100644 index 00000000..39a15cdd --- /dev/null +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/.markdownlint.json @@ -0,0 +1,4 @@ +{ + "extends": "../../../../.markdownlint.json", + "no-emphasis-as-heading": false +} diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/.markdownlint.json b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/.markdownlint.json new file mode 100644 index 00000000..a7af527a --- /dev/null +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/.markdownlint.json @@ -0,0 +1,12 @@ +{ + "extends": "../../../../.markdownlint.json", + "line-length": { + "code_block_line_length": 74, + "code_blocks": true, + "heading_line_length": 79, + "headings": true, + "line_length": 79, + "stern": true, + "tables": false + } +} diff --git a/reference/ps-modules/PlatyPS/About/.markdownlint.json b/reference/ps-modules/PlatyPS/About/.markdownlint.json new file mode 100644 index 00000000..a7af527a --- /dev/null +++ b/reference/ps-modules/PlatyPS/About/.markdownlint.json @@ -0,0 +1,12 @@ +{ + "extends": "../../../../.markdownlint.json", + "line-length": { + "code_block_line_length": 74, + "code_blocks": true, + "heading_line_length": 79, + "headings": true, + "line_length": 79, + "stern": true, + "tables": false + } +} From 27ecb4ad46b5afe92ea75df4653d24a4b66f3efd Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 18 Aug 2022 15:40:10 -0500 Subject: [PATCH 4/5] Add CrescendoBuilt to docs (#93) --- .../About/about_Crescendo.md | 76 ++++++++++--------- .../Export-CrescendoModule.md | 16 ++-- 2 files changed, 51 insertions(+), 41 deletions(-) diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md index 9e060f7f..47dd4f72 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md @@ -1,7 +1,7 @@ --- description: Describes the purpose of the Crescendo module. Locale: en-US -ms.date: 01/21/2022 +ms.date: 08/18/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.crescendo/about/about_Microsoft.PowerShell.Crescendo?view=ps-modules.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Microsoft.PowerShell.Crescendo @@ -10,26 +10,26 @@ title: about_Microsoft.PowerShell.Crescendo ## about_Microsoft.PowerShell.Crescendo -## SHORT DESCRIPTION +## Short description The PowerShell Crescendo module provides a novel way to create proxy functions for native commands via `JSON` configuration files. -## LONG DESCRIPTION +## Long description PowerShell is capable of invoking native applications like any shell. However, it would improve the experience if the native command could participate in the PowerShell pipeline and take advantage of the parameter behaviors that are part of PowerShell. -The PowerShell Crescendo module provides a way to more easily take advantage of -the PowerShell pipeline by invoking the native executable, facilitating -parameter handling, and converting text output into objects. +The PowerShell Crescendo module provides a way to take advantage of the +PowerShell pipeline by invoking the native executable, facilitating parameter +handling, and converting text output into objects. ## JSON Configuration The PowerShell Crescendo module provides a way to create a small bit of JSON -that is used to create a function that calls the native command. +that's used to create a function that calls the native command. An annotated schema is provided as part of the module that can improve the authoring process. @@ -41,9 +41,9 @@ commands in the same way you do with cmdlets. ## Output Handling -It is also possible to provide a script block that can be used to convert the -output from the native command into objects. If the native command emits `json` -or `xml` it is as simple as: +It's also possible to create a script block that can be used to convert the +output from the native command into objects. If the native command emits JSON +or XML it can be as simple as: ```json "OutputHandler": [ @@ -54,12 +54,12 @@ or `xml` it is as simple as: However, script blocks of arbitrary complexity may also be used. -## EXAMPLES +## Examples -A number of samples are provided as part of the module, you can see these in -the Samples directory in the module base directory. +Several samples are provided as part of the module. You can find these in the +`Samples` directory of the module base directory. -A very simple example is as follows to wrap the unix `/bin/ls` command: +The following JSON is a minimal example that wraps the unix `/bin/ls` command: ```json { @@ -68,32 +68,42 @@ A very simple example is as follows to wrap the unix `/bin/ls` command: "Noun":"FileList", "OriginalName": "/bin/ls", "Parameters": [ - {"Name": "Path","OriginalName": "", "OriginalPosition": 1, "Position": 0, "DefaultValue": "." }, - {"Name": "Detail","OriginalName": "-l","ParameterType": "switch"} + { + "Name": "Path", + "OriginalName": "", + "OriginalPosition": 1, + "Position": 0, + "DefaultValue": "." + }, + { + "Name": "Detail", + "OriginalName": "-l", + "ParameterType": "switch" + } ] } ``` The name of the proxy function is `Get-FileList` and has two parameters: -- Path +- **Path** - Which is Position 0, and has a default value of "." -- Detail +- **Detail** - Which is a switch parameter and adds `-l` to the native command parameters A couple of things to note about the Path parameter - The `OriginalPosition` is set to 1 and the `OriginalName` is set to an empty - string. This is because some native commands have a parameter which is _not_ - named and must be the last parameter when executed. All parameters will be - ordered by the value of `OriginalPosition` (the default is 0) and when the - native command is called, those parameters (and their values) will be put in - that order. + string. This is because some native commands have a parameter that is _not_ + named and must be the last parameter when executed. All parameters get + ordered by the value of `OriginalPosition` (the default is 0). When the + native command is called, those parameters (and their values) are put in that + order. In this example, there is no output handler defined, so the text output of the -command will be returned to the pipeline. +command is returned to the pipeline. -A more complicated example which wraps the linux `apt` command follows: +The following is a more complicated example that wraps the linux `apt` command: ```json { @@ -117,7 +127,7 @@ A more complicated example which wraps the linux `apt` command follows: In this case, the output handler converts the text output to a `pscustomobject` to enable using other PowerShell cmdlets. When run, this provides an object -which encapsulates the `apt` output +that encapsulates the `apt` output ```powershell PS> get-installedpackage | ?{ $_.name -match "libc"} @@ -138,16 +148,10 @@ Count Name Group 82 amd64 {@{Name=apt; Version=2.0.2ubuntu0.1; Architecture=amd64; State=System.String[]}, @{Name=base-files… ``` -## TROUBLESHOOTING NOTE - -The PowerShell Crescendo module is still very early in the development process, -so we expect changes to be made. - -One issue is that the output handler is currently a string, so constructing the -script block may be complex; semi-colons will be required to separate -statements. This may be addressed in a later version. +## See also -## SEE ALSO +The PowerShell Crescendo module is still in the development process, so we +expect changes to be made. The GitHub repository may be found at: [https://github.com/PowerShell/Crescendo](https://github.com/PowerShell/Crescendo). @@ -158,6 +162,6 @@ command wrapping can be found here: - [Part 1](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach/) - [Part 2](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2)) -## KEYWORDS +## Keywords Native Command diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md index 416bb7b8..997fd721 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md @@ -43,7 +43,7 @@ Export-CrescendoModule netsh netsh*.json -force ### -ConfigurationFile -This is a list of JSON files which represent the proxies for the module +This is a list of JSON files that represent the proxies for the module. ```yaml Type: System.String[] @@ -59,9 +59,8 @@ Accept wildcard characters: True ### -Force -By default, if `Export-CrescendoModule` finds an already created module, it will not overwrite the -existing file. Use the **Force** parameter to overwrite the existing file, or remove it prior to -running `Export-CrescendoModule`. +By default, if `Export-CrescendoModule` does not overwrite an existing module. Use the **Force** +parameter to overwrite the existing file, or remove it before running `Export-CrescendoModule`. ```yaml Type: System.Management.Automation.SwitchParameter @@ -109,7 +108,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -144,6 +143,13 @@ individual function. Finally, all proxies are used to create an `Export-ModuleMe invocation, so when the resultant module is imported, the module has all the command proxies available. +`Export-CrescendoModule` adds the **CrescendoBuilt** tag to the module manifest. You can use this +tag to find modules in the PowerShell Gallery that were created using Crescendo. For more +information, see: + +- [Gallery Search Syntax](/powershell/scripting/gallery/how-to/finding-packages/search-syntax) +- [Find-Module](/powershell/module/powershellget/find-module) + ## RELATED LINKS [Import-CommandConfiguration](Import-CommandConfiguration.md) From 9bcddad2758cf75070328bbab0a99291daa4c1ca Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 18 Aug 2022 18:31:14 -0500 Subject: [PATCH 5/5] Fix typos (#95) --- .../About/about_Crescendo.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md index 47dd4f72..30711b3e 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md @@ -130,7 +130,7 @@ to enable using other PowerShell cmdlets. When run, this provides an object that encapsulates the `apt` output ```powershell -PS> get-installedpackage | ?{ $_.name -match "libc"} +PS> Get-InstalledPackage | Where-Object { $_.name -match "libc"} Name Version Architecture State ---- ------- ------------ ----- @@ -140,7 +140,7 @@ libcap-ng0 0.7.9-2.1build1 amd64 {installed, local} libcom-err2 1.45.5-2ubuntu1 amd64 {installed, local} libcrypt1 1:4.4.10-10ubuntu4 amd64 {installed, local} -PS> get-installedpackage | Group-Object Architecture +PS> Get-InstalledPackage | Group-Object Architecture Count Name Group ----- ---- ----- @@ -159,8 +159,10 @@ The GitHub repository may be found at: PowerShell Blog posts that present the rational and approaches for native command wrapping can be found here: +**Native commands in PowerShell a new approach** + - [Part 1](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach/) -- [Part 2](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2)) +- [Part 2](https://devblogs.microsoft.com/powershell/native-commands-in-powershell-a-new-approach-part-2) ## Keywords