mirror of
https://github.com/github/codeql.git
synced 2026-04-12 10:34:02 +02:00
138 lines
6.6 KiB
ReStructuredText
138 lines
6.6 KiB
ReStructuredText
.. _codeql-library-for-actions:
|
|
|
|
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 <https://github.com/github/codeql/blob/main/actions/ql/lib/actions.qll>`__ imports most other standard library modules, so you can include the complete
|
|
library by beginning your query with:
|
|
|
|
.. code-block:: ql
|
|
|
|
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 <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions>`__ and `metadata syntax <https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions>`__ for more information on GitHub Actions YAML syntax and meaning.
|
|
|
|
The control flow graph (CFG) is imported using
|
|
|
|
.. code-block:: ql
|
|
|
|
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
|
|
|
|
.. code-block:: ql
|
|
|
|
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:
|
|
|
|
.. list-table:: Main GitHub Actions library modules
|
|
:header-rows: 1
|
|
|
|
* - 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 <https://docs.github.com/en/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code/>`__
|
|
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:
|
|
|
|
.. list-table:: Main predicates in ``AstNode``
|
|
:header-rows: 1
|
|
|
|
* - 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 <https://docs.github.com/en/actions/writing-workflows/about-workflows>`__ and `workflow syntax <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions>`__ for more information.
|
|
|
|
.. list-table:: Callable classes
|
|
:header-rows: 1
|
|
|
|
* - 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``:
|
|
|
|
.. code-block:: ql
|
|
|
|
import actions
|
|
|
|
from Workflow w
|
|
where w.getName() = "test"
|
|
select w, m.getAJob()
|