<center><img src='https://repository-images.githubusercontent.com/503625714/4c7c0d6c-cd0c-448c-98b9-e24be16b3ca4' alt='Gitgat' width="250" /></center>

Source control system security posture

SCM (Source Control Management) security is of high importance as it serves as an entry point to the whole CI/CD pipeline. This repository contains policies that verify SCM (currently GitHub's) organization/repositories/user accounts security. The policies are evaluated using Open Policy Agent (OPA).

There are different sets of policies depending on which account is being evaluated. Most policies are only relevant for organization owners. See the rulesets section bellow.

The policies are evaluated against a certain state. When executed for the first time, the state is empty. The returned data should be reviewed, and the security posture should be manually evaluated (with recommendations from each module). If the state is approved, it should be added to the input data, so that the next evaluation of policies tracks the changes of the state. More information about the state configurable for each module is available in each module's corresponding section.

Usage

Get a GitHub Personal Access Token

1. Generate a Personal Access Token with necessary permissions on GitHub in Settings > Developer Settings. You will need the following permissions:

• read:org
• read:user
• read:public_key
• repo:status
• repo_deployment
• read:repo_hook
• public_repo
• gist

If needed, refer to each module's section to figure out what permissions are needed to evaluate the module's policies.

2. Set an environment variable with the token, for example:

export GH_TOKEN='<token>'

Run Using Docker

Run the following to get the report as a gist in your GitHub Account:

docker run -e GH_TOKEN scribesecurity/gitgat:latest data.gh.post_gist

You can access your report from your gists https://gist.github.com/

Run the following to get the report as a Markdown file:

docker run -e GH_TOKEN scribesecurity/gitgat:latest data.github.report.print_report 2> report.md

Run the following to get the report as a JSON object:

docker run -e GH_TOKEN scribesecurity/gitgat:latest data.gh.eval

In order to run the report using the variables and state you have saved in the input.json file, use this command:

docker run -e GH_TOKEN -v <full_path_to_directory_containing_input_file>:/var/opt/opa scribesecurity/gitgat:latest

If you have already included the token in the input.json file, you can shorten it to:

docker run -v <full_path_to_directory_containing_input_file>:/var/opt/opa scribesecurity/gitgat:latest

Note that the default report is the JSON version, so if you want to get the Markdown file you need to specify it as seen at the top of this section.

Run Using the OPA CLI

Install OPA and additional tools

In order to execute the evaluation of the policies, download and install OPA (version 0.40.0 and up) from https://www.openpolicyagent.org/docs/latest/#running-opa. Binaries are available for macOS, Linux and Windows.

The examples below demonstrating safe handling of GitHub's Personal Access Token via an environment variable rely on cat and sed which are typically available on macOS and Linux. They can be obtained for Windows as well, for example, by using Git for Windows. It is also possible to put the token directly into the configuration file, but do it at your own risk and make sure that it cannot be read by other users.

Clone this repository

Clone the repository using:

git clone git@github.com:scribe-public/gitgat.git 

And then enter into the directory created:

cd gitgat

Configure the input.json configuration file

The configuration file for the examples below is expected to be input.json. Make sure you create this file in the main gitgat folder, using the following script:

cp data/empty-input.json input.json  

Samples of configuration files can be found in here: https://github.com/scribe-public/gitgat/blob/master/data/.

If you wish to add information or state to your input.json file, you can refer to data/sample_input.json, for policies configuration and state management. Each rule set is its own JSON section, and the state information for each rule fits inside that segment. Make sure that the state information does not get pushed to the repository, as it might contain sensitive data.

sample_input.json is not included in .gitignore, but input.json is. So it is recommended to use input.json as the input configuration file for OPA.

Run the policies using OPA

When running eval and report commands, pipe the token variable via stdin and sed. Following are a few examples of uses.

Create a report as a report as a gist in your GitHub account:

cat input.json | sed "s/GH_TOKEN/$GH_TOKEN/" | opa eval -I -b github data.gh.post_gist

Get a report as a md file:

cat input.json | sed "s/GH_TOKEN/$GH_TOKEN/" | opa eval -I -b github data.github.report.print_report 2> report.md

Get a report as a JSON object:

cat input.json | sed "s/GH_TOKEN/$GH_TOKEN/" | opa eval -I -b github data.gh.eval

Run a specific module/rule:

cat input.json | sed "s/GH_TOKEN/$GH_TOKEN/" | opa eval -I -b github data.github.<module>.eval

For example:

cat input.json | sed "s/GH_TOKEN/$GH_TOKEN/" | opa eval -I -b github data.github.ssh_keys.eval

You can find the different rule files under data/github. Each file is a single OPA rule. The file name is the rule name, and that's the name you can use instead of the <module>.

(Under development) Print the Markdown report to stdout:

cat input.json | sed "s/GH_TOKEN/$GH_TOKEN/" | opa eval -I -b github data.github.report.print_report

(Under development) Upload the report to GitHub as a Gist:

cat input.json | sed "s/GH_TOKEN/$GH_TOKEN/" | opa eval -I -b github data.gh.post_gist

Rule sets

The evaluation can be run for three different rule sets. The rule set is configured via input.rule_set:

• "user" - evaluates rules from a single user perspective.
• "org" - evaluates rules from an organization perspective. The organizations that are evaluated are configured in the input.json file under the organizations header.
• "enterprise" - evaluates rules for an enterprise (coming soon).

The default selection is "user" as can be seen in the example input.json file above.

State configuration

Policies are configured via relevant state objects in input.json. Each configurable module has a corresponding input configuration object. Configuration parameters are described in each module's section below. The state can be updated and approved by the policy administrator. Eval rules print out violations of policies. The violated rules can be used to configure exceptions allowed by the SCM administrator for the modules by updating the state of the modules. Additional information about modules is available in corresponding eval rules descriptions.

Authentication modules

2 factor authentication

2 factor authentication protects against developers account password leakage. It is highly recommended to request users to enable 2 factor authentication. Module tfa checks for organization members with 2 factor authentication disabled.

Required permissions:

• read:org - note, that only organization owners can get the list of users with 2 factor authentication disabled
• read:user - to get the list of organizations the user belongs to (when evaluating the user rule set)

Configuration parameters:

• input.tfa.disabled_members - specifies the list of users that are allowed to have 2 factor authentication disabled
• input.tfa.unenforced_orgs - specifies the list of organizations that are allowed to have 2 factor authentication enforcements disabled

Rule modules:

• data.github.tfa.eval.state.disabled_members returns the list of users in each organization that have the 2 factor authentication disabled. If the new state is approved, they should be added to the configuration state.

• data.github.tfa.eval.state.unenforced_orgs returns the list of organizations that do not enforce 2 factor authentication.

SSH keys

Developers can use SSH keys to access the repositories. A leaked SSH key gives an attacker access to the repository without the need to acquire a password. To mitigate the risk, it is advised to rotate SSH keys periodically and review configured SSH keys. The module is supported in the user rule set as organization owners do not have access to SSH keys metadata. Module ssh_keys checks for expired and newly added SSH keys.

Required permissions:

• read:public_key - to get the list of user's SSH public keys

Configuration parameters:

• input.ssh_keys.expiration - [years, months, days] for the SSH keys expiration
• input.ssh_keys.keys - list of SSH keys that are registered for the user

Rule modules:

• data.github.ssh_keys.eval.state.expired returns the list of SSH keys that are older than configured by the expiration parameter.
• data.github.ssh_keys.eval.state.keys returns the list of SSH keys that were not previously added to the input configuration file. All the approved keys should be added to the configuration state.

Deploy keys

Deploy keys are SSH keys that give access to a specific repository (as opposed to the user's SSH keys that give access to all user's repositories). The same recommendations apply to deploy keys. Module deploy_keys checks for expired and newly added deploy keys.

Required permissions:

• repo - to get the list of deploy keys

Configuration parameters:

• input.deploy_keys.expiration - [years, months, days] for the deploy keys expiration
• input.deploy_keys.keys - list of deploy keys that are registered for the r