Wording adjustments from test run.

Author: chriswblake

.github/steps/1-enable-codeql.md

@@ -35,14 +35,14 @@ Here are some options the default configuration provides:
 
 1. In the left navigation, fine the **Security** section and select **Advanced Security**.
 
-1. Scroll down and find the **Code scanning**.
+1. Scroll down and find the **Code scanning** area.
 
 1. In the **CodeQL** setting, click the **Set up** dropdown menu and choose **Default**.
 
    <img width="400" alt="enable code scanning" src="https://github.com/user-attachments/assets/0d639af3-a8fb-4ea7-8b94-44621a34fc3c"/>
 
 1. Click **Enable CodeQL**.
 
-   > This will trigger a first run of CodeQL. You can view the progress in the **Actions** tab.
+   > 💡 Tip: This will trigger a first run of CodeQL. You can view the progress in the **Actions** tab.
 
 1. With CodeQL now enabled, Mona will check your progress and share the next steps.

.github/steps/2-review-and-triage-codeql-alerts.md

@@ -2,95 +2,67 @@
 
 Now we will review the CodeQL scan results, triage an alert, and create a GitHub issue to track an alert.
 
-### What is GitHub Actions
-
-GitHub Actions is the automation and CI/CD platform within GitHub. We use GitHub Actions to orchestrate and execute security scans with code scanning. GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. For more information on GitHub Actions, see "[Understanding GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions)."
-
 ### What is CWE
 
-Common Weakness Enumeration (CWE) is a category system for hardware and software weaknesses and vulnerabilities. Think of it as a way to describe and categorize security issues in an application's source code. For more information on CWEs, see the Wikipedia article "[Common Weakness Enumeration](https://en.wikipedia.org/wiki/Common_Weakness_Enumeration)."
+Common Weakness Enumeration (CWE) is a category system for hardware and software weaknesses and vulnerabilities. Think of it as a way to describe and categorize security issues in an application's source code. For more information on CWEs, see the Wikipedia article [Common Weakness Enumeration](https://en.wikipedia.org/wiki/Common_Weakness_Enumeration).
 
 ### ⌨️ Activity: View the status of a CodeQL scan
 
-In this activity, we'll explore GitHub Actions to view the status of a CodeQL scan.
-
-1. In your new repository, go to your Actions page by selecting **Actions** from the top navigation bar. If the CodeQL Action run is still executing, you will see a yellow spinner indicating the scan is still in progress. This typically takes about 4 minutes to complete.
-
-1. Select the run by clicking on **CodeQL Setup**.
+1. In the top navigation, select the **Actions** tab.
 
-   <img width="400" alt="codeql setup" src="https://github.com/user-attachments/assets/016a729e-3b41-466c-8edf-3d4b41a86b7d"/>
+1. If needed, wait a moment for the CodeQL run to finish (about 4 minutes).
 
-   Notice that more information is available inside the Actions run. Feel free to explore this section to view information such as the CodeQL logs, duration, status, and artifacts generated by CodeQL.
+1. Click on the **CodeQL Setup** workflow run entry to open a page showing more details.
 
-   Once the scan is complete, a green check will show next to the execution.
+   <img width="500" alt="codeql setup" src="https://github.com/user-attachments/assets/016a729e-3b41-466c-8edf-3d4b41a86b7d"/>
 
-### ⌨️ Activity: View all CodeQL Alerts
+   > 💡 Tip: The workflow run contains additional CodeQL information such as the run duration, logs, and analysis artifacts.
 
-In this activity, we will view the CodeQL findings in the Security page of your repository. The Security page is where all security related information is displayed.
+### ⌨️ Activity: Review an Alert
 
-1. Navigate to the **Security** tab in the top navigation bar of your repository.
+1. In the top navigation, select the **Security** tab.
 
-1. Select **Code scanning** under the "Vulnerability alerts" heading in left-side navigation bar.
+1. In the left navigation, find the **Vulnerability alerts** area and select the **Code scanning** option.
 
-   This screen will contain all the vulnerabilities identified by CodeQL inside this repository's codebase. Explore the different filters and search capabilities in this page. These filtering capabilities become very helpful when you're working with many findings!
+1. (Optional) Use the filters and search bar to explore the open and closed security alerts, including from the CodeQL scan.
 
-### ⌨️ Activity 3: Review an Alert
+#### Alert status and location
 
