codeql-lab

codeql-lab is a consolidated Git repository that collects all relevant CodeQL components, resources, and tooling into a single version-controlled location.

Purpose

The goal of this repository is to provide an integrated development environment (“lab”) for CodeQL research, experimentation, and custom query development. It simplifies setup by maintaining all required submodules, configuration files, and datasets in one place.

Repository Location

The primary repository is hosted at: https://github.com/hohn/codeql-lab

Intended Use Cases

Local experimentation with CodeQL queries and libraries.
End-to-end testing of custom model data and query logic. This includes writing and validating custom data flow models, adjusting model coverage, and confirming that query results behave as expected across controlled datasets. The lab setup supports rapid iteration on QL logic, helping detect unintended changes and enabling reproducible evaluations of taint tracking, control flow, or API usage patterns.
Structured collaboration and controlled updates across all CodeQL-related artifacts.
Simplified onboarding and reproducible setup for new contributors or analysis environments.

Prerequisites

Working with this repository assumes prior experience with:

Git, Bash, and standard Unix command-line tools. These are used throughout and are required for setup and day-to-day tasks. Tools such as ripgrep, GNU Bash, and grep/regex workflows are assumed.
At least one supported programming language, such as C, C++, Java, Python, Go, or Ruby. A solid understanding of the target language is necessary to interpret analysis results and write effective queries. See general background on programming languages if needed.
Basic familiarity with program structure concepts, including abstract syntax trees (ASTs), control-flow graphs (CFGs), and data-flow graphs (DFGs). These are core to how CodeQL models code behavior.
Optional but helpful: familiarity with structural or functional programming languages (e.g. Lisp or OCaml) can make working with CodeQL’s query language and type system more intuitive. See overview of functional programming for related context.

Repository Layout

Core Structure

Repository is based on: https://github.com/github/vscode-codeql-starter.git
All development work is done on the branch: qllab

CodeQL version is pinned via the ql/ submodule:

commit 4d681f05bd671f8b5e31624f16a2b4d75e61c071 (tag: codeql-cli/v2.22.0)

A prebuilt CodeQL CLI binary is included:
```
1104625939  assets/codeql-osx64.zip
```
Project-specific repositories can be added directly under the root. Example: the C dataflow workshop in ./codeql-dataflow-sql-injection

Additional Structure Notes

The original upstream README.md is preserved at ./README-vscode-codeql-starter.md

Possible Reading Orders

Data Flow

Debugging data flow config (instead of taint flow), Java

We can illustrate taint-flow debugging in the Java SQL injection sample

Debugging data flow config (instead of taint flow), C

Modeling

Review: SQLite Injection Workshop, Java

Recap the Java-based injection example.

Customizations via codeql, java

codeql-dataflow-sql-injection/README.org, supplement codeql: Add to FlowSource or a subclass
TODO raw md from staging: codeql-dataflow-sql-injection/incoming.codeql-customizations-workshop.md

Model Editor: Simplest Case, Java

Extend the Java example using the model editor.
Explain how "models-as-data" works under the hood.
customizations using models-as-data, via model editor
- editor as illustration tool
customizations using models-as-data, via text
- continue with codeql-dataflow-sql-injection
- supplement codeql: Add to models-as-data

Jedis Example: Scale Demonstration, Java

Use Jedis (Java Redis client) to show modeling at scale.
Emphasize quantity; CodeQL logic is unchanged from #2.

TODO Review: SQLite Injection Workshop (C)

C++ version of the workshop.

TODO (Optional) Extending Queries with Customizations.qll

Supported in most languages, but not C++ by default.
Can be enabled by building a custom CodeQL bundle.
Use this CLI tool: https://github.com/advanced-security/codeql-bundle
USE language in name
Demonstrate using `codeql-lab`.
- in ./codeql-sqlite/README.org
- ql/cpp/ql/lib/semmle/code/cpp/security/FlowSources.qll
```
  abstract class FlowSource extends DataFlow::Node
```
- The other languages include Customizations.qll via <language.qll>, e.g., ql/python/ql/lib/python.qll
  1. Modify
```
ql/python/ql/lib/python.qll
```
  2. Add
```
ql/python/ql/lib/Customizations.qll
```
- For C/C++,
  1. Modify
```
ql/cpp/ql/lib/cpp.qll
```
  2. Add
```
ql/cpp/ql/lib/Customizations.qll
```

TODO Use models-as-data QL code directly (no graphical editor).

The model definition files exist
Data files exist
There is no editor
Generate YAML manually.
customizations using models-as-data, via text
- continue with codeql-dataflow-sql-injection
- The ./ql/cpp/ql/src/Security/CWE/CWE-089/SqlTainted.ql query works out of the box
- Add char* get_user_info() as extra source for illustration

TODO codeql-bundling

Tool Setup

Some scripts are used here, found in ./bin/. To ensure the ones written in Python have access to prerequites, set up a virtual environment via

  # 1. Create the virtualenv
  python3 -m venv ~/codeql-lab/venv

  # 2. Install any packages
  source ~/codeql-lab/venv/bin/activate
  pip install pyyaml

For any of these scripts to work, add them to the PATH via

  export PATH="$HOME/codeql-lab/bin:$PATH"

Languages

CodeQL 46.8%

Shell 28.9%

C 10.9%

Python 7.3%

Java 6.1%

README.org Unescape Escape

codeql-lab: Centralized Git Repository for CodeQL Development

Overview