Reference material
Getting started with the CodeQL CLI - CodeQL
QL packs - CodeQL
Related articles
CodeLingo vs Linters: TLDR // Bodacious Blog

Glossary

1
2
3
QL pack
    Contains important metadata that tells the
    CodeQL CLI how to process the query files.

Step 1) Install the CLI

Releases github/codeql-cli-binaries GitHub

Step 2) Obtain a local copy of the CodeQL queries

1
2
3
4
5
6
7
# Download the following repositories
git clone https://github.com/Semmle/ql
git clone https://github.com/github/codeql-go

mcd $HOME/programs/codeql-home
ln -s $MYGIT/Semmle/ql codeql-repo
ln -s $MYGIT/github/codeql-go codeql-go-repo

Step 3) Set up emacs

1
2
3
4
5
6
;; Semmle / CodeQL
(add-to-list 'auto-mode-alist '("\\.ql\\'" . ql-mode-base))
(add-to-list 'auto-mode-alist '("\\.dbscheme\\'" . dbscheme-mode))

(load (concat emacsdir "/manual-packages/semmle/dbscheme-mode.el"))
(load (concat emacsdir "/manual-packages/semmle/ql-mode-base.el"))

Step 4) Set up ranger

1
2
3
4
# Semmle / CodeQL
ext ql      = sp "$@"
ext qll      = sp "$@"
ext dbscheme      = sp "$@"

Usage

See
https://github.com/github/codeql-go/blob/master/README.md

To analyze a Go codebase, either use the CodeQL command-line interface to create a database yourself, or download a pre-built database from LGTM.com.

You can then run any of the queries contained in this repository either on the command line or using the VS Code extension.

codeql

1
codeql --help
Usage: codeql <command> <argument>...
Create and query CodeQL databases, or work with the QL language.

GitHub makes this program freely available for the analysis of open-source
software and certain other uses, but it is not itself free software. Type
codeql --license to see the license terms.

      --license              Show the license terms for the CodeQL toolchain.
Common options:
  -h, --help                 Show this help text.
  -v, --verbose              Incrementally increase the number of progress
                               messages printed.
  -q, --quiet                Incrementally decrease the number of progress
                               messages printed.
Some advanced options have been hidden; try --help -v for a fuller view.
Commands:
  query     Compile and execute QL code.
  bqrs      Get information from .bqrs files.
  database  Create, analyze and process CodeQL databases.
  dataset   [Plumbing] Work with raw QL datasets.
  resolve   [Deep plumbing] Helper commands to resolve disk locations etc.
  execute   [Deep plumbing] Low-level commands that need special JVM options.
  version   Show the version of the CodeQL toolchain.

codeql database create

1
codeql database create --help
Usage: codeql database create [OPTIONS] <database>
Create a CodeQL database for a source tree that can be analyzed using one of
the CodeQL products.

      <database>             [Mandatory] Path to the CodeQL database to create.
                               This directory will be created, and must not
                               already exist (but its parent must).
  -l, --language=<lang>      [Mandatory] The language that the new database
                               will be used to analyze.
                             There is no fixed set of supported languages; this
                               depends on which pluggable extractors have been
                               installed in the search path.
  -s, --source-root=<dir>    [Default: .] The root source code directory. In
                               many cases, this will be the checkout root.
                               Files within it are considered to be the primary
                               source files for this database. In some output
                               formats, files will be referred to by their
                               relative path from this directory.
  -j, --threads=<num>        Use this many threads for the import operation,
                               and pass it as a hint to any invoked build
                               commands. Pass 0 to use the number of cores.
  -c, --command=<command>    For compiled languages, build commands that will
                               cause the compiler to be invoked on the source
                               code to analyze. These commands will be executed
                               under an instrumentation environment that allows
                               analysis of generated code and (in some cases)
                               standard libraries.
                             If no build command is specified, the command
                               attempts to figure out automatically how to
                               build the source tree, based on heuristics from
                               the selected language pack. If the project has
                               an lgtm.yml file that defines custom build
                               commands, they will be used.
      --search-path=<dir>[:<dir>...]
                             A list of directories under which extractor packs
                               may be found. The entire directory trees rooted
                               at given directories will be searched for
                               extractors.
                             If the path contains multiple directory trees,
                               their order defines precedence between them: if
                               the target language is matched in more than one
                               of the directory trees, the one given first wins.
                             The default value is a list containing the parent
                               directory of the unpacked CodeQL toolchain,
                               followed by the unpacked toolchain itself. (If
                               this default does not work, it is strongly
                               recommended to set up --search-path in a
                               per-user configuration file).
