Master CodeQL: From Setup to Advanced Vulnerability Queries

1. CodeQL Introduction

CodeQL is a code‑analysis tool for vulnerability discovery. It originated from SemmleQL, was acquired by GitHub in 2019, and is now offered as CodeQL. Security researchers write queries in CodeQL language to locate code patterns matching known vulnerabilities, greatly improving audit efficiency. The project has earned over 5,000 stars on GitHub, and GitHub Security Lab runs a bounty program for high‑quality rules.

Supported languages include C/C++, C#, Go, Java, JavaScript, Python, Ruby, etc. This article focuses on writing CodeQL rules for C/C++.

2. CodeQL Environment Setup

2.1 Install Visual Studio Code and CodeQL extension

Download and install Visual Studio Code from the official website, then open the Extensions view, search for "codeql", and install the CodeQL extension.

2.2 Install the codeql‑cli parsing engine

The codeql‑cli generates a database from the target source code. While it can be installed on Windows or Linux, this guide uses the Linux installation for C/C++ projects.

Download the Linux version of codeql‑cli, extract it, and add the codeql executable to your PATH (e.g., by linking it to /usr/local/bin).

3. Source Code Database Generation

CodeQL works by querying a database that contains the abstract syntax tree (AST) of the compiled source code.

Example: create a vulnerable C file hello.c and generate a database with the following command:

codeql database create ./hello-db --language=cpp -c "gcc hello.c -o hello"

Use codeql database create --help to see all options.

The generated hello-db folder contains src.zip (compiled sources), a log directory (generation logs), and a db-cpp directory required by the VS Code extension.

For large projects such as AOSP’s Bluetooth module, set necessary environment variables, clean previous build output, locate the module’s Android.bp, and run a similar codeql database create command.

codeql database create -l cpp -c "/home/ailei/android_source/build/soong/soong_ui.bash --make-mode libbt-stack" --source-root=/home/ailei/android_source/system/bt/ --working-dir=/home/ailei/android_source --overwrite ./android-bt-db

4. CodeQL Rule Syntax Introduction

4.1 Basic Syntax

A simple rule to find a variable named buf consists of four parts: import, from, where, and select. import cpp – imports the C/C++ library. from Variable a – selects variables. where a.getName().matches(".*buf.*") – filters by name. select a.getName() – outputs the variable name.

Run the query via the VS Code command “CodeQL: Run Queries in Selected Files”.

4.2 Advanced Syntax

Examples from the vscode-codeql-starter repository demonstrate overflow‑buffer detection ( OverflowBuffer.ql) and taint tracking.

Key constructs include importing the taint‑tracking library ( import semmle.code.cpp.dataflow.TaintTracking), defining a Config class with isSource and isSink, and using predicates such as getSize() and accessSize to model buffer accesses.

Running these queries yields results that pinpoint the exact source locations of potential vulnerabilities.

Summary

CodeQL enables rapid, query‑driven vulnerability discovery across large codebases. By mastering environment setup, database generation, and rule authoring—from basic imports to advanced taint‑tracking—security engineers can build reusable query libraries, accelerate bug hunting, and contribute to a growing ecosystem of open‑source security rules.