hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2026-04-22 15:25:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #19190 from adityasharad/actions/initial-docs

Browse Source 
Docs: Add GitHub Actions as a supported language
This commit is contained in:
Aditya Sharad
2025-04-03 04:39:23 +05:30
committed by GitHub
parent 62fa136506 4d6afe7d29
commit 927b26b869
16 changed files with 254 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/codeql/codeql-language-guides/codeql-for-actions.rst Normal file
View File

@@ -0,0 +1,17 @@
.. _codeql-for-actions:
CodeQL for GitHub Actions
=========================
Experiment and learn how to write effective and efficient queries for CodeQL databases generated from GitHub Actions code.
.. toctree::
:hidden:
codeql-library-for-actions
customizing-library-models-for-actions
- :doc:`CodeQL library for GitHub Actions <codeql-library-for-actions>`: When you're analyzing a Ruby program, you can make use of the large collection of classes in the CodeQL library for GitHub Actions.
- :doc:`Customizing library models for GitHub Actions <customizing-library-models-for-actions>`: You can model frameworks and libraries that your codebase depends on using data extensions and publish them as CodeQL model packs.

136
docs/codeql/codeql-language-guides/codeql-library-for-actions.rst Normal file
View File

@@ -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, 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()

46
docs/codeql/codeql-language-guides/customizing-library-models-for-actions.rst Normal file
View File

@@ -0,0 +1,46 @@
.. _customizing-library-models-for-actions:
Customizing Library Models for GitHub Actions
=============================================
.. include:: ../reusables/beta-note-customizing-library-models.rst
GitHub Actions analysis can be customized by adding library models in data extension files.
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)

1
docs/codeql/codeql-language-guides/index.rst
View File

@@ -7,6 +7,7 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
.. toctree::
codeql-for-actions
codeql-for-cpp
codeql-for-csharp
codeql-for-go

2
docs/codeql/codeql-overview/codeql-tools.rst
View File

@@ -23,6 +23,8 @@ The standard CodeQL query and library packs
(`source <https://github.com/github/codeql/tree/codeql-cli/latest>`__)
maintained by GitHub are:
- ``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>`__)
- ``codeql/actions-all`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/actions/ql/lib/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/actions/ql/lib>`__)
- ``codeql/cpp-queries`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/cpp/ql/src/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/cpp/ql/src>`__)
- ``codeql/cpp-all`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/cpp/ql/lib/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/cpp/ql/lib>`__)
- ``codeql/csharp-queries`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/csharp/ql/src/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/csharp/ql/src>`__)

8
docs/codeql/query-help/actions-cwe.md Normal file
View File

@@ -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 -->

8
docs/codeql/query-help/actions.rst Normal file
View File

@@ -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

1
docs/codeql/query-help/codeql-cwe-coverage.rst
View File

@@ -27,6 +27,7 @@ Note that the CWE coverage includes both "`supported queries <https://github.com
:titlesonly:
full-cwe
actions-cwe
cpp-cwe
csharp-cwe
go-cwe

2
docs/codeql/query-help/index.rst
View File

@@ -5,6 +5,7 @@ View the query help for the queries included in the ``default``, ``security-exte
- :doc:`CodeQL query help for C and C++ <cpp>`
- :doc:`CodeQL query help for C# <csharp>`
- :doc:`CodeQL query help for GitHub Actions <actions>`
- :doc:`CodeQL query help for Go <go>`
- :doc:`CodeQL query help for Java and Kotlin <java>`
- :doc:`CodeQL query help for JavaScript and TypeScript <javascript>`
@@ -28,6 +29,7 @@ For a full list of the CWEs covered by these queries, see ":doc:`CodeQL CWE cove
:hidden:
:titlesonly:
actions
cpp
csharp
go

2
docs/codeql/reusables/actions-further-reading.rst Normal file
View File

@@ -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/>`__

2
docs/codeql/reusables/extractors.rst
View File

@@ -4,6 +4,8 @@
* - Language
- Identifier
* - GitHub Actions
- ``actions``
* - C/C++
- ``cpp``
* - C#

17
docs/codeql/reusables/supported-frameworks.rst
View File

@@ -40,6 +40,23 @@ and the CodeQL library pack ``codeql/csharp-all`` (`changelog <https://github.co
NHibernate, Database ORM
WinForms, User interface
GitHub Actions built-in support
================================
Provided by the current versions of the
CodeQL query pack ``codeql/actions-queries`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/cpp/ql/src/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/actions/ql/src>`__)
and the CodeQL library pack ``codeql/actions-all`` (`changelog <https://github.com/github/codeql/tree/codeql-cli/latest/cpp/ql/lib/CHANGELOG.md>`__, `source <https://github.com/github/codeql/tree/codeql-cli/latest/actions/ql/lib>`__).
.. csv-table::
:header-rows: 1
:class: fullWidthTable
:widths: auto
:align: left
Name, Category
`GitHub Actions workflow YAML files <https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions>`, Workflows
`GitHub Actions action metadata YAML files <https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions>`, Actions
Go built-in support
================================

