Skip to content

Commit

Permalink
Add secret scanning to SCM guide, fixes #488 (#489)
Browse files Browse the repository at this point in the history 
* Add secret scanning to SCM guide, fixes #488

Signed-off-by: David A. Wheeler <[email protected]>

* Fix markdownlint issues

Signed-off-by: David A. Wheeler <[email protected]>

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

fixes typo

Co-authored-by: Chris de Almeida <[email protected]>
Signed-off-by: CRob <[email protected]>

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

better word choice

Co-authored-by: Chris de Almeida <[email protected]>
Signed-off-by: CRob <[email protected]>

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

"quotes"

Co-authored-by: Chris de Almeida <[email protected]>
Signed-off-by: CRob <[email protected]>

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

"quotes"

Co-authored-by: Chris de Almeida <[email protected]>
Signed-off-by: CRob <[email protected]>

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

"quotes"

Co-authored-by: Chris de Almeida <[email protected]>
Signed-off-by: CRob <[email protected]>

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

better word choice

Co-authored-by: Chris de Almeida <[email protected]>
Signed-off-by: CRob <[email protected]>

* Update docs/SCM-BestPractices/README.md

Co-authored-by: Chris de Almeida <[email protected]>
Signed-off-by: David A. Wheeler <[email protected]>

---------

Signed-off-by: David A. Wheeler <[email protected]>
Signed-off-by: CRob <[email protected]>
Co-authored-by: CRob <[email protected]>
Co-authored-by: Chris de Almeida <[email protected]>
  • Loading branch information
@david-a-wheeler @SecurityCRob @ctcpip
3 people authored Nov 5, 2024
1 parent 8b596c2 commit 95fd687
Show file tree
Hide file tree
Showing 3 changed files with 145 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/SCM-BestPractices/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/secret_scanning.md) [GitHub](github/repository/secret_scanning.md)

### Operations

Expand Down
74 changes: 74 additions & 0 deletions docs/SCM-BestPractices/github/repository/secret_scanning.md
View file
Original file line number Diff line number Diff line change
@@ -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".
70 changes: 70 additions & 0 deletions docs/SCM-BestPractices/gitlab/project/secret_scanning.md
View file
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 95fd687

Please sign in to comment.