Merge pull request #895 from rdimitrov/add-rule-type-guidance

chore: add guidance notes for rule_types

examples/github/rule-types/actions_check_pinned_tags.yaml

@@ -14,6 +14,7 @@ guidance: |
   would need to generate a SHA-1 collision for a valid Git object payload.
   When selecting a SHA, you should verify it is from the action's repository
   and not a repository fork.
+
   For more information, see
   https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions
 def:

examples/github/rule-types/allowed_selected_actions.yaml

@@ -9,6 +9,11 @@ description: |
   Verifies the settings for selected actions and reusable workflows that are allowed
   in a repository. To use this rule, the repository policy for allowed_actions must
   be configured to selected.
+guidance: |
+  Having an overview over which actions and reusable workflows are allowed in a repository is important and allows for a better overall security posture.
+
+  For more information, see
+  https://docs.github.com/en/rest/actions/permissions#set-allowed-actions-and-reusable-workflows-for-a-repository
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/artifact_signature.yaml

@@ -6,6 +6,13 @@ context:
   provider: github
   group: Root Group
 description: Verifies that a given artifact has a valid signature.
+guidance: |
+  Artifact signing allows a user to add a digital fingerprint to an artifact and verify its trust later.
+  It allows the artifact user to verify the source and trust the container image.
+  Mediator leverages sigstore(cosign) to verify an artifact has been signed.
+
+  For more information, see
+  https://docs.sigstore.dev/signing/signing_with_containers
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/branch_protection.yaml

@@ -6,6 +6,13 @@ context:
   provider: github
   group: Root Group
 description: Verifies that a branch has proper protections.
+guidance: |
+  You can protect important branches by setting branch protection rules, which define whether
+  collaborators can delete or force push to the branch and set requirements for any pushes to the branch,
+  such as passing status checks or a linear commit history.
+
+  For more information, see
+  https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/codeql_enabled.yaml

@@ -12,7 +12,10 @@ guidance: |
   to ensure that vulnerabilities are not introduced into the codebase.
 
   To enable CodeQL, add a GitHub workflow to the repository that runs the
-  CodeQL analysis. For more information, see the [CodeQL documentation](https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#configuring-code-scanning-for-a-private-repository).
+  CodeQL analysis.
+
+  For more information, see
+  https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#configuring-code-scanning-for-a-private-repository
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/default_workflow_permissions.yaml

@@ -9,6 +9,11 @@ description: |
   Verifies the default workflow permissions granted to the GITHUB_TOKEN
   when running workflows in a repository, as well as if GitHub Actions
   can submit approving pull request reviews.
+guidance: |
+  Having control over the default workflow permissions for a repositry is important and allows for a better security posture.
+
+  For more information, see
+  https://docs.github.com/en/rest/actions/permissions#set-default-workflow-permissions-for-a-repository
 def:
   in_entity: repository
   rule_schema:

examples/github/rule-types/dependabot_enabled.yaml

@@ -10,7 +10,9 @@ guidance: |
   Dependabot enables Automated dependency updates for repositories.
   It is recommended that repositories have some form of automated dependency updates enabled
   to ensure that vulnerabilities are not introduced into the codebase.
-  To configure Dependabot, follow the instructions at https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+  For more information, see
+  https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/github_actions_allowed.yaml

@@ -16,7 +16,8 @@ description: |
 guidance: |
   Configure your repository to match the organization's policy for allowed actions.
 
-  For more information see the [GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository).
+  For more information, see
+  https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/repo_workflow_access_level.yaml

@@ -8,6 +8,11 @@ context:
 description: |
   Verifies the level of access that workflows outside of the repository have
   to actions and reusable workflows in the repository. This only applies to private repositories.
+guidance: |
+  Actions and reusable workflows in your private repositories can be shared with other private repositories owned by the same user or organization.
+
+  For information about private repositories, see
+  https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/secret_push_protection.yaml

@@ -6,6 +6,11 @@ context:
   provider: github
   group: Root Group
 description: Verfies that secret push protection is enabled for a given repository.
+guidance: |
+  You can use secret scanning to prevent supported secrets from being pushed into your repository by enabling secret scanning push protection.
+
+  For more information on how to configure this, see
+  https://docs.github.com/en/code-security/secret-scanning/push-protection-for-repositories-and-organizations#enabling-secret-scanning-as-a-push-protection-for-a-repository
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

examples/github/rule-types/secret_scanning.yaml

@@ -8,11 +8,11 @@ context:
 description: Verifies that secret scanning is enabled for a given repository.
 guidance: |
   Secret scanning is a feature that scans repositories for secrets and alerts
-  the repository owner when a secret is found. To enable this feature in github,
-  you must enable it in the repository settings. See the GitHub documentation
-  for more information. [1]
+  the repository owner when a secret is found. To enable this feature in GitHub,
+  you must enable it in the repository settings.
 
-  [1] https://docs.github.com/en/github/administering-a-repository/about-secret-scanning
+  For more information, see
+  https://docs.github.com/en/github/administering-a-repository/about-secret-scanning
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts