Code scanning
Code scanning in GitHub Advanced Security for Azure DevOps lets you analyze the code in an Azure DevOps repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are raised as an alert. Code scanning uses CodeQL to identify vulnerabilities.
CodeQL is the code analysis engine developed by GitHub to automate security checks. You can analyze your code using CodeQL and display the results as code scanning alerts. For more specific documentation about CodeQL, see CodeQL documentation.
GitHub Advanced Security for Azure DevOps works with Azure Repos. If you want to use GitHub Advanced Security with GitHub repositories, see GitHub Advanced Security.
Additional configurations for code scanning
Language and query support
GitHub experts, security researchers, and community contributors write and maintain the default CodeQL queries used for code scanning. The queries are regularly updated to improve analysis and reduce any false positive results. The queries are open source, so you can view and contribute to the queries in the github/codeql repository.
CodeQL supports and uses the following language identifiers:
Language | Identifier | Optional alternative identifiers (if any) |
---|---|---|
C/C++ | c-cpp |
c or cpp |
C# | csharp |
|
Go | go |
|
Java/Kotlin | java-kotlin |
|
JavaScript/TypeScript | javascript |
|
Python | python |
|
Ruby | ruby |
|
Swift | swift |
Tip
- Use
c-cpp
to analyze code written in C, C++ or both. - Use
java-kotlin
to analyze code written in Java, Kotlin or both. - Use
javascript
to analyze code written in JavaScript, TypeScript or both.
For more information, see Supported languages and frameworks.
You can view the specific queries and task details executed by CodeQL in the build log.
Code scanning build mode customization
Code scanning supports two build modes when setting up a pipeline for scanning:
none
- the CodeQL database is created directly from the codebase without building the codebase (supported for all interpreted languages, and additionally supported for C# and Java).manual
- you define the build steps to use for the codebase in the workflow (supported for all compiled languages).
For more information on the different build modes including a comparison on the benefits of each build mode, see CodeQL code scanning for compiled languages.
For running code scanning analysis through GitHub Advanced Security for Azure DevOps, the autobuild
build mode is instead a separate build task, AdvancedSecurity-CodeQL-Autobuild@1
.
Tip
Build mode none
is useable in conjunction with other interpreted languages (e.g., JavaScript, Python, Ruby).
If build mode none
is specified for C# or Java in conjunction with other compiled languages that do not support build mode none
, the pipeline task will fail.
Here is an example of a valid configuration with multiple languages and none
build mode:
trigger: none
pool:
vmImage: windows-latest
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
# build mode `none` is supported for C# and Java, and JavaScript is an interpreted language
# and build mode `none` has no impact on JavaScript analysis
languages: 'csharp, java, javascript'
buildtype: 'none'
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
Here is an example of an invalid configuration with multiple languages and none
build mode:
trigger: none
pool:
vmImage: windows-latest
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
# build mode `none` is supported for C# but build mode `none` is NOT supported for Swift
# so this pipeline definition will result in a failed run
languages: 'csharp, swift'
buildtype: 'none'
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
Using custom queries with CodeQL
By default, if you do not have a custom configuration file specified in your pipeline setup, CodeQL runs the security-extended
query pack to analyze your code. You can utilize custom CodeQL queries to write your own queries to find specific vulnerabilities and errors. You also need to create a custom configuration file to modify CodeQL's default analysis.
To find existing custom queries or to contribute your own custom query, see Contributing to CodeQL.
Analysis with custom queries
The quickest way to start with a custom query is to write a query and save it in your local Azure DevOps repository. You can customize the details of a custom query according to your need, but it must have at least a rule ID. For more information about how to write your own CodeQL query, see Writing CodeQL queries. You can also bundle multiple queries together into a query suite, or utilize packs published by other people. For more information, see Publishing and using CodeQL packs.
Using a custom configuration file
A custom configuration file is a way to manage what queries are run during CodeQL's analysis against your code. You can specify more queries or query packs to be run, and change or disable the default CodeQL queries.
To include a specific query you want to include, specify the query with a name and path to the location of the query file (.ql) in your repository.
To include a specific pack you want to include, specify the pack name. You can specify any number of CodeQL query packs to run in your configuration file.
The next step is to create a qlpack.yml
file. This file declares the CodeQL pack and information about it. Any *.ql
files in the same directory (or sub-directory) as a qlpack.yml
are considered part of the package.
Tip
The packs
filter from the configuration file support downloading packs from repositories hosted in GitHub, although the queries
filter does not.
If the pack is private in GitHub, then you need to provide a GitHub access token via the AdvancedSecurity-Codeql-Init@1
task as an environment variable and variable name as GITHUB_TOKEN
, with the scope of the token being read:packages
.
Here is an example configuration file:
name: "Run custom queries"
# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
- name: Use security-extended query suite
uses: security-extended
- name: Use local custom query (single query)
uses: ./customQueries/javascript/FindTestFunctions.ql
- name: Use local custom query (directory of queries)
uses: ./customQueries/javascript/MemoryLeakQueries
packs:
- mygithuborg/mypackname
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
query-filters:
- include:
kind: problem
- include:
precision: medium
- exclude:
id:
- js/angular/disabling-sce
- js/angular/insecure-url-allowlist
Tip
Configuration file specifications ignore and take precedence over pipeline-level configurations for the AdvancedSecurity-Codeql-Init@1
task.
includepaths
/ ignorepaths
will be ignored or, if paths
/paths-ignore
are present, overwritten with values from paths
/paths-ignore
.
querysuite
will be overwritten with values specified in queries
or packs
in the configuration file.
If you are using any custom query, here is an example qlpack.yml
placed in the directory of your custom queries:
version: 1.0.1
dependencies:
codeql/javascript-all: "*"
codeql/javascript-queries: "*"
The dependencies
variable contains all of the dependencies of this package and their compatible version ranges. Each dependency is referenced as the scope/name
of a CodeQL library pack. When defining dependencies
, your qlpack.yml
depends on exactly one of the core language packs (for example, JavaScript, C#, Ruby, etc.), which determines the language your query can analyze.
For more specific advice and configuration options with your configuration file, see Customizing your advanced setup for code scanning or for qlpack.yml
setup, see CodeQL pack structure.
Once you have your configuration file, you then need to customize your pipeline running CodeQL analysis to utilize your new file. Here is a sample pipeline pointing to a configuration file:
trigger: none
pool:
vmImage: windows-latest
# You can either specify your CodeQL variables in a variable block...
variables:
# `configfilepath` must be an absolute file path relative to the repository root
advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# Or you can specify variables as variables for the task. You do not need both definitions.
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
languages: 'javascript'
loglevel: '2'
configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
env:
GITHUB_TOKEN: $(githubtoken)
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
Code scanning alerts
GitHub Advanced Security for Azure DevOps code scanning alerts include code scanning flags by repository that alert of code-level application vulnerabilities.
To use code scanning, you need to first configure GitHub Advanced Security for Azure DevOps.
The Advanced Security tab under Repos in Azure DevOps is the hub to view your code scanning alerts. Select the Code scanning tab to view scanning alerts. You can filter by branch, state, pipeline, rule type, and severity. At this time, the alerts hub doesn't display alerts for scanning completed on PR branches.
There's no effect to results if pipelines or branches are renamed - it may take up to 24 hours before the new name is displayed.
If you choose to run custom CodeQL queries, there isn't by default a separate filter for alerts generated from different query packs. You can filter by rule, which is distinct for each query.
If you turn off Advanced Security for your repository, you lose access to the results in the Advanced Security tab and build task. The build task does not fail, but any results from builds run with the task while Advanced Security is disabled are hidden and not retained.
Alert details
Select an alert for more details, including remediation guidance. Each alert includes a location, description, example, and severity.
Section | Explanation |
---|---|
Location | The Locations section details a specific instance where CodeQL detected a vulnerability. If there are multiple instances of your code violating the same rule, a new alert is generated for each distinct location. The Locations card contains a direct link to the affected code snippet so you can select the snippet to be directed to the Azure DevOps web UI for editing. |
Description | The description is provided by the CodeQL tool based off of the problem. |
Recommendation | The recommendation is the suggested fix for a given code scanning alert. |
Example | The example section shows a simplified example of the identified weakness in your code. |
Severity | Severity levels can be low, medium, high, or critical. The severity score is based off of the given Common Vulnerability Scoring System (CVSS) score for the identified Common Weakness Enumeration (CWE). Learn more about how severity is scored at this GitHub blog post. |
Manage code scanning alerts
Viewing alerts for a repository
Anyone with contributor permissions for a repository can view a summary of all alerts for a repository in the Advanced Security tab under Repos. Select the Code scanning tab to view all secret scanning alerts.
To display results, code scanning tasks need to run first. Once the first scan finishes, any detected vulnerabilities are displayed in the Advanced Security tab.
By default, the alerts page shows dependency scanning results for the default branch of the repository.
The status of a given alert reflects the state for the default branch and latest run pipeline, even if the alert exists on other branches and pipelines.
Dismissing code scanning alerts
To dismiss alerts, you need appropriate permissions. By default, only project administrators can dismiss Advanced Security alerts.
To dismiss an alert:
- Navigate to the alert you wish to close and select on the alert.
- Select the Close alert drop-down.
- If not already selected, select either Risk accepted or False positive as the closure reason.
- Add an optional comment into the Comment text box.
- Select Close to submit and close the alert.
- The alert state changes from Open to Closed and your dismissal reason displays.
This action only dismisses the alert for your selected branch. Other branches that contain the same vulnerability stay active until dismissed. Any alert previously dismissed can be manually reopened.
Troubleshooting code scanning
Generally, if you are encountering errors with CodeQL execution, the CodeQL CLI reports the status of each command it runs as an exit code. The exit code provides information for subsequent commands or for other tools that rely on the CodeQL CLI. For more information on exit code details, see Exit codes.
Error: 'database finalize' CodeQL command (32)
This error indicates a problem with finalizing the CodeQL database creation, potentially due to extraction errors or missing build steps.
Troubleshooting steps:
- Verify code exists and is compiled
- For compiled languages, verify that the build process is compiling code and is happening between the
AdvancedSecurity-Codeql-Init
and theAdvancedSecurity-Codeql-Analyze
tasks. Common build commands and required flags (such as clean no-cache/no-daemon) can be found here at Specifying build commands. - For interpreted languages, confirm that there is some source code for the specified language in the project.
- For compiled languages, verify that the build process is compiling code and is happening between the
- Check extraction errors
- Verify if extraction errors affect the CodeQL database's health.
- Review the log file for extraction errors and warnings to assess overall database health.
- Investigate overwhelming errors
- If most files encounter extractor errors, investigate further to understand the root cause of improper extraction.
Error: autobuild script (1)
This error describes an automatic build failure, suggesting an issue with code scanning setup or configuration.
Troubleshooting steps:
- Configure build steps
- Remove the AutoBuild step and instead configure specific build steps for compiled languages in your pipelines.
- Refer to setup guidelines provided in Configure GitHub Advanced Security for Azure DevOps.
Error: CodeQL directories not found in agent tool cache
This error indicates an issue with installing CodeQL for self-hosted agents.
Troubleshooting steps:
- Refer to setup guidelines or configuration scripts provided in Configure GitHub Advanced Security for Azure DevOps.
Error: language pipeline variable not set
This error occurs when attempting to run CodeQL without setting the pipeline variable specifying which languages to scan.
Troubleshooting steps:
- Set language pipeline variable
- Ensure the language pipeline variable is correctly configured. Refer to setup guidelines provided in Configure GitHub Advanced Security for Azure DevOps.
- Supported languages include
csharp
,cpp
,go
,java
,javascript
,python
,ruby
, andswift
.
CodeQL returning no results
This section provides guidance for situations where CodeQL analysis yields no results.
Troubleshooting steps:
- Check for detected vulnerabilities
- Consider the possibility that your code may genuinely have no vulnerabilities. If vulnerabilities are expected but not detected, proceed to verify further.
- Review query suite configuration
- Confirm the query suite being used and consider switching to a more comprehensive suite if necessary.
- Alternatively, custom query suites can be created for tailored analysis.
- Adjust permissions for viewing results
- Ensure proper permissions, at least at the contributor level, are granted to access analysis results. For more information, see Advanced Security permissions.
CodeQL timing out
If the AdvancedSecurity-Codeql-Analyze@1
task is displaying This job was abandoned ... we lost contact with the agent
and you are using a hosted Microsoft agent, the task is hitting the built-in six-hour timeout for paid hosted agents. You may attempt to run analysis on a self-hosted agent instead.
Code scanning task permissions
The code scanning build task uses the pipeline identity to call the Advanced Security REST APIs. By default, pipelines in the same project have access to upload the SARIF file generated by running CodeQL analysis. If these permissions are removed from the build service account or if you have a custom setup (for example, a pipeline hosted in a different project than the repository), you must grant these permissions manually.
Troubleshooting steps:
- Grant
Advanced Security: View alerts
andAdvanced Security: Manage and dismiss alerts
permission to the build service account used in your pipeline, which for project-scoped pipelines is[Project Name] Build Service ([Organization Name])
, and for collection-scoped pipelines isProject Collection Build Service ([Organization Name])
.
Manual installation of CodeQL bundle to self-hosted agent
Install the CodeQL bundle to the agent tool cache by utilizing the setup script for your architecture, available on GitHub. These scripts require the
$AGENT_TOOLSDIRECTORY
environment variable to be set to the location of the agent tools directory on the agent, e.g. C:/agent/_work/_tool
. Alternatively, you may manually implement the following steps:
- Pick the latest CodeQL release bundle from GitHub.
- Download and unzip the bundle to the following directory inside the agent tool directory, typically located under
_work/_tool
:./CodeQL/0.0.0-[codeql-release-bundle-tag]/x64/
. Using the current release ofv2.16.0
, the folder name would be titled./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64/
. Learn more about the agent tool directory. - Create an empty file titled
x64.complete
within the./CodeQL/0.0.0-[codeql-release-bundle-tag]
folder. Using the previous example, the end file path to yourx64.complete
file should be./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64.complete
.