mirror of
https://github.com/hohn/codeql-lab.git
synced 2025-12-16 18:03:08 +01:00
86 lines
4.0 KiB
Org Mode
86 lines
4.0 KiB
Org Mode
* codeql-lab: Centralized Git Repository for CodeQL Development
|
||
|
||
** Overview
|
||
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 [[https://man.archlinux.org/man/rg.1][ripgrep]], [[https://www.gnu.org/software/bash/][GNU Bash]], and [[https://en.wikipedia.org/wiki/Grep][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 [[https://en.wikipedia.org/wiki/Programming_language][programming languages]] if needed.
|
||
|
||
- *Basic familiarity with program structure concepts*, including
|
||
[[https://en.wikipedia.org/wiki/Abstract_syntax_tree][abstract syntax trees (ASTs)]], [[https://en.wikipedia.org/wiki/Control-flow_graph][control-flow graphs (CFGs)]], and
|
||
[[https://en.wikipedia.org/wiki/Data-flow_analysis][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. [[https://en.wikipedia.org/wiki/Lisp_(programming_language)][Lisp]] or [[https://en.wikipedia.org/wiki/OCaml][OCaml]]) can make working with
|
||
CodeQL’s query language and type system more intuitive.
|
||
See overview of [[https://en.wikipedia.org/wiki/Functional_programming][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]]
|
||
|
||
* 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
|
||
#+BEGIN_SRC sh
|
||
# 1. Create the virtualenv
|
||
python3 -m venv ~/codeql-lab/venv
|
||
|
||
# 2. Install any packages
|
||
source ~/codeql-lab/venv/bin/activate
|
||
pip install pyyaml
|
||
#+END_SRC
|
||
|
||
For any of these scripts to work, add them to the PATH via
|
||
#+BEGIN_SRC sh
|
||
export PATH="$HOME/codeql-lab/bin:$PATH"
|
||
#+END_SRC
|
||
|