mirror of
https://github.com/github/codeql.git
synced 2025-12-19 02:13:17 +01:00
98b6e5ce2f
Discovered in internal review of docs preview. Use double backticks to render inline code blocks. Use __ after inline hyperlinks. Use an extra blank line to format the Actions library predicates table correctly. Fix some rogue references to Ruby and case inconsistency.
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()
|