Usage
Gato is used by invoking gato or praetorian-gato from the command line after installing the package.
The socks-proxy and http-proxy arguments can be passed to route all traffic through a SOCKS or HTTP proxy. A use case for a SOCKS proxy would be to send traffic through a jump-box as part of a red-team engagement. The primary use case for the HTTP Proxy option would be to send both HTTPS and Git traffic through Burp.
The tool currently requires a classic GitHub personal access token OR an application OAuth token (starting with gho_). This is either one you create or one compromised as part of a penetration test. Currently, the tool does not support fine-grained Personal Access Tokens. However, this functionality may be added in the future. The PAT must be entered by setting the GH_TOKEN environment variable or entering it when prompted.
The tool has three modules, attack, enumerate, and search.
The attack module offers the ability to create malicious workflow runs via three attack types:
- Workflow
- Fork Pull Request
- Secrets Exfiltration
The workflow attack type requires a PAT with the repo and workflow scope.
The fork pull request attack type is intended to be used against public repositories and will typically use a PAT created by the tool user instead of a compromised PAT. To use the full feature set for the fork PR attack type, a token with delete_repo, workflow, and repo scope is necessary.
The enumerate module allows enumerating both private and public organizations using a GitHub personal access token. The tool, at minimum, requires a personal access token with the repo scope.
If the admin:org scope exists, the tool will perform additional enumeration actions, such as listing organization-level self-hosted runners as well as organization level secrets.
The tool currently does NOT support performing enterprise-level enumeration.
The enumeration tool supports 5 modes of operation:
- Validate Only
Simply validates the PAT and prints member organizations (if any)
- Self Enumeration
Enumerates all organizations the authenticated user associated with the PAT is a member of. This requires a token with at least the
reposcope to function correctly.
- Organization Enumeration
This will enumerate a single organization and all accessible repositories within it. If the organization has hundreds or thousands of repositories, it is advisable to use the search feature to build a smaller list of repositories to enumerate.
- Repository Enumeration
This will enumerate a single repository in
Org/Repoformat.
- Repositories Enumeration
This will enumerate a list of repositories in
Org/Repoformat from a text file.
Additionally, several flags apply to the enumeration module:
- YAML Output
If set, saves any workflow yaml files within the repositories to a provided directory.
- Skip Cloning
gato performs enumeration of workflow files by creating a sparse checkout of repositories. This only downloads the top-level files, along with the contents of the
.githubdirectory. Git clone events are included in the audit log for GitHub Enterprise Cloud customers. For details regarding the log footprint of this option, see OpSec
- Skip Runlog
Do not download any workflow run logs. This will speed up enumeration but may miss self-hosted runners for non-admin users. As of writing, this action does not generate any GitHub audit log events.
- Output JSON
Creates a full JSON output of the enumeration. This will contain all the details printed by
gatoand sometimes more (gatowill only print the first workflow it determines to be associated with a self-hosted runner, but the JSON will list all of them).
The search module is a lightweight wrapper around GitHub's code search API. It allows searching organizations for cases where self-hosted is present in YAML files. This can be used for private organizations as well if the user has access to that repository.
This is a good starting point for assessing an organization because the repositories returned can be enumerated in-depth using the enumerate module.