Source of truth: the CodeQL documentation, in particular CodeQL queries and the QL language reference. This page is a short orientation for someone writing their first queries. For using the command-line tool from a JetBrains IDE see Writing CodeQL queries in a JetBrains IDE.
CodeQL treats code as data. You build a database from a codebase, then write queries in QL, a declarative, logic-based language, to ask questions about it.
A query file ends in .ql. It usually has a metadata comment, imports, and a from … where … select block:
/**
* @name Empty if statement
* @description Finds if statements with an empty body.
* @kind problem
* @problem.severity warning
* @id example/empty-if
*/
import java
from IfStmt s
where s.getThen() instanceof EmptyStmt
select s, "This if statement has an empty body."import javabrings in the Java library. Each supported language has its own library (python,javascript,cpp,csharp,go,rubyand others).fromdeclares variables and their types, heresof typeIfStmt.whereis a logical condition over those variables.selectsays what to report. For@kind problemqueries the result is an element followed by a message string.
| Piece | What it is | Example |
|---|---|---|
| Class | A set of values with member predicates | IfStmt, MethodCall |
| Predicate | A named relation, like a function that may return several results | predicate isEmpty(Block b) { b.getNumStmt() = 0 } |
not, and, or |
Logical connectives | not e instanceof NullLiteral |
instanceof |
Type test | e instanceof NullLiteral |
result |
The return value of a predicate with a result type | int getSize() { result = 3 } |
Quantifiers let a condition range over other values. exists means some value satisfies it and forall means every value does:
from Method m
where exists(Parameter p | p = m.getAParameter() and p.getName() = "id")
select mQueries and .qll library files can define your own classes and predicates. A .qll file is a shared library; a .ql file is a query you run.
The @kind tag in the metadata decides how results are shown:
problem: an alert at one location with a message.path-problem: an alert with a data-flow path from a source to a sink (taint tracking).metricandtable: values, not alerts.
Queries live in a pack, described by qlpack.yml. The pack names its dependencies, such as the language library, and codeql pack install downloads them. Without a qlpack.yml, imports such as import java usually cannot be resolved.
With a database already built (codeql database create), run:
codeql query run --database=my-db path/to/query.ql- Start from a broad query and narrow the
whereclause step by step, running it each time. - Use the language library's documentation (the CodeQL library reference for your language) to find the class you need before writing your own.
- Give every query an
@idand a clear@name; tools rely on them. - Check the licence terms before running the CodeQL CLI on a company codebase (see the JetBrains page).
Editing .ql, .qll and .dbscheme files in a JetBrains IDE? Taintline adds highlighting, folding, a structure view and a run configuration, all offline.
Not affiliated with or endorsed by GitHub. CodeQL is a trademark of GitHub, Inc.