Fine-tune testing scope with CodeQL
Besides adding build instructions, which we covered in the last guide, excluding directories and changing the queries you run are the most common configuration changes users make. Changing queries is typically done to expand or narrow the scope of your testing. Typically, we see organizations exclude directories containing outside code that they can take little action to fix. We'll also hear from KPMG again.
In this guide, you will learn:
How to exclude files or folders from a CodeQL scan
How to change which queries run as part of a CodeQL scan
The differences between the three default query suites included with CodeQL
1. Exclude a directory from your scan.
Let's start by excluding test files from your Web Goat repository from the CodeQL scan.
Open the codeql.yml workflow file from the Web Goat repository’s /.github/ directory
Find the section labeled # Initializes the CodeQL tools for scanning.
Under languages: ${{ matrix.language }} add the following:
config: |
paths-ignore:
- '**/*.test.js'
We recommend keeping the number of folders you exclude to a minimum. It can be tempting to exclude folders containing third-party code, since there's not much we can do about issues there. But ultimately, it's better to know about potential vulnerabilities, even if you can't fix them directly. From our perspective you should be scanning as much as possible.
2. Change your query suite.
CodeQL runs queries to uncover potential security risks or quality issues. Here’s an example of a simple JavaScript CodeQL query that finds functions with more than 10 parameters:
import javascript
from Function f
where f.getNumParameter() > 10
select f
CodeQL query suites provide a way of selecting queries, based on metadata (e.g. their filename or location on disk/in a CodeQL pack). CodeQL packs are collections of compiled queries used to create, share, and run CodeQL queries and libraries. A query suite defines what queries are run as part of a CodeQL pack. For example, if you would like to modify the queries run and not modify the queries themselves, use a suite. If you have custom queries, data extensions, etc., then use a pack.
Let’s just use the default suites for now. CodeQL has three different built-in query suites that run a variety of different query packs: code-scanning (default), security-extended, and security-and-quality.
You should use the standard code scanning suite if you want only the most high-precision results and most high-severity vulnerabilities. If you're willing to sacrifice some precision to catch more vulnerabilities, including many lower severity issues, use security-extended. Use security-and-quality when you want to run everything from security-extended plus some quality queries that focus more on structure and maintainability.
Let’s enable security-and-quality now. Beneath the line you just added, add:
queries:
- uses: security-and-quality
You can specify other queries, query packs, and query suites the same way.
The whole section of the file should now look like this:
- name: Initialize CodeQL
uses: github/codeql-action/init@v2
with:
languages: ${{ matrix.language }}
config: |
paths-ignore:
- '**/*.test.js'
queries:
- uses: security-and-quality
3. Check the results.
After the CodeQL job completes, go to the repository's Security tab and select the Code scanning section of the menu on the left. You should now have even more results. As always, if the job fails, double check your spacing and indentation in the YAML file.
Up next: Extend your testing with third-party tools with GitHub code scanning
We've now covered the most common configuration changes you might want to make in CodeQL. There are many, many more configuration options available in the documentation. In the advanced module, we’ll work with an external config file that a security team can maintain. But for now, let's move on to our next guide.
Thus far we’ve only used code scanning to view results from CodeQL. But code scanning can display results from third-party tools as well, providing you with a single interface for working with a wide range of security tools.