|
| 1 | +--- |
| 2 | +title: DevOps with .NET and GitHub Actions - Secure code with CodeQL |
| 3 | +description: Add security scanning to your .NET code with GitHub Actions and CodeQL |
| 4 | +author: colindembovsky |
| 5 | +ms.date: 03/04/2021 |
| 6 | +--- |
| 7 | + |
| 8 | +# Secure .NET Code with CodeQL and GitHub Actions |
| 9 | + |
| 10 | +[CodeQL](https://codeql.github.com/docs/codeql-overview/about-codeql/) is a static code analysis engine that can automate security and quality checks. With CodeQL, you can perform _variant analysis_, which uses known vulnerabilities as seeds to find similar issues. CodeQL is part of [GitHub Advanced Security](https://docs.github.com/github/getting-started-with-github/about-github-advanced-security) that includes: |
| 11 | + |
| 12 | +> [!div class="checklist"] |
| 13 | +
|
| 14 | +> * Code scanning - find potential security vulnerabilities in your code. |
| 15 | +> * Secret scanning - detect secrets and tokens that are committed. |
| 16 | +> * Dependency scanning - detect vulnerabilities in packages that you consume. |
| 17 | +
|
| 18 | +CodeQL [supports some of the most popular programming languages and compilers](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/): |
| 19 | + |
| 20 | +- C/C++ |
| 21 | +- Java |
| 22 | +- C# |
| 23 | +- Python |
| 24 | +- Go |
| 25 | +- JavaScript |
| 26 | +- TypeScript |
| 27 | + |
| 28 | +CodeQL is a powerful language and security professionals can create custom queries using CodeQL. However, teams can benefit immensely from the large open-source collection of queries that the security community has created without having to write any custom CodeQL. |
| 29 | + |
| 30 | +In this article, you'll set up a GitHub workflow that will scan code in your repository using CodeQL. You will: |
| 31 | + |
| 32 | +> [!div class="checklist"] |
| 33 | +
|
| 34 | +> * Create a code scanning action. |
| 35 | +> * Edit the workflow file to include custom scan settings. |
| 36 | +> * See scanning results. |
| 37 | +
|
| 38 | +> [!NOTE] |
| 39 | +> To see security alerts for your repository, you must be a repository owner. |
| 40 | +
|
| 41 | +## Create the code scanning workflow |
| 42 | + |
| 43 | +You can use a starter workflow for code scanning by navigating to the **Security** tab of your repository. |
| 44 | + |
| 45 | +1. Navigate to your GitHub repository and select the **Security** > **Code Scanning Alerts**. The top recommended workflow should be CodeQL Analysis. Select **Set up this workflow**. |
| 46 | + |
| 47 | +  |
| 48 | + **Figure 1:** Create a new code scanning workflow. |
| 49 | + |
| 50 | +1. A new workflow file is created in your `.github/workflows` folder. |
| 51 | +1. Select **Start Commit** on the upper right to save the default workflow. You can commit to the `main` branch. |
| 52 | + |
| 53 | +  |
| 54 | + **Figure 2:** Commit the file. |
| 55 | + |
| 56 | +1. Select the **Actions** tab. In the left-hand tree, you'll see a **CodeQL** node. Select this node to filter for CodeQL workflow runs. |
| 57 | + |
| 58 | +  |
| 59 | + **Figure 3:** View the CodeQL workflow runs. |
| 60 | + |
| 61 | +Take a look at the workflow file while it runs. If you remove the comments from the file, you'll see the following YAML: |
| 62 | + |
| 63 | +```yml |
| 64 | +name: "CodeQL" |
| 65 | + |
| 66 | +on: |
| 67 | + push: |
| 68 | + branches: [ main ] |
| 69 | + pull_request: |
| 70 | + branches: [ main ] |
| 71 | + schedule: |
| 72 | + - cron: '40 14 * * 6' |
| 73 | + |
| 74 | +jobs: |
| 75 | + analyze: |
| 76 | + name: Analyze |
| 77 | + runs-on: ubuntu-latest |
| 78 | + |
| 79 | + strategy: |
| 80 | + fail-fast: false |
| 81 | + matrix: |
| 82 | + language: [ 'csharp' ] |
| 83 | + |
| 84 | + steps: |
| 85 | + - name: Checkout repository |
| 86 | + uses: actions/checkout@v2 |
| 87 | + |
| 88 | + - name: Initialize CodeQL |
| 89 | + uses: github/codeql-action/init@v1 |
| 90 | + with: |
| 91 | + languages: ${{ matrix.language }} |
| 92 | + |
| 93 | + - name: Autobuild |
| 94 | + uses: github/codeql-action/autobuild@v1 |
| 95 | + |
| 96 | + - name: Perform CodeQL Analysis |
| 97 | + uses: github/codeql-action/analyze@v1 |
| 98 | +``` |
| 99 | +
|
| 100 | +Notice the following things: |
| 101 | +
|
| 102 | +1. The workflow `name` is `CodeQL`. |
| 103 | +1. This workflow triggers on `push` and `pull_request` events to the `main` branch. There's also a `cron` trigger. The `cron` trigger lets you define a schedule for triggering this workflow and is randomly generated for you. In this case, this workflow will run at 14:40 UTC every Saturday. |
| 104 | + |
| 105 | + > [!TIP] |
| 106 | + > If you edit the workflow file and hover over the cron expression, a tooltip will show you the English text for the cron expression. |
| 107 | + |
| 108 | +1. There's a single job called `analyze` that runs on the `ubuntu-latest` hosted agent. |
| 109 | +1. This workflow defines a `strategy` with a `matrix` on the array of `language`. In this case, there's only `csharp`. If the repository contained other languages, you could add them to this array. This causes the job to "fan out" and create an instance per value of the matrix. |
| 110 | +1. There are four steps, starting with `checkout`. |
| 111 | +1. The second step initializes the CodeQL scanner for the `language` this job is going to scan. CodeQL intercepts calls to the compiler to build a database of the code while the code is being built. |
| 112 | +1. The `Autobuild` step will attempt to automatically build the source code using common conventions. If this step fails, you can replace it with your own custom build steps. |
| 113 | +1. After building, the CodeQL analysis is performed, where suites of queries are run against the code database. |
| 114 | +1. The run should complete successfully. However, there appear to be no issues. |
| 115 | + |
| 116 | +  |
| 117 | + **Figure 4:** No results to the initial scan. |
| 118 | + |
| 119 | +## Customize CodeQL settings |
| 120 | + |
| 121 | +The CodeQL scan isn't reporting any security issues. That's expected with this basic sample. CodeQL can also scan for _quality_ issues. The current workflow is using the default `security-extended` suite. You can add quality scanning in by adding a configuration file to customize the scanning suites. In this step, you'll configure CodeQL to use the `security-and-quality` suites. |
| 122 | + |
| 123 | +> [!INFORMATION] |
| 124 | +> For other CodeQL configuration options, see [this article](https://docs.github.com/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-codeql-code-scanning-in-your-ci-system). |
| 125 | + |
| 126 | +1. Navigate to the `.github` folder in the **Code** tab and select **Add File**: |
| 127 | + |
| 128 | +  |
| 129 | + **Figure 5:** Create a new file. |
| 130 | + |
| 131 | +1. Enter `codeql/codeql-config.yml` as the name. This creates the file in a folder. Paste in the following code: |
| 132 | + |
| 133 | + ```yml |
| 134 | + name: "Security and Quality" |
| 135 | +
|
| 136 | + queries: |
| 137 | + - uses: security-and-quality |
| 138 | + ``` |
| 139 | + |
| 140 | +  |
| 141 | + **Figure 6:** Create the CodeQL configuration file. |
| 142 | + |
| 143 | +1. Select **Commit to main** at bottom of the editor to commit the file. |
| 144 | +1. Edit the CodeQL workflow to use the new configuration file. Navigate to `.github/workflows/codeql-analysis.yml` and select the pencil icon. Add a new property to the `with` section as shown below: |
| 145 | + |
| 146 | + ```yml |
| 147 | + - name: Initialize CodeQL |
| 148 | + uses: github/codeql-action/init@v1 |
| 149 | + with: |
| 150 | + languages: ${{ matrix.language }} |
| 151 | + config-file: ./.github/codeql/codeql-config.yml # <-- add this line |
| 152 | + ``` |
| 153 | + |
| 154 | +1. Select **Start Commit** and commit to the `main` branch. |
| 155 | + |
| 156 | +## Review the security alerts |
| 157 | + |
| 158 | +> [!IMPORTANT] |
| 159 | +> You must be a repository owner to view security alerts. |
| 160 | +> |
| 161 | +> This sample repository is small. As such, it doesn't contain any major security or quality issues. However, "real world" repositories will likely have some issues. |
| 162 | + |
| 163 | +When the last CodeQL workflow run completes, you should see two issues in the **Security** tab: |
| 164 | + |
| 165 | + |
| 166 | +**Figure 7:** View security alerts. |
| 167 | + |
| 168 | +1. Select the first alert to open it. |
| 169 | +1. In this case, the alert is for a generated file that isn't committed to the repository. For that reason, the preview is unavailable. |
| 170 | +1. Notice the tags that are applied. These tags can be used for filtering issues. |
| 171 | +1. Select **Show more** under the rule information to show help and recommendations. |
| 172 | + |
| 173 | +  |
| 174 | + **Figure 8:** Open an alert. |
| 175 | + |
| 176 | +1. Selecting **Dismiss** will open options for dismissing this issue: |
| 177 | + |
| 178 | +  |
| 179 | + **Figure 9:** Dismiss an alert. |
| 180 | + |
| 181 | +>[!div class="step-by-step"] |
| 182 | +>[Previous](actions-deploy.md) |
0 commit comments