Low-level dataset cleanup options:
      --max-disk-cache=<MB>  Set the maximum amount of space the disk cache for
                               intermediate query results can use.
                             If this size is not configured explicitly, the
                               evaluator will try to use a "reasonable" amount
                               of cache space, based on the size of the dataset
                               and the complexity of the queries. Explicitly
                               setting a higher limit than this default usage
                               will enable additional caching which can speed
                               up later queries.
  -m, --mode=<mode>          Select how aggressively to trim the cache. Choices
                               include:
                             brutal: Remove the entire cache, trimming down to
                               the state of a freshly extracted dataset
                             normal (default): Trim everything except
                               explicitly "cached" predicates.
                             light: Simply make sure the defined size limits
                               for the disk cache are observed, deleting as
                               many intermediates as necessary.
      --cleanup-upgrade-backups
                             Delete any backup directories resulting from
                               database upgrades.
      --[no-]finalize-dataset
                             Finalize this dataset, making further attempts to
                               import data into it fail. Passing this option
                               allows some additional on-disk state to be
                               deleted, but at the cost of sacrificing the
                               ability to extend the dataset later.
Common options:
  -h, --help                 Show this help text.
  -v, --verbose              Incrementally increase the number of progress
                               messages printed.
  -q, --quiet                Incrementally decrease the number of progress
                               messages printed.
Some advanced options have been hidden; try --help -v for a fuller view.

Step 5) Database creation command

1
codeql database create $HOME/programs/codeql-home/databases -l go -s $MYGIT/github/codeql-go/

Demonstration

Database creation completed successfully.

asciinema recording

Querying the database

codeql query

1
codeql query run --help
Usage: codeql query run [OPTIONS] <file.ql>
Run a single query.

This command runs single query against a CodeQL database or raw QL dataset.

By default the result of the query will be displayed on the terminal in a
human-friendly rendering. If you want to do further processing of the results,
we strongly recommend using the --output option to write the results to a file
in an intermediate binary format, which can then be unpacked into various more
machine-friendly representations by the codeql bqrs subcommands.

To run multiple queries in parallel, see codeql database run-queries.

      <file.ql>              [Mandatory] QL source of the query to execute.
  -o, --output=<file.bqrs>   A file where to output from the query will be
                               written in BQRS format.
Options to select what to query: [Exactly one of these must appear]:
  -d, --database=<database>  Path to a CodeQL database to query.
Options to control the query evaluator:
      --max-disk-cache=<MB>  Set the maximum amount of space the disk cache for
                               intermediate query results can use.
                             If this size is not configured explicitly, the
                               evaluator will try to use a "reasonable" amount
                               of cache space, based on the size of the dataset
                               and the complexity of the queries. Explicitly
                               setting a higher limit than this default usage
                               will enable additional caching which can speed
                               up later queries.
  -j, --threads=<num>        Use this many threads to evaluate queries.
Options to control RAM usage:
  -M, --ram=<MB>             Set total amount of RAM the query evaluator should
                               be allowed to use.
Options to control QL compilation:
      --warnings=<mode>      How to handle warnings from the QL compiler. One
                               of:
                             hide: Suppress warnings.
                             show (default): Print warnings but continue with
                               compilation.
                             error: Treat warnings as errors.
      --[no-]local-checking  Only perform initial checks on the part of the QL
                               source that is used.
      --no-metadata-verification
                             Don't check embedded query metadata in QLDoc
                               comments for validity.
Options to set up compilation environment:
      --search-path=<dir>[:<dir>...]
                             A list of directories under which QL packs may be
                               found. The entire directory trees rooted at
                               given directories will be searched for QL packs.
                             If the path contains multiple directory trees,
                               their order defines precedence between them: if
                               a pack name that must be resolved is matched in
                               more than one of the directory trees, the one
                               given first wins.
                             Pointing this at a checkout of the open-source
                               CodeQL repository ought to work when querying
                               one of the languages that live there.
                             The default value is a list containing the parent
                               directory of the unpacked CodeQL toolchain,
                               followed by the unpacked toolchain itself. (If
                               this default does not work, it is strongly
                               recommended to set up --search-path in a
                               per-user configuration file).
      --additional-packs=<dir>[:<dir>...]
                             If this list of directories is given, they will be
                               searched for packs before the ones in
                               --search-path. The order between these doesn't
                               matter; it is an error if a pack name is found
                               in two different places through this list.
                             This is useful if you're temporarily developing a
                               new version of a pack that also appears in the
                               default path. On the other hand it is not
                               recommended to override this option in a config
                               file; some internal actions will add this option
                               on the fly, overriding any configured value.
Common options:
  -h, --help                 Show this help text.
  -v, --verbose              Incrementally increase the number of progress
                               messages printed.
  -q, --quiet                Incrementally decrease the number of progress
                               messages printed.
Some advanced options have been hidden; try --help -v for a fuller view.

Demonstration

1
2
codeql query run -d $HOME/programs/codeql-home/databases $MYGIT/github/codeql-go/ql/src/definitions.ql
pak

$MYGIT/github/codeql-go/ql/src/definitions.ql

https://github.com/github/codeql-go/blob/master/ql/src/definitions.ql

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
/**
 * @name Jump-to-definition links
 * @description Generates use-definition pairs that provide the data
 *              for jump-to-definition in the code viewer.
 * @kind definitions
 * @id go/jump-to-definition
 */

import go

from Ident def, Ident use, Entity e
where
  use.uses(e) and
  def.declares(e)
select use, def, "V"

asciinema recording

Honest opinion: CodeLingo Query Language beats this

I’ll give it more time, though.

Update
CodeLingo and CLQL are dead. Long live Semmle.