Add secret scanning to SCM guide, fixes #488

docs/SCM-BestPractices/README.md

@@ -126,6 +126,7 @@ For recommendations only applicable to GitHub or GitLab visit one of the followi
 * Repository Should Not Allow Committer Approvals [<img src="https://user-images.githubusercontent.com/287526/230376963-ae9b8a47-4a74-4746-bc83-5b34cc520d40.svg" alt="GitLab" height="20" width="20">](gitlab/project/repository_allows_committer_approvals_policy.md) [GitLab](gitlab/project/repository_allows_committer_approvals_policy.md)
 * Webhook Configured Without SSL Verification [<img src="https://user-images.githubusercontent.com/287526/230376963-ae9b8a47-4a74-4746-bc83-5b34cc520d40.svg" alt="GitLab" height="20" width="20">](gitlab/project/project_webhook_doesnt_require_ssl.md) [GitLab](gitlab/project/project_webhook_doesnt_require_ssl.md)
 * Project Should Have Fewer Than Three Owners [<img src="https://user-images.githubusercontent.com/287526/230376963-ae9b8a47-4a74-4746-bc83-5b34cc520d40.svg" alt="GitLab" height="20" width="20">](gitlab/project/project_has_too_many_admins.md) [GitLab](gitlab/project/project_has_too_many_admins.md)
+* Secret Scanning Should be Enabled [<img src="https://user-images.githubusercontent.com/287526/230375178-2f1f8844-5609-4ef3-b9ac-141c20c43406.svg" alt="GitHub" height="20" width="20">](github/repository/forking_allowed_for_repository.md) [GitHub](github/repository/secret_scanning.md)
 
 ### Operations
 

docs/SCM-BestPractices/github/repository/secret_scanning.md

@@ -0,0 +1,74 @@
+# Secret Scanning
+
+policy name: secret_scanning
+
+severity: HIGH
+
+## Description
+
+This security control checks for secrets being checked into a repository
+and prevents it.
+Turning on secret scanning detects many kinds of secrets being checked
+into a repository and reports it.
+Push protection builds on secret scanning and prevents attempts to add such
+secrets (and creates an alert if that is overridden).
+
+## Threat Example(s)
+
+Inserting a secret into a source code repository is unfortunately an easy
+mistake to make. Instructions for various services often
+encourage putting secrets into a repository (as it's the "simple" way
+to do it, though not the secure way).
+Once secrets are in a repository, they become available for anyone who
+can view the repository (directly or via a copy).
+Inserting secrets into a source code repository is a mistake, since
+it interferes with the whole point of a secret: keeping it secret.
+This is such a common type of vulnerability that it is identified as
+the Common Weakness Enumeration (CWE)
+[CWE-540: Inclusion of Sensitive Information in Source Code](https://cwe.mitre.org/data/definitions/540.html).
+
+## Remediation
+
+Like practically all tools, secret scanning is subject to false positives
+and false negatives. That said, secret scanning can prevent significant
+vulnerabilities and should be enabled.
+
+There are two different steps, scanning and enforcement:
+
+* On a new project you should enable both scanning and enforcement.
+* On an existing project you should enable scanning, ensure it works
+  well first, and *then* enable enforcement.
+
+### Enabling Secret Scanning
+
+[The GitHub documentation describes how to enable secret scanning](https://docs.github.com/en/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories).
+
+In short, to enable GitHub secret scanning on a repository:
+
+1. Make sure you have admin permissions
+2. Go to the repo's settings page
+3. Enter "Security" section of the sidebar, click "Code security and analysis".
+4. Click "Enable for secret scanning"
+5. Click "Save changes"
+
+You may also choose to enable other secret scanning tools.
+For example, those with access to the Linux Foundation's LFX tools should
+consider enabling its secret scanning tools as well.
+
+### Enforcing Secret Scanning
+
+In GitHub you can enable push protection on secret scanning
+for repositories and organizations.
+When this is enabled, secret scanning "blocks contributors
+from pushing secrets to a repository and generates an alert
+whenever a contributor bypasses the block."
+
+[The GitHub documentation describes how to enable push protection with secret scanning](https://docs.github.com/en/code-security/secret-scanning/push-protection-for-repositories-and-organizations).
+
+In short, to enforce GitHub secret scanning on a repository:
+
+1. Make sure you have admin permissions
+2. Go to the repo's settings page
+3. Enter "Security" section of the sidebar, click "Code security and analysis".
+4. Under "Code security and analysis", find "GitHub Advanced Security."
+5. Under "Secret scanning", under "Push protection", click "Enable".

docs/SCM-BestPractices/gitlab/project/secret_scanning.md

@@ -0,0 +1,70 @@
+# Secret Scanning
+
+policy name: secret_scanning
+
+severity: HIGH
+
+## Description
+
+This security control checks for secrets being checked into a repository.
+Turning on secret detection (also called secret scanning)
+detects many kinds of secrets being checked
+into a repository and reports it.
+At this time GitLab's mechanism for *preventing* this event is experimental.
+
+## Threat Example(s)
+
+Inserting a secret into a source code repository is unfortunately an easy
+mistake to make. Instructions for various services often
+encourage putting secrets into a repository (as it's the "simple" way
+to do it, though not the secure way).
+Once secrets are in a repository, they become available for anyone who
+can view the repository (directly or via a copy).
+Inserting secrets into a source code repository is a mistake, since
+it interferes with the whole point of a secret: keeping it secret.
+This is such a common type of vulnerability that it is identified as
+the Common Weakness Enumeration (CWE)
+[CWE-540: Inclusion of Sensitive Information in Source Code](https://cwe.mitre.org/data/definitions/540.html).
+
+## Remediation
+
+Like practically all tools, secret scanning is subject to false positives
+and false negatives. That said, secret scanning can prevent significant
+vulnerabilities and should be enabled.
+
+GitLab includes
+[two different secret detection methods](https://docs.gitlab.com/ee/user/application_security/secret_detection/)
+which can be used simultaneously:
+
+* The pipeline method "detects secrets during the project’s CI/CD pipeline.
+  This method cannot reject pushes".
+* The pre-receive method "detects secrets when users push changes to
+  the remote Git branch. This method can reject pushes if a secret is detected."
+
+However, as of 2024-05-14, the pre-receive method is an
+experiment with limited availability. Thus, we focus on the pipeline method.
+The pipeline method is unfortunately unable to *prevent* this, but at least
+it quickly warns you of the event.
+
+Note that secret scanning is automatically enabled if you enable
+[Auto DevOps](https://docs.gitlab.com/ee/topics/autodevops/index.html#enable-or-disable-auto-devops).
+
+Those with more complex needs must
+edit the `.gitlab-ci.yml` file manually.
+To do this:
+
+1. Make sure you can manage project merge requests permissions
+2. Go to the project's settings page
+3. Select "Build > Pipeline editor"
+4. Add the following to the end of the `.gitlab-ci.yml` file:
+
+   ~~~~yml
+   include:
+     - template: Jobs/Secret-Detection.gitlab-ci.yml
+   ~~~~
+
+5. Select the Validate tab, then select Validate pipeline.
+   The message "Simulation completed successfully" indicates the file is valid.
+6. Select the Edit tab.
+7. In the Branch text box, enter the name of the default branch.
+8. Select Commit changes.