Security table of contents.
Advanced CodeQL setup
When you enable CodeQL, you have the option to select either the "Default" or "Advanced" setup. Although we recommend using the Default setup whenever possible, there are use cases in which you will need to use advanced setup. Most commonly, you might need to specify a custom build process, add or remove queries, or exclude directories from a scan. Here's why KPMG decided to use the Advanced Setup:
In addition to needing external dependencies for our builds, we enabled advanced setup at KPMG becausewe saw the benefit of using CodeQL not just for security, but for code quality as well. Pull request reviews are great, but can only get you so far. We use several automated linting and code quality tools, but we've found that no tool catches everything. GitHub's security-and-quality query pack helps us catch things we wouldn't catch otherwise. We’ve also written a few custom queries to promote our own standards and style by alerting developers when they commit code, instead of asking them to make changes at some arbitrary time in the future.We've seen a big improvement in code quality already.
GitHub will try to automatically build applications as part of a CodeQL scan, but the autobuilder action won’t always be able to successfully build every application. Web Goat, for instance, requires a custom build to call Maven.
We'll start by adding custom build instructions for Web Goat in this guide, and move on to changing our CodeQL queries and excluding directories in the next step.
In this guide, you will learn:
When to use CodeQL advanced setup instead of the default setup
How to edit a CodeQL configuration file
How to set custom build instructions for CodeQL
1. Add custom build instructions to CodeQL with advanced setup.
CodeQL is typically run and managed through GitHub Actions using the CodeQL action. Just as you would with any other action, CodeQL advanced setup is called and managed with a workflow file written in YAML. When you use the Default configuration, this YAML file is hidden from you and managed behind the scenes. For an advanced setup, we will need to create our own workflow file.
Fork the Web Goat repository into an organization with GHAS enabled if you haven’t already. If you haven’t already enabled GitHub Actions for the repository, click Settings under your repository name. If you cannot see theActions tab, select the “...” dropdown menu, then clickActions. Click the button that saysI understand my workflows, go ahead and enable them.
Go to your Web Goat repository's Settings tab.
On the sidebar, under Settings, selectCode security and analysis.
If you haven't enabled CodeQL previously, find the Code scanning heading and select theSet up drop down. You'll see a choice betweenDefault orAdvanced. SelectAdvanced.
If you already enabled CodeQL with the default settings, select the menu labeled "...", then selectSwitch to advanced. SelectDisable CodeQL when prompted. Don’t worry, we will re-enable it after we’ve completed the advanced setup process.
After selecting or switching to advanced, you'll be taken to a GitHub Actions workflow file namedcodeql.yml. You can find it in your Web Goat repository’s/.github/workflows directory. This is the file we use to run and configure CodeQL.
The following lines towards the end of thecodeql.yml file run the autobuilder:
# Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift). # If this step fails, then you should remove it and run the build manually (see below) -name:Autobuild uses:github/codeql-action/autobuild@v2Remove them and replace them with the following:
-if:matrix.language=='java' name:Setupjava17 uses:actions/setup-java@v3 with: distribution:'temurin' java-version:17 architecture:x64 -if:matrix.language=='java' name:BuildwithMaven run:mvn-Bpackage--filepom.xmlThis simple workflow will try to build the application with Maven, instead of the autobuilder.
Commit this to the main branch.
2. Check the results.
Now open the repository's Actions tab. There should be two CodeQL analysis jobs running, one for Java and one for JavaScript. Both should work this time.
When the job is complete, go to the repository's Security tab and select theCode scanning section of the menu on the left.
On the top of this page, there should be a status notification to let you know that CodeQL is working.
We should now see more results than we did before because we will have Java vulnerabilities in addition to the JavaScript vulnerabilities displayed last time. You can see more information by selecting theTool status. If the Java job failed, be sure to double check your indentation and spacing.
Up Next:Fine-tune testing scope with CodeQL
Now that we have an advanced setup to work with, let’s tackle the other two most common advanced CodeQL configuration tasks:changing the queries we run and excluding directories.