Skip to content

Commit

Permalink
Merge pull request #6 from skills/felicitymay/update-course-text
Browse files Browse the repository at this point in the history 
Skills secret scanning course: text updates to adjust for a few changes since the course was created and for consistency
  • Loading branch information
@felicitymay
felicitymay authored Apr 25, 2024
2 parents f3f7b12 + 11fbbc8 commit eada3c9
Show file tree
Hide file tree
Showing 4 changed files with 56 additions and 101 deletions.
29 changes: 11 additions & 18 deletions .github/steps/1-tbd.md
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,35 @@
<!--
<<< Author notes: Step 1 >>>
Choose 3-5 steps for your course.
The first step is always the hardest, so pick something easy!
Link to docs.github.com for further explanations.
Encourage users to open new tabs for steps!
TBD-step-1-notes.
-->

## Step 1: Enable Secret Scanning

_Welcome to "Introduction to Secret Scanning"! :wave:_

In this step, you will enable secret scanning on this repository. Once secret scanning is enabled, you will add a new credential to see how secret scanning identifies the credential.

**What is a secret**: In the context of secret scanning, a secret (or credential) is a plain-text string that authorizes a user to any number of third-party services. Examples could be AWS secret access keys/ID's, Google API keys, or Stripe API tokens. GitHub Docs hosts the [entire list of supported patterns](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-patterns#supported-secrets).
**What is a secret**: In the context of secret scanning, a secret (or credential) is a plain-text string, or a pair of strings, that authorizes a user to access a service. Examples could be AWS secret access keys/ID's, Google API keys, or Stripe API tokens. GitHub Docs hosts a list of [all supported patterns](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-patterns#supported-secrets).

### :keyboard: Activity 1.1: Enable secret scanning

Secret scanning is enabled by default for all new public repositories. If you're working in a public repository, you can go straight to "Activity 1.2: Commit a token." For private or internal repositories, secret scanning is available with [GitHub Advanced Security](https://docs.github.com/en/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security).

1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab.
2. In your newly created repository, select **Settings** from the top navigation bar.
3. Under the **Security** section on the left side, select **Code security and analysis**.
4. Scroll to the bottom of this page and select the **Enable** button next to "Secret scanning"
4. Scroll to the bottom of this page and select the **Enable** button next to "Secret scanning."

> [!IMPORTANT]
> When you enable secret scanning, you may receive an email notification about credentials in your repository. Don't worry! The tokens in this Skills repo are inactive. There is no risk to your environment.
> When you enable secret scanning, you may receive an email notification about credentials in your repository. Don't worry! The tokens in this Skills repository are inactive. There is no risk to your environment.
### :keyboard: Activity 1.2: Commit a token

Now that you have secret scanning enabled in this repository, let's commit a new token to see how it works. You'll commit an AWS key and access ID to the repository. Don't worry, this is an inactive token that can't be used to log in to AWS.

1. Like the first activity, you will need to work on these steps in a second browser tab.
2. Click the Code tab in your repository.
3. Select the `credentials.yml` file.
1. You should continue to work on activities in a second browser tab.
2. Click the **Code** tab in your repository.
3. Display the `credentials.yml` file.
4. Click the Edit button to the right.

![A screenshot of credentials.yml on the GitHub web interface with the edit button outlined](/images/edit-credentials-file.png)

5. Copy the following text and paste it to the bottom of the `credentials.yml` file.
5. Copy the following text and paste it at the bottom of the `credentials.yml` file.

