CodeQL library for GitHub Actions¶

When you’re analyzing GitHub Actions workflows and Action metadata files, you can make use of the large collection of classes in the CodeQL library for GitHub Actions.

Overview¶

CodeQL ships with an extensive library for analyzing GitHub Actions code, particularly GitHub Actions workflow files and Action metadata files, each written in YAML. The classes in this library present the data from a CodeQL database in an object-oriented form and provide abstractions and predicates to help you with common analysis tasks.

The library is implemented as a set of CodeQL modules, that is, files with the extension .qll. The module actions.qll imports most other standard library modules, so you can include the complete library by beginning your query with:

import actions

The CodeQL libraries model various aspects of the YAML code used to define workflows and actions. The above import includes the abstract syntax tree (AST) library, which is used for locating program elements, to match syntactic elements in the YAML source code. This can be used to find values, patterns and structures. Both the underlying YAML elements and the GitHub Actions-specific meaning of those elements are modeled.

See the GitHub Actions documentation on workflow syntax and metadata syntax for more information on GitHub Actions YAML syntax and meaning.

The control flow graph (CFG) is imported using

import codeql.actions.Cfg

The CFG models the control flow between statements and expressions, for example whether one expression can be evaluated before another expression, or whether an expression “dominates” another one, meaning that all paths to an expression must flow through another expression first.

The data flow library is imported using

import codeql.actions.DataFlow

Data flow tracks the flow of data through the program, including through function calls (interprocedural data flow) and between steps in a job or workflow. Data flow is particularly useful for security queries, where untrusted data flows to vulnerable parts of the program to exploit it. Related to data flow, is the taint-tracking library, which finds how data can influence other values in a program, even when it is not copied exactly.

To summarize, the main GitHub Actions library modules are:

Main GitHub Actions library modules¶
Import	Description
`actions`	The standard GitHub Actions library
`codeql.actions.Ast`	The abstract syntax tree library (also imported by actions.qll)
`codeql.actions.Cfg`	The control flow graph library
`codeql.actions.DataFlow`	The data flow library
`codeql.actions.TaintTracking`	The taint tracking library

The CodeQL examples in this article are only excerpts and are not meant to represent complete queries.

Abstract syntax¶

The abstract syntax tree (AST) represents the elements of the source code organized into a tree. The AST viewer in Visual Studio Code shows the AST nodes, including the relevant CodeQL classes and predicates.

All CodeQL AST classes inherit from the AstNode class, which provides the following member predicates to all AST classes:

Main predicates in `AstNode`¶
Predicate	Description
`getEnclosingWorkflow()`	Gets the enclosing Actions workflow, if any. Applies only to elements within a workflow.
`getEnclosingJob()`	Gets the enclosing Actions workflow job, if any. Applies only to elements within a workflow.
`getEnclosingStep()`	Gets the enclosing Actions workflow job step, if any.
`getEnclosingCompositeAction()`	Gets the enclosing composite action, if any. Applies only to elements within an action metadata file.
`getLocation()`	Gets the location of this node.
`getAChildNode()`	Gets a child node of this node.
`getParentNode()`	Gets the parent of this `AstNode`, if this node is not a root node.
`getATriggerEvent()`	Gets an Actions trigger event that can start the enclosing Actions workflow, if any.

Workflows¶

A workflow is a configurable automated process made up of one or more jobs, defined in a workflow YAML file in the .github/workflows directory of a GitHub repository.

In the CodeQL AST library, a Workflow is an AstNode representing the mapping at the top level of an Actions YAML workflow file.

See the GitHub Actions documentation on workflows and workflow syntax for more information.

Callable classes¶
CodeQL class	Description and selected predicates
`Workflow`	An Actions workflow, defined as a mapping at the top level of a workflow YAML file in `.github/workflows`. See https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions. `getAJob()` - Gets a job within the `jobs` mapping of this workflow. `getEnv()` - Gets an `env` mapping within this workflow declaring workflow-level environment variables, if any. `getJob(string jobId)` - Gets a job within the `jobs` mapping of this workflow with the given job ID. `getOn()` - Gets the `on` mapping defining the events that trigger this workflow. `getPermissions()` - Gets a `permissions` mapping within this workflow declaring workflow-level token permissions, if any. `getStrategy()` - Gets a `strategy` mapping for the jobs in this workflow, if any. `getName()` - Gets the name of this workflow, if defined within the workflow.

The following example lists all jobs in a workflow with the name declaration name: test:

import actions

from Workflow w
where w.getName() = "test"
select w, m.getAJob()