Reorganizing and wording adjustments

chriswblake · web-flow · commit 366f136b692a · 2025-06-29T07:37:23.000Z
diff --git a/.github/steps/1-step.md b/.github/steps/1-step.md
@@ -13,12 +13,12 @@ In this first step, we'll be learning more about [CodeQL](https://codeql.github.
 
 [CodeQL](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql) is a static analysis testing tool that helps you identify security weaknesses such as SQL injection, cross-site scripting, and code injection issues.
 
-<img width="200" align="right" alt="codeql default configuration box" src="https://github.com/user-attachments/assets/cf5ba96b-98bb-4db5-b743-bd31bceaabac"/>
-
 Typically CodeQL patterns are collected into [query suites](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql#about-codeql-queries) of patterns. When combined well, this can be a very powerful! To help with this, teams of security experts have pre-populated suites for many common scenarios and programming languages.
 
 In many cases, taking advantage of CodeQL is as simple as accepting the default suite, but you can also select the extended suite or customize your own with [GitHub Actions]().
 
+<img width="200" align="right" alt="codeql default configuration box" src="https://github.com/user-attachments/assets/cf5ba96b-98bb-4db5-b743-bd31bceaabac"/>
+
 Here are some options the default configuration provides:
 
 - **Languages:** The languages automatically detected in your repository that CodeQL will scan.
diff --git a/.github/steps/2-step.md b/.github/steps/2-step.md
@@ -1,8 +1,8 @@
-## Step 2: Prevent Vulnerabilities in a Pull Request
+## Step 2: Detect Vulnerabilities in a Pull Request
 
 In this step, we will introduce a vulnerability into the `routes.py` file to trigger an alert.
 
-### ⌨️ Activity: Recreate a vulnerability
+### ⌨️ Activity: Create a vulnerability
 
 1. In the top navigation, select the **Code** tab.
 
@@ -18,15 +18,19 @@ In this step, we will introduce a vulnerability into the `routes.py` file to tri
    "SELECT * FROM books WHERE name LIKE '%" + name + "%'"
    ```
 
-1. Above the editor in the top-right, click the **Commit changes...** button. Select the radio button next to **Create a new branch**. **DO NOT commit it to main branch.**
+1. Above the editor in the top-right, click the **Commit changes...** button. Select the radio button next to **Create a new branch** option. **DO NOT commit to the main branch.**
 
-1. Click **Propose changes** option and click **Create pull request**.
+1. Click the **Propose changes** option and click **Create pull request**. Use the following branch name.
+
+   ```txt
+   learning-codeql
+   ```
 
 ### ⌨️ Activity: Review pull request
 
-1. If needed, navigate to the newly created pull requests from the previous activity.
+1. If needed, navigate to the newly created pull request from the previous activity.
 
-1. Scroll to the bottom of the pull request. Search for a check named `CodeQL`. This is the analysis job scanning the proposed code changes in the pull request.
+1. Scroll to the bottom of the pull request and search for a check named `CodeQL`. This is the analysis job scanning the proposed code changes in the pull request.
 
    <img width="500" alt="pr panel" src="https://github.com/user-attachments/assets/1c29ee0f-cc1d-4568-9e71-338d45ad1d54"/>
 
@@ -39,7 +43,20 @@ In this step, we will introduce a vulnerability into the `routes.py` file to tri
 
    <img width="500" alt="image" src="https://github.com/user-attachments/assets/677cc104-9116-44a9-8061-091e8126442a">
 
-1. With the pull request started, Mona will check your progress and share the next steps.
+### ⌨️ Activity: View the CodeQL scanning logs
+
+1. In the top navigation, select the **Actions** tab.
+
+1. Click on the **CodeQL Setup** workflow run entry to open a page showing more details.
+
+   <img width="500" alt="codeql setup" src="https://github.com/user-attachments/assets/016a729e-3b41-466c-8edf-3d4b41a86b7d"/>
+
+   > 💡 Tip: The workflow run contains additional CodeQL information such as the run duration, logs, and analysis artifacts.
+
+1. With the pull request started and CodeQL scan finished, Mona will check your progress and share the next steps.
+
+> [!TIP]
+> Check out the [Triage code scanning alerts in pull requests](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests) page to learn more about integration of code scanning into pull requests.
 
 
-<!-- If you would like to learn more about pull request integrations for code scanning, see "[Triage code scanning alerts in pull requests](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests)." -->
+<!-- > 💡 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). -->
diff --git a/.github/steps/3-step.md b/.github/steps/3-step.md
@@ -4,35 +4,20 @@ With our pull request changes now reviewed by CodeQL, let's take a moment to lea
 
 GitHub provides a dedicated **Security** tab for securely managing all security related issues. CodeQL saves alerts using the same standard as many other analysis tools with the results showing up under the **Code scanning** area.
 
-<img width="500" alt="image" src="https://github.com/user-attachments/assets/cf4fc6ec-e40e-4df6-8984-b6ec35341737" />
+<img width="600" alt="image" src="https://github.com/user-attachments/assets/cf4fc6ec-e40e-4df6-8984-b6ec35341737" />
 
 ### What information do alerts provide?
 
 The main area of an 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).
 
+<img width="600" alt="additional information" src="https://github.com/user-attachments/assets/9a5aaf3f-e063-4d07-8cdd-6272eec8a411"/>
 
-<img width="500" alt="additional information" src="https://github.com/user-attachments/assets/9a5aaf3f-e063-4d07-8cdd-6272eec8a411"/>
-
-<!-- > 💡 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). -->
-
-### What is 'CWE'
+### What is CWE?
 
 Many of the patterns CodeQL scans for come from existing databases of vulnerabilities.
 
 The 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
-
-1. In the top navigation, select the **Actions** tab.
-
-1. If needed, wait a moment for the CodeQL run to finish (about 4 minutes).
-
-1. Click on the **CodeQL Setup** workflow run entry to open a page showing more details.
-
-   <img width="500" alt="codeql setup" src="https://github.com/user-attachments/assets/016a729e-3b41-466c-8edf-3d4b41a86b7d"/>
-
-   > 💡 Tip: The workflow run contains additional CodeQL information such as the run duration, logs, and analysis artifacts.
-
 ### ⌨️ Activity: Review an Alert
 
 1. In the top navigation, select the **Security** tab.
@@ -45,15 +30,15 @@ The Common Weakness Enumeration (CWE) is a category system for hardware and soft
 
 1. Notice the description, related vulnerability information and a recommended solution.
 
-    <img width="500" alt="recommendations" src="https://github.com/user-attachments/assets/a5653b45-b66f-4e5b-8e03-a7b8cd3b91b4"/>
+<img width="500" alt="recommendations" src="https://github.com/user-attachments/assets/a5653b45-b66f-4e5b-8e03-a7b8cd3b91b4"/>
 
 1. (Optional) Click the **View source** link to view the CodeQL query that detected the alert.
 
 1. (Optional) Click the **Show more** link to view the full recommendation.
 
 1. Inspect the audit trail to see a secure history of the alert, including open/close information.
 
-    <img width="500" alt="audit trail" src="https://github.com/user-attachments/assets/25ec5256-20c7-4e9d-8160-ff40f3763872"/>
+<img width="500" alt="audit trail" src="https://github.com/user-attachments/assets/25ec5256-20c7-4e9d-8160-ff40f3763872"/>
 
 ### ⌨️ Activity: Dismiss and Reopen an Alert
 
@@ -69,3 +54,8 @@ The Common Weakness Enumeration (CWE) is a category system for hardware and soft
    - The alert state will change to `Open`.
    - An entry is added to the audit trail, which can't be removed or edited.
 
+1. With an alert closed and reopened, post a comment on this issue. Mona will check your progress and share the next steps.
+
+   ```md
+   Hey @professortocat, I've closed an reopened an alert. What is the next step?
+   ```
diff --git a/.github/steps/4-step.md b/.github/steps/4-step.md
@@ -1,36 +1,30 @@
-## Step 3: Fix Security Vulnerabilities
+## Step 4: 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 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.
+Let's fix the security vulnerability we introduced that CodeQL identified.
 
 ### ⌨️ Activity: Resolve an open alert
 
 1. In the top navigation, select the **Security** tab.
 
-1. In the left navigation, find the **Vulnerability alerts** area and select the **Code scanning** option. You should see two open alerts.
-
-   > 🪧 Note: If any of the alerts are `Closed`, go to the alert's page and choose **Reopen alert**.
+1. In the left navigation, find the **Vulnerability alerts** area and select the **Code scanning** option.
 
-1. Review the 2 open alerts and review the recommendations to decide changes to make.
+1. Review the open alert and review the recommended changes.
 
-1. In the top navigation, select the **Code** tab.
+1. In the top navigation, select the **Code** tab. Ensure you are on the branch for your pull request (`learning-codeql`).
 
 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"/>
+   <img width="500" alt="edit button" src="https://github.com/user-attachments/assets/19462cc5-a360-4dae-a97b-ecfd571aa403"/>
 
 1. Navigate to about **line 16** and modify it to the below.
 
    ```py
    "SELECT * FROM books WHERE name LIKE %s", name
    ```
 
-1. Above the editor in the top-right, click the **Commit changes...** button. Use the defaults options to commit the changes to `main`.
+1. Above the editor in the top-right, click the **Commit changes...** button. Use the defaults options to commit the changes to the `learning-codeql` branch.
 
    - CodeQL will now initiate a another scan.
 
@@ -41,15 +35,4 @@ If you expand the **More info** section at the bottom of the alert, there are ve
    - 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 CodeQL job finished, Mona will check your progress and share the next steps. -->
-
-1. With the pull request started, Mona will check your progress and share a final review. Nice work! You are done! 🥳
-
-
-
-
-<!-- 1. Navigate back to **Security** tab and **Code scanning alerts** area.
-
-1. Click the **1 Closed** text to switch to a view showing closed alerts.
-
-   <img width="500" alt="one closed alert" src="https://github.com/user-attachments/assets/b10005b6-9ef8-4d46-a160-4c9849d2c898"/> -->
+1. With the CodeQL scan finished, Mona will check your progress and share a final review. Nice work! You are done! 🥳