-In this activity, we will explore the alert UI. We'll review the data flow of the vulnerability, identify what part of the code the alert impacts, and get more information about the alert.
+The main area of the alert provides the resolution status, affected branch, code location, and classification information like severity and [CVE identification number](https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories#cve-identification-numbers).
 
-**Alert status:** This section displays the current alert status (open or closed), identifies the branch where the scan detected the alert, and shows the timestamp of the alert.
+> 💡 Tip: Clicking the **Show paths** link will provide additional insights about the alert's data flow from user input (source), through the application, and when it is acted on (sink).
 
-<img width="400" alt="alert status" src="https://github.com/user-attachments/assets/2fecc67d-52ef-44fc-ad89-1eb28ceb9437">
+<img width="500" alt="alert status" src="https://github.com/user-attachments/assets/2fecc67d-52ef-44fc-ad89-1eb28ceb9437">
 
-**Location information:** This section describes which part of the code is vulnerable.
+<img width="500" alt="location information" src="https://github.com/user-attachments/assets/1a450118-f200-436b-8433-04b7e5e4f1a8"/>
 
-<img width="400" alt="location information" src="https://github.com/user-attachments/assets/1a450118-f200-436b-8433-04b7e5e4f1a8"/>
+<img width="500" alt="additional information" src="https://github.com/user-attachments/assets/9a5aaf3f-e063-4d07-8cdd-6272eec8a411"/>
 
-**Paths:** Clicking on "Show paths" will give you additional insights into the alert's data flow. The modal shows us where the user input (we call that a "source") flows through the application until it's acted on (we call this the "sink"). This visualizes the flow of data through your application.
+#### Explanation and Recommendation
 
-**Recommendations:** This section provides a quick overview of the tool (CodeQL in this case), Rule ID, and even allows you to view the CodeQL query used to find this vulnerability. You can view the query by clicking **View source**. Additionally, this pane includes recommendations for fixing this vulnerability. Click **Show more** to view the full recommendation.
+This alert is further described, justified, and a recommended solution is provided when possible.
 
-<img width="400" alt="recommendations" src="https://github.com/user-attachments/assets/a5653b45-b66f-4e5b-8e03-a7b8cd3b91b4"/>
+- Click the **View source** link to view the CodeQL query that detected the alert.
+- Click the **Show more** link to view the full recommendation.
 
-**Audit trail:** The audit trail shows the history of the alert. This trail will show the status as users mark an alert as closed or fix an alert in the code.
+<img width="500" alt="recommendations" src="https://github.com/user-attachments/assets/a5653b45-b66f-4e5b-8e03-a7b8cd3b91b4"/>
 
-<img width="400" alt="audit trail" src="https://github.com/user-attachments/assets/25ec5256-20c7-4e9d-8160-ff40f3763872"/>
+#### Audit trail
 
-**Alert triage:** Use the buttons at the top right of the alert to triage or create a new issue for the alert. Don't do anything yet. We'll get into these buttons in a moment. 😄
+The audit trail provides a secure history of the alert for future reference, like who marked the vulnerability as closed/fixed.
 
-**Additional info:** Finally, the right-side panel contains information such as tags, CWE information, and the severity of the alert
-<img width="400" alt="additional information" src="https://github.com/user-attachments/assets/9a5aaf3f-e063-4d07-8cdd-6272eec8a411"/>
+<img width="500" alt="audit trail" src="https://github.com/user-attachments/assets/25ec5256-20c7-4e9d-8160-ff40f3763872"/>
 
 ### ⌨️ Activity: Dismiss an Alert
 
-Now that we're familiar with the alert layout, let's work through the process of closing one.
-
-1. Inside this same alert, click **Dismiss alert**, choose any reason for dismissal, and add a short note.
-
-1. Click **Dismiss alert**.
-
-1. At this point, the alert will change its state to "Dismissed". You can now see the change you made in the audit trail at the bottom of the alert.
-
-1. Navigate back to **Security** > **Code scanning alerts**. You'll see that you only have 1 alert listed.
-
-1. Click **1 Closed**. This will bring you to the closed alerts where you can view the alert you just closed.
-
-   <img width="400" alt="one closed alert" src="https://github.com/user-attachments/assets/b10005b6-9ef8-4d46-a160-4c9849d2c898"/>
-
-1. (Optional) You can also reopen the alert by opening it, then selecting **Reopen alert**.
-
-### ⌨️ Activity: Create a GitHub Issue for an Alert
-
-This last step will show you how to create a GitHub Issue to track the work that goes into resolving a vulnerability. Issues provide a space for collaboration for a security problem and can be assigned to people or teams.
-
-1. Open one of the open alerts that CodeQL identified from the scan.
+1. On the alert page, in the top right, click **Dismiss alert** dropdown.
 
-1. Click the green **Create issue** button at the top right of the alert. If you don't see this button, check the status of the alert to make sure it's an open alert.
+1. Select any reason and add a short explanation then click the **Dismiss alert** button.
 
-1. Add any details you would like to include in the new issue form.
+    - The alert state will change to `Dismissed` and an audit trail entry will be added.
 
-1. Click **Submit new issue**.
+1. Navigate back to **Security** tab and **Code scanning alerts** area.
 
-1. To view the your issue, click **Issues** in the top navigation bar of your repository.
+1. Click the **1 Closed** text to switch to a view showing closed alerts.
 
-1. With the new issue opened for managing the fix, Mona will check your progress and share the next steps.
+   <img width="500" alt="one closed alert" src="https://github.com/user-attachments/assets/b10005b6-9ef8-4d46-a160-4c9849d2c898"/>

.github/steps/3-fix-security-vulnerabilities.md

@@ -1,49 +1,50 @@
 ## Step 3: Fix Security Vulnerabilities
 
-Let's fix the existing security vulnerabilities already identified by CodeQL. Remember, at this point, we have introduced CodeQL into our repository and had it scan the existing code. The vulnerabilities it found are real-world issues, and they need to be fixed! We'll fix this issue by editing the `/server/routes.py` file.
-
-### ⌨️ Activity 1: Review alerts
-
-First, before we fix these alerts, we need to make sure the alerts are still open. We'll also need to gather information on which files to fix and how best to fix them.
-
-1. Navigate to your code scanning alerts page: **Security** > **Code scanning**.
-
-1. You should see two alerts listed as "**Open**". If any of the alerts are listed as "**Closed**", open the alert page and choose **Reopen alert**.
+Let's fix the existing security vulnerabilities already identified by CodeQL. Remember, at this point, we have introduced CodeQL into our repository and it has scanned the existing code. The vulnerabilities it found are real-world issues, and they need to be fixed!
 
 Now that both of these alerts are open, let's fix them. If you look at the alerts, they both call out one specific file containing the issues: `server/routes.py`. The issue is in crafting the SQL query for the database. These queries are vulnerable to SQL injection attacks. We should rewrite these SQL statements more securely.
 
 If you expand the **More info** section at the bottom of the alert, there are very clear suggestions to fix this query. We're going to implement those suggestions in the next activity.
 
-### ⌨️ Activity: Edit routes.py
+### ⌨️ Activity: Resolve an open alert
 
-We now know where the issues exist and how to fix them. We'll start by modifying the file `routes.py`. Again, you'll want to do these next steps in a separate browser window or tab.
+1. In the top navigation, select the **Security** tab.
 
-1. Click the **Code** tab in your repository.
+1. In the left navigation, find the **Vulnerability alerts** area and select the **Code scanning** option. You should see two open alerts.
 
-1. Select the `server` folder.
+   > 🪧 Note: If any of the alerts are `Closed`, go to the alert's page and choose **Reopen alert**.
 
-1. Select the `routes.py` file.
+1. Review the 2 open alerts and review the recommendations to decide changes to make.
 
-1. Click the **Edit** button to the right.
+1. In the top navigation, select the **Code** tab.
+
+1. Navigate to the `server` folder and select the `routes.py` file.
+
+1. In the top right of the preview, click the **Edit** button.
 
    <img width="400" alt="edit button" src="https://github.com/user-attachments/assets/19462cc5-a360-4dae-a97b-ecfd571aa403"/>
 
-1. Edit line 16 by highlighting the SQL statement and replace it with this text.
+1. Navigate to about **line 16** and modify it to the below.
 
    ```py
    "SELECT * FROM books WHERE name LIKE %s", name
    ```
 
-1. Edit line 22 to replace the SQL statement with this text.
+1. Navigate to about **line 22** and modify it to the below.
 
    ```py
    "SELECT * FROM books WHERE author LIKE %s", author
    ```
 
-1. Click **Commit changes...** from the top right. The "Propose changes" window will pop up. Leave the defaults configured, and click **Commit changes** again.
+1. Above the editor in the top-right, click the **Commit changes...** button. Use the defaults options to commit the changes to `main`.
+
+   - CodeQL will now initiate a another scan.
+
+1. In the top navigation, navigate to the **Actions** tab. Wait for the **CodeQL** workflow to finish.
 
-1. CodeQL will now initiate a new scan. Check the status of that scan by navigating to **Actions** then choose the **CodeQL** action. Once the scan job completes, Actions will display a green check next to the last run.
+1. Return the the open alerts page and review the open alerts.
 
-1. Once that CodeQL scan is done, navigate to **Security** > **Code scanning** to review the alerts. You should have zero open alerts and two closed alerts 🎉. Feel free to review the closed alerts, especially the audit trail.
+   - There should be zero open alerts and two closed alerts. Nice work! 🎉
+   - Feel free to review the closed alerts, especially the audit trail.
 
-1. With the file change committed, Mona will check your progress and share the next steps.
+1. With the CodeQL job finished, Mona will check your progress and share the next steps.

.github/steps/4-prevent-vulnerabilities-in-the-pull-request.md

@@ -1,47 +1,27 @@
-## Step 4: Prevent Vulnerabilities in the Pull Request
+## Step 4: Prevent Vulnerabilities in a Pull Request
 
-The last step is to try pull request integration with CodeQL. In this step, we will add a vulnerability back into the `routes.py` file to trigger an alert for a SQL injection vulnerability. This is going to be the same issue we initially saw.
+In this step, we will add a vulnerability back into the `routes.py` file to trigger an alert.
+However, this time the change will be on a pending pull request, being detected before it reaches production.
 
-Our goal is to understand what developers experience when they find a new vulnerability.
+### ⌨️ Activity: Recreate a vulnerability
 
-In this step, we will:
+1. In the top navigation, select the **Code** tab.
 
-- edit the `routes.py` file.
-- change the SQL statement to make it insecure.
-- commit those changes and merge the insecure code into the main branch.
-- experience the alert inside the pull request.
+1. Navigate to the `server` folder and select the `routes.py` file.
 
-**What is pull request**: Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators. This allows multiple people to work on the same code at the same time. For more information, check out the GitHub Skills exercise "[Introduction to GitHub](https://github.com/skills/introduction-to-github)" or "[About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)" from the GitHub docs.
-
-**What is branch**: A branch is a parallel version of your repository. By default, your repository has one branch named main and it is considered to be the definitive branch. Creating additional branches allows you to copy the main branch of your repository and safely make any changes without disrupting the main project. For more information, see "[About branches](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#)" in the GitHub docs.
-
-### ⌨️ Activity: Edit `routes.py` and create a new pull request
-
-In this first activity, we'll introduce the same insecure SQL statement from before to the `routes.py` file. Once we update the file, we'll commit it to a new branch, then create a pull request.
-
-1. Click the **Code** tab in your repository.
-
-1. Select the `server` folder.
-
-1. Select the `routes.py` file.
-
-1. Click the **Edit** button to the right.
+1. In the top right of the preview, click the **Edit** button.
 
    <img width="400" alt="edit button" src="https://github.com/user-attachments/assets/19462cc5-a360-4dae-a97b-ecfd571aa403"/>
 
-1. Edit line 16 by highlighting the SQL statement and replace it with this text.
+1. Navigate to about **line 16** and modify it to the below to re-introduce the vulnerability.
 
    ```py
    "SELECT * FROM books WHERE name LIKE '%" + name + "%'"
    ```
 
-1. Click **Commit changes...** from the top right. The "Propose changes" window will pop up.
-
-1. This time, select the radio button next to **Create a new branch**. You can create a new name for this branch or leave it as the default suggestion.
-
-1. Click **Propose changes**. This opens a new pull request.
+1. Above the editor in the top-right, click the **Commit changes...** button. Don't commit it to `main`. Select the radio button next to **Create a new branch**.
 
-1. In the "Open a pull request" window, click **Create pull request**.
+1. Click **Propose changes** option and click **Create pull request**.
 
 ### ⌨️ Activity: Review pull request
 

README.md

@@ -8,7 +8,7 @@ _Learn to identify, resolve, and prevent insecure coding patterns._
 - **What you'll learn**: How to enable code scanning to identify typical vulnerabilities like SQL injection, review alerts, and take action to fix them.
 - **What you'll build**: An automated process to identify existing vulnerabilities and prevent future vulnerabilities in production code.
 - **Prerequisites**:
-  - Introduction to GitHub
+  - [Introduction to GitHub](https://github.com/skills/introduction-to-github)
 - **How long**: Less than 30 minutes.
 
 ### How to start this exercise