```yaml
default:
Expand All @@ -46,5 +39,5 @@ Now that you have secret scanning enabled in this repository, let's commit a new
region: us-east-2
```
6. Click **Commit changes...** from the top right. The "Propose changes" window will pop up. Leave the defaults configured, and click **Commit changes** again.
7. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.
6. Click **Commit changes...** at the top right. The "Commit changes" window is displayed. Leave the defaults configured, and click **Commit changes** to commit directly to the `main` branch.
7. Wait about 20 seconds, then refresh this page (the one you're following instructions from). A GitHub Actions workflow in the repository will run and automatically replace this contents of this `README` file with instructions for the next step.
75 changes: 36 additions & 39 deletions .github/steps/2-tbd.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,6 @@
<!--
<<< Author notes: Step 2 >>>
Start this step by acknowledging the previous step.
Define terms and link to docs.github.com.
TBD-step-2-notes.
-->

## Step 2: Review and close secret scanning alerts

_You did Step 1: Enable secret scanning! :tada:_
_You've enabled secret scanning and added a secret to test that the feature is working! :tada:_

In the last step, you enabled secret scanning on the repository and committed an AWS credential to the repository. In this step, you'll first review the secret scanning alerts. Afterward, you'll enable push protection which prevents you from accidentally writing credentials to a repository. Finally, you'll attempt to write a new credential to see how push protection works.

Expand All @@ -21,64 +14,65 @@ This page contains the list of secret scanning alerts. You can filter and sort t

- **Amazon AWS Secret Access Key**: This is the access key you committed in the last step
- **Amazon AWS Access Key ID**: This is the key ID committed in the last step
- **GitHub Personal Access Token**: This token was already in the `credentials.yml`before you got started
- **GitHub Personal Access Token**: This token was already in the `credentials.yml` file before you started

### :keyboard: Activity 2.2: Review a secret scanning alert

In this activity, you will explore the alert UI. You'll review the validity of the secret and identify where the secret was detected in the repository.
In this activity, you will explore the alert. You'll review the validity of a secret and identify where the secret was detected in the repository.

Open the **Amazon AWS Access Key ID** alert.
Open the **Amazon AWS Access Key ID** alert and explore the information shown.

**Alert status:** This section identifies the current status of the alert (open or closed) and identifies when the alert was first detected.
- **Alert status:** This section shows the current status of the alert (open or closed) and reports when the alert was first detected.

![A screenshot of the Amazon AWS Access Key ID alert with the currently open status highlighted](/images/alert-status.png)
![Screenshot of the Amazon AWS Access Key ID alert with the currently open status highlighted.](/images/alert-status.png)

**Alert validity state:** Secret scanning checks the validity state with certain partners to understand if the token is currently active in the partner platform. This section shows the validity state. The validity states include "Active", "Inactive", and "Possibly active". A secret will be in the "Possibly active" state until the partner validates that it is either active or inactive.
- **Alert validity state:** Displayed only for tokens where secret scanning can contact the partner platform to check whether the token is currently active. This section shows the validity state: "Active", "Inactive", or "Possibly active", and how to remediate the exposed secret. A secret has the "Possibly active" state until the partner validates that it is either active or inactive.

![A screenshot of the Amazon AWS Access Key ID alert with the validity state highlighted](/images/alert-validity-state.png)
![Screenshot of the Amazon AWS Access Key ID alert with the validity state highlighted.](/images/alert-validity-state.png)

**Secret location:** This section describes the locations where the secret was identified in your repository. If the secret exists in multiple files, secret scanning will link to each file. The committer, a link to the commit sha, and the commit date are also included for each location.
- **Secret location:** This section describes the locations where the secret was identified in your repository. If the secret exists in multiple files, secret scanning will link to each file. The committer, a link to the commit SHA, and the commit date are also included for each location. Note that you should ignore the first two locations as they are part of the definition of the course. You can see the token you added in `credentials.yml` as the third location.

![A screenshot of an alert with the secret location highlighted](/images/secret-location.png)
![Screenshot of an alert with a secret location highlighted.](/images/secret-location.png)

**Alert audit trail:** The alert audit trail contains any changes to the state of the alert as well as who made the change. In this example, the alert only has an "Opened" event. If the alert is closed, a new event will be added to the audit trail.
- **Alert audit trail:** The alert audit trail contains any changes to the state of the alert as well as who made the change. In this example, the alert only has an "Opened" event so far. If the alert is closed, a new event will be added to the audit trail.

![A screenshot of the bottom of an alert with the audit trail highlighted](/images/audit-trail.png)
![Screenshot of the bottom of an alert with the audit trail highlighted.](/images/audit-trail.png)

### :keyboard: Activity 2.3: Close an alert

When secret scanning finds a secret in your repository, the first thing you should do is disable that secret on the provider side. This prevents any further use of that credential. Once the secret has been disabled, the next step is to close the alert by marking it as "Revoked". In this activity, you will open an alert that has been validated as "Inactive" by secret scanning, then mark that alert as "Revoked" in secret scanning.

1. From the list of secret scanning alerts (in your other tab), open the alert titled **GitHub Personal Access Token**.
2. At the top of this alert, note that this alert is marked as "Secret inactive on github.com". Secret scanning has already validated this credential and found that it is disabled.
**NOTE:** If the token has not yet been validated, click the **Verify secret** button.
3. Select the **Close as** dropdown
4. Choose **Revoked**
5. Enter a comment in the text box
6. Choose **Close alert**
![A screenshot of the GitHub Personal Access Token alert, the close alert options are activated and the option "revoked" is highlighted. The comment field has been filled in with "secret inactive"](/images/revoke-token.png)
7. Note that the alert has changed state to "Closed" and that a new entry has been added to the audit trail at the bottom of the alert.
1. In your other tab, return to the full list of secret scanning alerts, either using the **Secret scanning alerts** link at the top left of the alert or by using the **Security** tab as described above.
2. From the list of secret scanning alerts, open the alert titled **GitHub Personal Access Token**.
3. At the top of this alert, if the alert is marked as "Secret inactive on github.com" then secret scanning has already validated this credential and found that it is disabled. If the alert is still marked as "Possibly active secret", click the **Verify secret** button to validate it now.
5. Now we know that this secret is no longer active, we are ready to close the alert. Select the **Close as** dropdown and choose **Revoked**.
7. Enter a comment in the text box.
8. Choose **Close alert**.
![Screenshot of the GitHub Personal Access Token alert, the close alert options are activated and the option "revoked" is highlighted. The comment field has been filled in with "secret inactive".](/images/revoke-token.png)
9. Note that the alert now has a state of "Closed" and that the audit trail at the bottom of the alert shows that you closed the alert as revoked.

## Step 3: Enable push protection

_Way to go! You completed Step 2: Review secret scanning alerts :tada:_
_Way to go! You reviewed and closed a secret scanning alert! :tada:_

Up to now, you've learned how to identify secrets already stored in your repository. In this section, you will enable push protection on the repository to prevent new secrets from being written to the repository.

**What is push protection**: When code is being written to GitHub (a push), secret scanning checks for high-confidence secrets (those identified with a low false positive rate). Secret scanning lists any secrets it detects so the author can review the secrets and remove them or, if needed, allow those secrets to be pushed.
**What is push protection**: When someone tries to send code changes to GitHub (a push), secret scanning checks for high-confidence secrets (those identified with a low false-positive rate). Secret scanning lists any secrets it detects so the author can review the secrets and remove them or, if needed, allow those secrets to be pushed.

### :keyboard: Activity 3.1: Enable push protection

Push protection is enabled by default for all public repositories. If you're working in a public repository, you can go straight to "Activity 3.2: Attempt to push a secret." For private or internal repositories, enable push protection in the repository "Settings."

1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab.
2. Navigate to **Settings** on the top navigation bar.
3. Under the "Security" section on the left side, select **Code security and analysis**.
4. Scroll to the bottom of the page and select **Enable** next to "Push Protection."

### :keyboard: Activity 3.2: Attempt to push a secret

Now that you have enabled secret scanning push protection, certain new secrets will be blocked from being written to the repository. In this activity you will commit a new credential to the repository to experience the block protection.
Now that push protection for secret scanning is enabled, new secrets that secret scanning has high confidence in identifying will be blocked from being written to the repository. In this activity you will commit a new credential to the repository to experience the push protection.

1. In your other browswer tab, click **Code** from the top navigation bar.
1. In your other browswer tab, click **Code** in the top navigation bar.
2. Open the `credentials.yml` file.
3. Click the **Edit** button (pencil icon) to the right.
4. Copy and paste the following string into the end of the file:
Expand All @@ -89,19 +83,22 @@ Now that you have enabled secret scanning push protection, certain new secrets w

5. Delete `<REMOVEME>` from the string you just pasted. The `<REMOVEME>` string is there so secret scanning doesn't create an alert before you're able to test push protection. Your file should look like this:

![A screenshot of credentials.yml being edited in the GitHub web UI. A newly added github-token is highlighted.](/images/push-protection.png)
![Screenshot of credentials.yml being edited in the GitHub web interface. A newly added github-token is highlighted.](/images/push-protection.png)

6. Select **Commit changes...**.
7. Select **Commit changes**.
8. Instead of committing the updated file to your repository, a push protection alert warns you that your changes include a GitHub Personal Access Token.

6. Select **Commit changes...**
7. Select **Commit changes**
8. At this point, an alert will show on your page informing you that a new secret is being added to the repository.
> [!TIP]
> When you work in a local environment or a GitHub Codespace, secret scanning cannot block your commit. Instead, your push to GitHub is blocked. In this case, if the secret is active then you will need to remove the secret from your branch and commit history, see [Resolving a blocked push on the command line](https://docs.github.com/en/code-security/secret-scanning/pushing-a-branch-blocked-by-push-protection#resolving-a-blocked-push-on-the-command-line).
### :keyboard: Activity 3.3: Bypass push protection

Now that you're aware of the secret in your commit, you should remove the secret from the commit and commit history, then attempt the push again. In some cases, you may be willing to accept the risk of adding a secret to your repository. In those situations, you can choose to bypass push protection. In this activity, you will bypass push protection and write the token to your repository (don't worry, the example token is safe).
Now that you're aware of the secret in your changes, you should remove the secret and then attempt the commit again. In some cases, you may be willing to accept the risk of adding a secret to your repository. In those situations, you can choose to bypass push protection. In this activity, you will bypass push protection and write the token to your repository (don't worry, the example token is safe).

