GitHub-Audit

Report on GitHub organizations and repositories for adherence to Mozilla's Guidelines for Sensitive Repositories (additional background).

GitHub-Audit is a set of scripts which can be used to query various aspects of an organization or repository.

These scripts are intended to be usable both from the command line (CLI) and via automation (using 12 Factor principles whenever possible).

Installation

For now, users should clone the repository, and install the requirements using poetry:

git clone https://GitHub.com/Mozilla-Services/GitHub-Audit
cd GitHub-Audit
poetry install

Usage example

NOTE: run all scripts in the virtual environment created by poetry. From within the checkout, either activate the virtualenv:

$ poetry shell
$ # run scripts
$ exit  # deactivate virtual env

Or run each script within the virtual env:

$ poetry run {script}

All scripts should respond to the --help option. Additional options are often described there.

Docker

Using docker to produce CSV output:

$ docker build -t audit .
$ docker run -e GITHUB_TOKEN -e GITHUB_ORG=mozilla-services audit

Checks via API

These checks require a PAT token available. The PAT token should be on the second line of a file named .credentials in the current directory (s/a #3).

Each of the scripts below supports a --help option. Use that for additional information on invoking each script.

• get_branch_protections.py * to extract the information about protected branches. Outputs JSON file, which report_branch_status.py can summarize to csv. Import that into a spreadsheet, and play.

• show_all_terms is a wrapper script around term_search.py. It makes local shallow clones of repos that match, and uses rg to search for additional occurances. Use the --help option.

• term_search.py search orgs or repos for a specific term, such as an API token name. Outputs list of repos that do have the term (per GitHub's index, which can be out of date).

For more examples and usage, please refer to the Wiki.

Development setup

Prerequisites

This project uses Black to format all python code. A .pre-commit-config.yaml file is included, and use of the pre-commit is recommended.

To ready your environment for development, do:

poetry install --dev
pre-commit install

Release History

See [Changes]

License

Distributed under the Mozilla Public License, version 2 (MPL-2) license. See LICENSE for more information.

Contributing

1. Discuss any new feature first by opening an issue.
2. Fork it (https://github.com/mozilla-services/GitHub-Audit/fork)
3. Clone your fork to your development environment.
4. Create your feature branch (git checkout -b feature/fooBar)
5. Commit your changes (git commit -am 'Add some fooBar')
6. Push to the branch (git push origin feature/fooBar)
7. Create a new Pull Request