About GitGoat for GitHub
GitGoat enables DevOps and Engineering teams to test security products intending to integrate with GitHub. GitGoat is a learning and training project that demonstrates common configuration errors that can potentially allow adversaries to introduce code to production.
GitGoat was built to enable DevOps and Engineering teams to design and implement a sustainable misconfiguration prevention strategy. It can be used for proof-of-concept projects, such as OpenSSF, Arnica, and others.
Since GitGoat creates misconfigured assets on GitHub, it is warmly recommended to avoid using it in a production organization.
Here is what you need before kicking off the process:
- Account on GitHub
At this point, GitHub does not support the creation of an organization via APIs. Thus, the organization needs to be created via the user interface. Below are the steps to create an organization:
- Login to GitHub and navigate to the organization creation page.
- Fill the
Organization account name(e.g. GitGoat-Demo), “Contact email”, and select
My personal accountunder the “This organzation belongs to” section. Click on next and skip the next screen of adding organization members.
Create a Personal Access Token (PAT) to GitHub
A PAT is required to run GitGoat in order to create repositories and teams, and invite members to the organization created in the previous step. To create a PAT, follow these steps:
- Go to the new tokens page. If you are redirected to the login page, authenticate yourself.
- Fill the fields in the “New personal access token page” and then click on
- Set the
expirationtime as needed. Since it will be used only to execute GitGoat, a short expiration time is preferred.
- Select the following scopes:
- Set the
- Make sure to copy your personal access token now. It will be required for the next step.
Run a Docker Container
Clone the docker image:
docker pull ghcr.io/arnica-ext/gitgoat:main
Run the container by injecting the PAT as an environment variable:
docker run -ti --env github_token=[YOUR_PAT] --rm ghcr.io/arnica-ext/gitgoat:main python3 run.py --org [YOUR_ORGANIZATION_NAME]
GitGoat can be customized in the
config.yamlfile. To modify this file or run GitGoat with multiple variations of the config file, please follow the instructions below.
Set the environment variable
Open your preferred terminal, clone this repo and change the directory to the GitGoat folder.
git clone https://github.com/arnica-ext/GitGoat.git GitGoat cd GitGoat
On Mac/Linux, set the environment variable
github_token using the following command:
On Windows, use the following command:
Install the requirements
Install the required libraries to run GitGoat with the following command:
python3 -m pip install -r requirements.txt
This is the moment of truth, go for it!
python3 run.py --org [YOUR_ORGANIZATION_NAME]
The configuration file
config.yaml can be adjusted as needed, or if multiple files are used, add
--config [YOUR_CONFIG_FILE.yaml] to the execution path above.
In case you’d like to rant and rave about the tokens in this file, these accounts are dummy just to create commits in your organization. Feel free to spend the time to create your accounts, if needed.
Validate the results
If everything went well, you should see the following in your newly created organization:
- 5 new repositories named Echinacea, Lavender, Chamomile, Calendula, Tarragon (we like the herbs theme).
- Many teams with the naming convention [repository_name]-[admin/maintain/triage/push/pull]. Each team has a specific permission to the associated repository.
- 5 users named miker-gg (a.k.a. Mike Roservice) archie-gg (a.k.a. Archie Tekkt), billdp-gg (a.k.a. Bill De Pipeline), codeyf-gg (a.k.a. Codey Fie) and debu-gg (a.k.a. Deb Ugeen) as members in the organization and the teams.
- Many commits by the users in the last 12 months. Keep in mind that the commit dates are vary, but there is only a single push by every user to the relevant repository.
How to use GitGoat
Avoid changing the built-in repositories visibility
GitGoat generates valid and invalid secrets to test hardcoded secrets detectors. Please keep the repositories private in order to avoid a situation where GitHub blocks the valid secrets when they are exposed publicly.
Everything else is Kosher
Well… do whatever you want with it…
Contribute to GitGoat
GitGoat is open sourced to the community in order to encourage everyone to test security products in a rapid fashion without impacting the production operations. In return, please open issues, create pull requests, or simply add us to the watch list to follow our enhancements in this project.