2
docs/codeql/reusables/supported-versions-compilers.rst
View File

@@ -16,6 +16,7 @@
.NET Core up to 3.1
.NET 5, .NET 6, .NET 7, .NET 8, .NET 9","``.sln``, ``.csproj``, ``.cs``, ``.cshtml``, ``.xaml``"
GitHub Actions [12]_,"Not applicable",Not applicable,"``.github/workflows/*.yml``, ``.github/workflows/*.yaml``, ``**/action.yml``, ``**/action.yaml``"
Go (aka Golang), "Go up to 1.24", "Go 1.11 or more recent", ``.go``
Java,"Java 7 to 24 [5]_","javac (OpenJDK and Oracle JDK),
@@ -40,3 +41,4 @@
.. [9] Requires glibc 2.17.
.. [10] Support for the analysis of Swift requires macOS.
.. [11] TypeScript analysis is performed by running the JavaScript extractor with TypeScript enabled. This is the default.
.. [12] Support for GitHub Actions is in public preview.

1
docs/codeql/writing-codeql-queries/about-codeql-queries.rst
View File

@@ -74,6 +74,7 @@ When writing your own alert queries, you would typically import the standard lib
- :ref:`CodeQL library guide for C and C++ <codeql-library-for-cpp>`
- :ref:`CodeQL library guide for C# <codeql-library-for-csharp>`
- :ref:`CodeQL library guide for Go <codeql-library-for-go>`
- :ref:`CodeQL library guide for GitHub Actions <codeql-library-for-actions>`
- :ref:`CodeQL library guide for Java and Kotlin <codeql-library-for-java>`
- :ref:`CodeQL library guide for JavaScript <codeql-library-for-javascript>`
- :ref:`CodeQL library guide for Python <codeql-library-for-python>`

7
docs/query-help-style-guide.md
View File

@@ -7,9 +7,12 @@ When you contribute a new [supported query](supported-queries.md) to this reposi
* [C/C++ queries](https://codeql.github.com/codeql-query-help/cpp/)
* [C# queries](https://codeql.github.com/codeql-query-help/csharp/)
* [Go queries](https://codeql.github.com/codeql-query-help/go/)
* [Java queries](https://codeql.github.com/codeql-query-help/java/)
* [JavaScript queries](https://codeql.github.com/codeql-query-help/javascript/)
* [GitHub Actions queries](https://codeql.github.com/codeql-query-help/actions/)
* [Java/Kotlin queries](https://codeql.github.com/codeql-query-help/java/)
* [JavaScript/TypeScript queries](https://codeql.github.com/codeql-query-help/javascript/)
* [Python queries](https://codeql.github.com/codeql-query-help/python/)
* [Ruby queries](https://codeql.github.com/codeql-query-help/ruby/)
* [Swift queries](https://codeql.github.com/codeql-query-help/swift/)
### Location and file name

5
docs/query-metadata-style-guide.md
View File

@@ -19,10 +19,13 @@ For examples of query files for the languages supported by CodeQL, visit the fol
* [C/C++ queries](https://codeql.github.com/codeql-query-help/cpp/)
* [C# queries](https://codeql.github.com/codeql-query-help/csharp/)
* [GitHub Actions queries](https://codeql.github.com/codeql-query-help/actions/)
* [Go queries](https://codeql.github.com/codeql-query-help/go/)
* [Java queries](https://codeql.github.com/codeql-query-help/java/)
* [Java/Kotlin queries](https://codeql.github.com/codeql-query-help/java/)
* [JavaScript queries](https://codeql.github.com/codeql-query-help/javascript/)
* [Python queries](https://codeql.github.com/codeql-query-help/python/)
* [Ruby queries](https://codeql.github.com/codeql-query-help/ruby/)
* [Swift queries](https://codeql.github.com/codeql-query-help/swift/)
## Metadata area