CodeQL extension for Visual Studio Code

This project is an extension for Visual Studio Code that adds rich language support for CodeQL and allows you to easily find problems in codebases. In particular, the extension:

• Enables you to use CodeQL to query databases generated from source code.
• Shows the flow of data through the results of path queries, which is essential for triaging security results.
• Provides an easy way to run queries from the large, open source repository of CodeQL security queries.
• Adds IntelliSense to support you writing and editing your own CodeQL query and library files.

To see what has changed in the last few versions of the extension, see the Changelog.

You can also read full documentation for the extension on the GitHub documentation website.

Quick start overview

The information in this README file describes the quickest way to start using CodeQL. For information about other configurations, see "Using the advanced functionality of the CodeQL for VS Code extension" in the GitHub documentation.

Quick start: Installing and configuring the extension

1. Install the extension.
2. Check access to the CodeQL CLI.
3. Clone the CodeQL starter workspace.

Quick start: Using CodeQL

1. Import a database from GitHub.
2. Run a query.

Quick start: Installing and configuring the extension

Installing the extension

The CodeQL extension requires a minimum of Visual Studio Code 1.39. Older versions are not supported.

1. Install and open Visual Studio Code.
2. Open the Extensions view (press Ctrl+Shift+X or Cmd+Shift+X).
3. At the top of the Extensions view, type CodeQL in the box labeled Search Extensions in Marketplace.
4. Locate the CodeQL extension and select Install. This will install the extension from the Visual Studio Marketplace.

Checking access to the CodeQL CLI

The extension uses the CodeQL CLI to compile and run queries. The extension automatically manages access to the CLI for you by default (recommended). To check for updates to the CodeQL CLI, you can use the CodeQL: Check for CLI Updates command.

If you want to override the default behavior and use a CodeQL CLI that's already on your machine, see "Configuring access to the CodeQL CLI" in the GitHub documentation.

If you have any difficulty with CodeQL CLI access, see the CodeQL Extension Log in the Output view for any error messages.

Cloning the CodeQL starter workspace

When you're working with CodeQL, you need access to the standard CodeQL libraries and queries. Initially, we recommend that you clone and use the ready-to-use starter workspace. This includes libraries and queries for the main supported languages, with folders set up ready for your custom queries. After cloning the workspace (use git clone --recursive), you can use it in the same way as any other VS Code workspace—with the added advantage that you can easily update the CodeQL libraries.

For information about configuring an existing workspace for CodeQL, see "Setting up a CodeQL workspace" in the GitHub documentation.

Upgrading CodeQL standard libraries

You can easily keep up-to-date with the latest changes to the CodeQL standard libraries.

If you're using the CodeQL starter workspace, you can pull in the latest standard libraries by running:

git pull
git submodule update --recursive

in the starter workspace directory.

If you're using your own clone of the CodeQL standard libraries, you can do a git pull from where you have the libraries checked out.

Quick start: Using CodeQL

You can find all the commands contributed by the extension in the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) by typing CodeQL, many of them are also accessible through the interface, and via keyboard shortcuts.

Importing a database from GitHub

While you can use the CodeQL CLI to create your own databases, the simplest way to start is by downloading a database from GitHub.com.

1. Find a project that you're interested in on GitHub.com, for example Apache Kafka.
2. Copy the link to that project, for example https://github.com/apache/kafka.
3. In VS Code, open the Command Palette and choose the CodeQL: Download Database from GitHub command.
4. Paste the link you copied earlier.
5. Select the language for the database you want to download (only required if the project has databases for multiple languages).
6. Once the CodeQL database has been imported, it is displayed in the Databases view.

For more information, see "Managing CodeQL databases" in the GitHub documentation.

Running a query

The instructions below assume that you're using the CodeQL starter workspace, or that you've added the CodeQL libraries and queries repository to your workspace.

1. Expand the ql folder and locate a query to run. The standard queries are grouped by target language and then type, for example: ql/java/ql/src/Likely Bugs.
2. Open a query (.ql) file.
3. Right-click in the query window and select CodeQL: Run Query on Selected Database. Alternatively, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P), type Run Query, then select CodeQL: Run Query on Selected Database.

The CodeQL extension runs the query on the current database using the CLI and reports progress in the bottom right corner of the application. When the results are ready, they're displayed in the CodeQL Query Results view. Use the dropdown menu to choose between different forms of result output.

If there are any problems running a query, a notification is displayed in the bottom right corner of the application. In addition to the error message, the notification includes details of how to fix the problem.

Keyboard navigation

If you wish to navigate the query results from your keyboard, you can bind shortcuts to the CodeQL: Navigate Up/Down/Left/Right in Result Viewer commands.

What next?

We recommend reading the full documentation for the extension on the GitHub documentation website. You may also find the following resources useful:

• Create a database for a different codebase.
• Try out variant analysis.
• Learn more about CodeQL.
• Read how security researchers use CodeQL to find CVEs.

License

The CodeQL extension for Visual Studio Code is licensed under the MIT License. The version of CodeQL used by the CodeQL extension is subject to the GitHub CodeQL Terms & Conditions.

Data and Telemetry

If you specifically opt-in to permit GitHub to do so, GitHub will collect usage data and metrics for the purposes of helping the core developers to improve the CodeQL extension for VS Code. This data will not be shared with any parties outside of GitHub. IP addresses and installation IDs will be retained for a maximum of 30 days. Anonymous data will be retained for a maximum of 180 days. For more information, see "Telemetry in CodeQL for Visual Studio Code" in the GitHub documentation.