diff --git a/docs/codeql/codeql-language-guides/codeql-for-actions.rst b/docs/codeql/codeql-language-guides/codeql-for-actions.rst new file mode 100644 index 000000000000..d4597811a470 --- /dev/null +++ b/docs/codeql/codeql-language-guides/codeql-for-actions.rst @@ -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 `: 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 `: You can model frameworks and libraries that your codebase depends on using data extensions and publish them as CodeQL model packs. diff --git a/docs/codeql/codeql-language-guides/codeql-library-for-actions.rst b/docs/codeql/codeql-language-guides/codeql-library-for-actions.rst new file mode 100644 index 000000000000..507438583c62 --- /dev/null +++ b/docs/codeql/codeql-language-guides/codeql-library-for-actions.rst @@ -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 `__ 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 `__ and `metadata syntax `__ 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 `__ +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 `__ and `workflow syntax `__ 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() diff --git a/docs/codeql/codeql-language-guides/customizing-library-models-for-actions.rst b/docs/codeql/codeql-language-guides/customizing-library-models-for-actions.rst new file mode 100644 index 000000000000..3d1a0b218272 --- /dev/null +++ b/docs/codeql/codeql-language-guides/customizing-library-models-for-actions.rst @@ -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: + data: + - + - + - ... + +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) \ No newline at end of file diff --git a/docs/codeql/codeql-language-guides/index.rst b/docs/codeql/codeql-language-guides/index.rst index 2b4fabc01a72..f59d8163db21 100644 --- a/docs/codeql/codeql-language-guides/index.rst +++ b/docs/codeql/codeql-language-guides/index.rst @@ -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 diff --git a/docs/codeql/codeql-overview/codeql-tools.rst b/docs/codeql/codeql-overview/codeql-tools.rst index f3d37880ab65..ada1a75689ed 100644 --- a/docs/codeql/codeql-overview/codeql-tools.rst +++ b/docs/codeql/codeql-overview/codeql-tools.rst @@ -23,6 +23,8 @@ The standard CodeQL query and library packs (`source `__) maintained by GitHub are: +- ``codeql/actions-queries`` (`changelog `__, `source `__) +- ``codeql/actions-all`` (`changelog `__, `source `__) - ``codeql/cpp-queries`` (`changelog `__, `source `__) - ``codeql/cpp-all`` (`changelog `__, `source `__) - ``codeql/csharp-queries`` (`changelog `__, `source `__) diff --git a/docs/codeql/query-help/actions-cwe.md b/docs/codeql/query-help/actions-cwe.md new file mode 100644 index 000000000000..d594e0e76c4c --- /dev/null +++ b/docs/codeql/query-help/actions-cwe.md @@ -0,0 +1,8 @@ +# CWE coverage for GitHub Actions + +An overview of CWE coverage for GitHub Actions in the latest release of CodeQL. + +## Overview + + + diff --git a/docs/codeql/query-help/actions.rst b/docs/codeql/query-help/actions.rst new file mode 100644 index 000000000000..38debf918190 --- /dev/null +++ b/docs/codeql/query-help/actions.rst @@ -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 `__, `source `__). + +.. include:: toc-actions.rst diff --git a/docs/codeql/query-help/codeql-cwe-coverage.rst b/docs/codeql/query-help/codeql-cwe-coverage.rst index ab78764e6aab..6236289a9ab5 100644 --- a/docs/codeql/query-help/codeql-cwe-coverage.rst +++ b/docs/codeql/query-help/codeql-cwe-coverage.rst @@ -27,6 +27,7 @@ Note that the CWE coverage includes both "`supported queries ` - :doc:`CodeQL query help for C# ` +- :doc:`CodeQL query help for GitHub Actions ` - :doc:`CodeQL query help for Go ` - :doc:`CodeQL query help for Java and Kotlin ` - :doc:`CodeQL query help for JavaScript and TypeScript ` @@ -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 diff --git a/docs/codeql/reusables/actions-further-reading.rst b/docs/codeql/reusables/actions-further-reading.rst new file mode 100644 index 000000000000..03fe948a1cd6 --- /dev/null +++ b/docs/codeql/reusables/actions-further-reading.rst @@ -0,0 +1,2 @@ +- `CodeQL queries for GitHub Actions `__ +- `CodeQL library reference for GitHub Actions `__ diff --git a/docs/codeql/reusables/extractors.rst b/docs/codeql/reusables/extractors.rst index bfcd7571cb76..30ccef6e4654 100644 --- a/docs/codeql/reusables/extractors.rst +++ b/docs/codeql/reusables/extractors.rst @@ -4,6 +4,8 @@ * - Language - Identifier + * - GitHub Actions + - ``actions`` * - C/C++ - ``cpp`` * - C# diff --git a/docs/codeql/reusables/supported-frameworks.rst b/docs/codeql/reusables/supported-frameworks.rst index 68ce952f70f3..e6bf21a20ff5 100644 --- a/docs/codeql/reusables/supported-frameworks.rst +++ b/docs/codeql/reusables/supported-frameworks.rst @@ -40,6 +40,23 @@ and the CodeQL library pack ``codeql/csharp-all`` (`changelog `__, `source `__) +and the CodeQL library pack ``codeql/actions-all`` (`changelog `__, `source `__). + +.. csv-table:: + :header-rows: 1 + :class: fullWidthTable + :widths: auto + :align: left + + Name, Category + `GitHub Actions workflow YAML files `, Workflows + `GitHub Actions action metadata YAML files `, Actions + Go built-in support ================================ diff --git a/docs/codeql/reusables/supported-versions-compilers.rst b/docs/codeql/reusables/supported-versions-compilers.rst index 92821d9556f7..7d5a9bdb34ab 100644 --- a/docs/codeql/reusables/supported-versions-compilers.rst +++ b/docs/codeql/reusables/supported-versions-compilers.rst @@ -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. diff --git a/docs/codeql/writing-codeql-queries/about-codeql-queries.rst b/docs/codeql/writing-codeql-queries/about-codeql-queries.rst index 6d263b80303b..f4e60b513c9a 100644 --- a/docs/codeql/writing-codeql-queries/about-codeql-queries.rst +++ b/docs/codeql/writing-codeql-queries/about-codeql-queries.rst @@ -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++ ` - :ref:`CodeQL library guide for C# ` - :ref:`CodeQL library guide for Go ` +- :ref:`CodeQL library guide for GitHub Actions ` - :ref:`CodeQL library guide for Java and Kotlin ` - :ref:`CodeQL library guide for JavaScript ` - :ref:`CodeQL library guide for Python ` diff --git a/docs/query-help-style-guide.md b/docs/query-help-style-guide.md index 143d9f4b8218..88b9844fc224 100644 --- a/docs/query-help-style-guide.md +++ b/docs/query-help-style-guide.md @@ -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 diff --git a/docs/query-metadata-style-guide.md b/docs/query-metadata-style-guide.md index ff478340b101..f5f2143d8be4 100644 --- a/docs/query-metadata-style-guide.md +++ b/docs/query-metadata-style-guide.md @@ -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