Skip to content

Commit a1ceaa0

Browse files
adityasharadadityasharad
committed
Docs: Add initial library docs for Actions
Create the basic structure, state the key importable libraries. Describe a workflow. State the extensible predicates available. Other elements are to be filled in later.
1 parent f6442d2 commit a1ceaa0

File tree

2 files changed

+185
-0
lines changed

2 files changed

+185
-0
lines changed

‎docs/codeql/codeql-language-guides/codeql-library-for-actions.rst

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
.. _codeql-library-for-actions:
2+
3+
CodeQL library for GitHub Actions
4+
=======================
5+
6+
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.
7+
8+
Overview
9+
--------
10+
11+
CodeQL ships with an extensive library for analyzing GitHub Actions code, particularly GitHub Actions workflow files and Action metadata files, each written in YAML.
12+
The classes in this library present the data from a CodeQL database in an object-oriented form and provide abstractions and predicates
13+
to help you with common analysis tasks.
14+
15+
The library is implemented as a set of CodeQL modules, that is, files with the extension ``.qll``. The
16+
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
17+
library by beginning your query with:
18+
19+
.. code-block:: ql
20+
21+
import actions
22+
23+
The CodeQL libraries model various aspects of the YAML code used to define workflows and actions.
24+
The above import includes the abstract syntax tree (AST) library, which is used for locating program elements, to match syntactic
25+
elements in the YAML source code. This can be used to find values, patterns and structures.
26+
Both the underlying YAML elements and the GitHub Actions-specific meaning of those elements are modeled.
27+
28+
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.
29+
30+
The control flow graph (CFG) is imported using
31+
32+
.. code-block:: ql
33+
34+
import codeql.actions.Cfg
35+
36+
The CFG models the control flow between statements and expressions, for example whether one expression can
37+
be evaluated before another expression, or whether an expression "dominates" another one, meaning that all paths to an
38+
expression must flow through another expression first.
39+
40+
The data flow library is imported using
41+
42+
.. code-block:: ql
43+
44+
import codeql.actions.DataFlow
45+
46+
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.
47+
Data flow is particularly useful for security queries, where untrusted data flows to vulnerable parts of the program
48+
to exploit it. Related to data flow, is the taint-tracking library, which finds how data can *influence* other values
49+
in a program, even when it is not copied exactly.
50+
51+
To summarize, the main GitHub Actions library modules are:
52+
53+
.. list-table:: Main GitHub Actions library modules
54+
:header-rows: 1
55+
56+
* - Import
57+
- Description
58+
* - ``actions``
59+
- The standard GitHub Actions library
60+
* - ``codeql.actions.Ast``
61+
- The abstract syntax tree library (also imported by `actions.qll`)
62+
* - ``codeql.actions.Cfg``
63+
- The control flow graph library
64+
* - ``codeql.actions.DataFlow``
65+
- The data flow library
66+
* - ``codeql.actions.TaintTracking``
67+
- The taint tracking library
68+
69+
The CodeQL examples in this article are only excerpts and are not meant to represent complete queries.
70+
71+
Abstract syntax
72+
---------------
73+
74+
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/>`__
75+
in Visual Studio Code shows the AST nodes, including the relevant CodeQL classes and predicates.
76+
77+
All CodeQL AST classes inherit from the `AstNode` class, which provides the following member predicates
78+
to all AST classes:
79+
80+
.. list-table:: Main predicates in ``AstNode``
81+
:header-rows: 1
82+
83+
* - Predicate
84+
- Description
85+
* - ``getEnclosingWorkflow()``
86+
- Gets the enclosing Actions workflow, if any. Applies only to elements within a workflow.
87+
* - ``getEnclosingJob()``
88+
- Gets the enclosing Actions workflow job, if any. Applies only to elements within a workflow.
89+
* - ``getEnclosingStep()``
90+
- Gets the enclosing Actions workflow job step, if any.
91+
* - ``getEnclosingCompositeAction()``
92+
- Gets the enclosing composite action, if any. Applies only to elements within an action metadata file.
93+
* - ``getLocation()``
94+
- Gets the location of this node.
95+
* - ``getAChildNode()``
96+
- Gets a child node of this node.
97+
* - ``getParentNode()``
98+
- Gets the parent of this `AstNode`, if this node is not a root node.
99+
* - ``getATriggerEvent()``
100+
- Gets an Actions trigger event that can start the enclosing Actions workflow, if any.
101+
102+
103+
Workflows
104+
~~~~~~~
105+
106+
A workflow is a configurable automated process made up of one or more jobs,
107+
defined in a workflow YAML file in the `.github/workflows` directory of a GitHub repository.
108+
109+
In the CodeQL AST library, a `Workflow` is an `AstNode` representing the mapping at the top level of an Actions YAML workflow file.
110+
111+
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.
112+
113+
.. list-table:: Callable classes
114+
:header-rows: 1
115+
116+
* - CodeQL class
117+
- Description and selected predicates
118+
* - ``Workflow``
119+
- An Actions workflow. This is a mapping at the top level of an Actions YAML workflow file. See https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions.
120+
121+
On getOn() { result = super.getOn() }
122+
123+
- `getAJob()` - Gets a job within the `jobs` mapping of this workflow.
124+
- `getEnv()` - Gets an `env` mapping within this workflow declaring workflow-level environment variables, if any.
125+
- `getJob(string jobId)` - Gets a job within the `jobs` mapping of this workflow with the given job ID.
126+
- `getOn()` - Gets the `on` mapping defining the events that trigger this workflow.
127+
- `getPermissions()` - Gets a `permissions` mapping within this workflow declaring workflow-level token permissions, if any.
128+
- `getStrategy()` - Gets a `strategy` mapping for the jobs in this workflow, if any.
129+
- `getName()` - Gets the name of this workflow, if defined within the workflow.
130+
131+
The following example lists all jobs in a workflow with the name declaration `name: test`:
132+
133+
.. code-block:: ql
134+
135+
import actions
136+
137+
from Workflow w
138+
where w.getName() = "test"
139+
select w, m.getAJob()

‎docs/codeql/codeql-language-guides/customizing-library-models-for-actions.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
.. _customizing-library-models-for-actions:
2+
3+
Customizing Library Models for GitHub Actions
4+
=========================================
5+
6+
.. include:: ../reusables/beta-note-customizing-library-models.rst
7+
8+
GitHub Actions analysis can be customized by adding library models in data extension files.
9+
10+
A data extension for GitHub Actions is a YAML file of the form:
11+
12+
.. code-block:: yaml
13+
14+
extensions:
15+
- addsTo:
16+
pack: codeql/actions-all
17+
extensible: <name of extensible predicate>
18+
data:
19+
- <tuple1>
20+
- <tuple2>
21+
- ...
22+
23+
The CodeQL library for GitHub Actions exposes the following extensible predicates:
24+
25+
Customizing data flow and taint tracking:
26+
27+
- **actionsSourceModel**\(action, version, output, kind, provenance)
28+
- **actionsSinkModel**\(action, version, input, kind, provenance)
29+
- **actionsSummaryModel**\(action, version, input, output, kind, provenance)
30+
31+
Customizing Actions-specific analysis:
32+
33+
- **argumentInjectionSinksDataModel**\(regexp, command_group, argument_group)
34+
- **contextTriggerDataModel**\(trigger, context_prefix)
35+
- **externallyTriggerableEventsDataModel**\(event)
36+
- **immutableActionsDataModel**\(action)
37+
- **poisonableActionsDataModel**\(action)
38+
- **poisonableCommandsDataModel**\(regexp)
39+
- **poisonableLocalScriptsDataModel**\(regexp, group)
40+
- **repositoryDataModel**\(visibility, default_branch_name)
41+
- **trustedActionsOwnerDataModel**\(owner)
42+
- **untrustedEventPropertiesDataModel**\(property, kind)
43+
- **untrustedGhCommandDataModel**\(cmd_regex, flag)
44+
- **untrustedGitCommandDataModel**\(cmd_regex, flag)
45+
- **vulnerableActionsDataModel**\(action, vulnerable_version, vulnerable_sha, fixed_version)
46+
- **workflowDataModel**\(path, trigger, job, secrets_source, permissions, runner)

0 commit comments

Comments
 (0)