GitHub Actions Pipeline Enumeration and Attack Tool
[!WARNING]
This repository is deprecated and archived
Gato has been superseded by Trajan, Praetorian's multi-platform CI/CD vulnerability detection and attack automation tool. Trajan consolidates GitHub Actions (Gato) and GitLab (Glato) CI/CD attack capabilities into a single, actively-maintained project.
Please migrate to Trajan: https://github.com/praetorian-inc/trajan
No further updates, bug fixes, or security patches will be made to this repository.
Gato, or GitHub Attack Toolkit, is an enumeration and attack tool that allows both blue teamers and offensive security practitioners to identify and exploit pipeline vulnerabilities within a GitHub organization's public and private repositories.
The tool has post-exploitation features to leverage a compromised personal access token in addition to enumeration features to identify poisoned pipeline execution vulnerabilities and actions artifacts secrets against public repositories.
GitHub recommends that self-hosted runners only be utilized for private repositories, however, there are thousands of organizations that utilize self-hosted runners. Default configurations are often vulnerable, and Gato uses a mix of workflow file analysis and run-log analysis to identify potentially vulnerable repositories at scale.
Gato version 1.7 introduces the Actions Artifacts Secrets Scanner.
The Actions Artifacts Secrets Scanner enumerates GitHub Actions workflow artifacts for secrets. Praetorian researchers have leveraged the scanner to identify critical vulnerabilities in several prominent open-sourced projects. Details of these vulnerabilities will be released once the disclosure processes are complete. This work was initially inspired by research from Palo Alto Networks.
The Actions Artifacts Secrets Scanner performs the following actions:
NoseyParker must be installed in the $PATH of the system running the Actions Artifacts Secrets Scanner.
Secrets in public workflow artifacts can contain many false positives. By
default, the Actions Artifacts Secrets Scanner excludes rules and results
associated with common false positives. To include all secrets scanning results,
you can use the --include_all_artifact_secrets flag.
Here is an example command that runs the Actions Artifacts Secrets Scanner on a list of GitHub organizations, disables self-hosted runner enumeration, includes all artifact secret results, and outputs to a JSON file.
gato e --enum_wf_artifacts --include_all_artifact_secrets --skip_sh_runner_enum -O testorgs.txt -oJ testorgoutput.json
By default, the Actions Artifacts Secrets Scanner imposes the following limitations to reduce the time spent on a single repository:
These constraints were optimized such that the Actions Artifacts Secrets Scanner
can scan the top 200 GitHub organizations within 48 hours. If you want to modify
these constraints, you can update them in the scan_wf_artifacts() function of
gato/enumerate/repository.py.
Gato supports OS X and Linux with at least Python 3.7.
In order to install the tool, simply clone the repository and use pip install. We
recommend performing this within a virtual environment.
git clone https://github.com/praetorian-inc/gato
cd gato
python3 -m venv venv
source venv/bin/activate
pip install .
Gato also requires that git version 2.27 or above is installed and on the
system's PATH. In order to run the fork PR attack module, sed must also be
installed and present on the system's path.
We maintain a development branch that contains newer Gato features that are not
yet added to main. There is an increased chance you will run into bugs; however,
we still run our integration test suite on the dev branch, so there should not
be any blatant bugs.
If you want to use the dev branch, just check it out prior to running pip
install - that's it!
If you do run into any bugs for your specific use case, by all means open an issue!
After installing the tool, it can be launched by running gato or
praetorian-gato.
We recommend viewing the parameters for the base tool using gato -h, and the
parameters for each of the tool's modules by running the following:
gato search -hgato enum -hgato attack -hThe tool requires a GitHub classic or app installation token in order to
function. To create one, log in to GitHub and go to GitHub Developer
Settings and select Generate New Token
and then Generate new token (classic).
After creating this token set the GH_TOKEN environment variable within your
shell by running export GH_TOKEN=<YOUR_CREATED_TOKEN>. Alternatively, store
the token within a secure password manager and enter it when the application
prompts you.
If creating a GitHub App Installation token, the app needs to have at least
Actions:read and Contents:read to execute the enumeration modules.
For troubleshooting and additional details, such as installing in developer mode or running unit tests, please see the wiki.
Please see the wiki for detailed documentation, as well as OpSec considerations for the tool's various modules!
If you believe you have identified a bug within the software, please open an issue containing the tool's output, along with the actions you were trying to conduct.
If you are unsure if the behavior is a bug, use the discussions section instead!
Contributions are welcome! Please review our design methodology and coding standards before working on a new feature!
Additionally, if you are proposing significant changes to the tool, please open an issue to start a conversation about the motivation for the changes.
Gato is licensed under the Apache License, Version 2.0.
Copyright 2023 Praetorian Security, Inc
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.