1. Select the radio button next to **It's used in tests**.
2. Click **Allow secret**.
3. A notification will show saying that you can now commit the secret.
3. A notification banner reports that you can now commit the secret.
4. Select **Commit changes...** again.
5. Select **Commit changes**.
6. Wait about 20 seconds then refresh this page (the one you're following instructions from). GitHub Actions will automatically update to the next step.
6. Wait about 20 seconds, then refresh this page (the one you're following instructions from). A GitHub Actions workflow in the repository will run and automatically replace this contents of this `README` file with instructions for the next step.
15 changes: 6 additions & 9 deletions .github/steps/X-finish.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,20 @@
<!--
<<< Author notes: Finish >>>
Review what we learned, ask for feedback, provide next steps.
-->

## Finish 🏆

_Congratulations friend, you've completed this course!_

Here's a recap of all the tasks you've accomplished in your repository:

- Enabled secret scanning on your repository
- Enabled secret scanning if your repository has private or internal visibility
- Committed a secret to the repository
- Reviewed secrets that have been identified by secret scanning
- Closed a secret scanning alert
- Enabled secret scanning push protection to prevent secrets from being written to the repository
- Enabled secret scanning push protection to prevent secrets from being written to the repository (required only for private or internal repositories)
- Attempted to commit a secret, but had that commit stopped by push protection
- Bypassed the push protection
- Bypassed push protection

It's important to note that secret scanning capabilities are available for free for all public repositories. Customers who want to enable secret scanning on private repos should find out more about [GitHub Advanced Security](https://docs.github.com/en/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security) or [Set up a trial of GitHub Advanced Security](https://docs.github.com/en/enterprise-cloud@latest/billing/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security).

It's important to note that secret scanning capabilities are available for free for all public repositories. Customers needing secret scanning for private repos should investigate [GitHub Advanced Security](https://docs.github.com/en/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security). In addition to the features you worked with here, Advanced Security also provides the following features:
In addition to the features you worked with here, GitHub Advanced Security also provides the following features:

- Custom secret scanning patterns
- Non-partner and generic patterns including passwords, RSA and SSH keys, and database connection strings
Expand Down
Loading

0 comments on commit eada3c9

Please sign in to comment.