From 72dd4116824707bf26dabcf7511d896c3e13c530 Mon Sep 17 00:00:00 2001
From: Michael Lombardi <mlombardi@microsoft.com>
Date: Thu, 11 Aug 2022 12:49:22 -0500
Subject: [PATCH] (GH-90) Document PSAvoidUsingBrokenHashAlgorithms

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 0000000..83b7592
--- /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 ee86175..528d5ad 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         | Yes<sup>2</sup> |
 | [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 a3c26b6..f6aee6e 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