(GH-90) Document PSAvoidUsingBrokenHashAlgorithms

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
+```

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         | Yes<sup>2</sup> |
 | [AvoidUsingComputerNameHardcoded](./AvoidUsingComputerNameHardcoded.md)                           | Error       |        Yes         |                 |
 | [AvoidUsingConvertToSecureStringWithPlainText](./AvoidUsingConvertToSecureStringWithPlainText.md) | Error       |        Yes         |                 |

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