Docs: Add GitHub Actions as a supported language #19190
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
| .. _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. 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. | ||
|
adityasharad marked this conversation as resolved.
Outdated
|
||
| - `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. | ||
|
Contributor
There was a problem hiding this comment. For my education. Is there a preference in having this defined as a function (
Collaborator
Author
There was a problem hiding this comment. Without taking the string as a parameter, to reason about the specific job by that name, it would look something like exists(Job job |
job = workflow.getAJob() and
job.getName() = "potato" and
// whatever else you want to say about the job
)One can also do workflow.getAJob().getName() = "potato"but that only asserts that there is a job with this name, it doesn't let you perform any further reasoning involving that specific job. |
||
| - `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() | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| .. _customizing-library-models-for-actions: | ||
|
|
||
| Customizing Library Models for GitHub Actions | ||
| ========================================= | ||
|
|
||
| .. include:: ../reusables/beta-note-customizing-library-models.rst | ||
|
Contributor
There was a problem hiding this comment. Wait...this is still in beta?
Collaborator
Author
There was a problem hiding this comment. Yeah we need to drop this separately. |
||
|
|
||
| GitHub Actions analysis can be customized by adding library models in data extension files. | ||
|
Contributor
There was a problem hiding this comment. Would it make sense to link to the main documentation page for data extensions? Or maybe to include links to some examples in the code.
Collaborator
Author
There was a problem hiding this comment. I think so but I would rather do it separately for all the languages. |
||
|
|
||
| A data extension for GitHub Actions is a YAML file of the form: | ||
|
|
||
| .. code-block:: yaml | ||
|
|
||
| extensions: | ||
| - addsTo: | ||
| pack: codeql/actions-all | ||
| extensible: <name of extensible predicate> | ||
| data: | ||
| - <tuple1> | ||
| - <tuple2> | ||
| - ... | ||
|
|
||
| The CodeQL library for GitHub Actions exposes the following extensible predicates: | ||
|
|
||
| Customizing data flow and taint tracking: | ||
|
|
||
| - **actionsSourceModel**\(action, version, output, kind, provenance) | ||
| - **actionsSinkModel**\(action, version, input, kind, provenance) | ||
| - **actionsSummaryModel**\(action, version, input, output, kind, provenance) | ||
|
|
||
| Customizing Actions-specific analysis: | ||
|
|
||
| - **argumentInjectionSinksDataModel**\(regexp, command_group, argument_group) | ||
| - **contextTriggerDataModel**\(trigger, context_prefix) | ||
| - **externallyTriggerableEventsDataModel**\(event) | ||
| - **immutableActionsDataModel**\(action) | ||
| - **poisonableActionsDataModel**\(action) | ||
| - **poisonableCommandsDataModel**\(regexp) | ||
| - **poisonableLocalScriptsDataModel**\(regexp, group) | ||
| - **repositoryDataModel**\(visibility, default_branch_name) | ||
| - **trustedActionsOwnerDataModel**\(owner) | ||
| - **untrustedEventPropertiesDataModel**\(property, kind) | ||
| - **untrustedGhCommandDataModel**\(cmd_regex, flag) | ||
| - **untrustedGitCommandDataModel**\(cmd_regex, flag) | ||
| - **vulnerableActionsDataModel**\(action, vulnerable_version, vulnerable_sha, fixed_version) | ||
| - **workflowDataModel**\(path, trigger, job, secrets_source, permissions, runner) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| # CWE coverage for GitHub Actions | ||
|
|
||
| An overview of CWE coverage for GitHub Actions in the latest release of CodeQL. | ||
|
|
||
| ## Overview | ||
|
|
||
| <!-- autogenerated CWE coverage table will be added below --> | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| CodeQL query help for GitHub Actions | ||
| ============================ | ||
|
|
||
| .. include:: ../reusables/query-help-overview.rst | ||
|
|
||
| These queries are published in the CodeQL query pack ``codeql/actions-queries`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/actions/ql/src/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/actions/ql/src>`__). | ||
|
|
||
| .. include:: toc-actions.rst |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| - `CodeQL queries for GitHub Actions <https://github.com/github/codeql/tree/main/actions/ql/src>`__ | ||
| - `CodeQL library reference for GitHub Actions <https://codeql.github.com/codeql-standard-libraries/actions/>`__ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,6 +4,8 @@ | |
|
|
||
| * - Language | ||
| - Identifier | ||
| * - GitHub Actions | ||
| - ``actions`` | ||
| * - C/C++ | ||
| - ``cpp`` | ||
| * - C# | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.