Overview and Purpose

GitHub is a wonderful ecosystem with many extensions to make certain workflows easier. However, if you are in the 1% that host a "sensitive" repository on GitHub, you may want to follow the suggestions below.

The permissions model on GitHub, especially for older OAuth authenticated apps, is quite broad -- what you enable for one project applies to all projects you have access to.

This can expose repositories with sensitive information to risks, without the repository admins being aware of risks. The following guidelines should be applied to all sensitive repositories (defined below) hosted on GitHub.

The purpose of this checklist is to provide a base level of protection against compromise of credentials that may have the ability to modify repository resources (code, wikis, issues, etc.). Those credentials could belong either to an individual, or given to GitHub extensions.

These guidelines are in addition to the corporate standards login required.

These guidelines were developed by the Firefox Operations Security team. Direct any questions or comments on the guidelines to secops+github  mozilla.com.

For implementation assistance contact the owners of your GitHub organization.

Terminology

As used in this document, the following terms have specific meanings.

Elevated Permissions

Any permission not available to a logged in GitHub member. For public repositories, this is "push" access (which includes the ability to assign issues). For private repositories, it also includes the ability to read the repository.

Production Branch

Any branch that generates a release that is supported in some way.

Release

Any distribution of the code, or artifacts generated from the code, for external use. "Release" includes deployments to staging or production hardware, "code drops" into another project, and similar milestones.

Sensitive Repository

This term includes (but is not limited to):

• Repositories containing code that is directly or indirectly part of the Firefox product delivered by Mozilla.
• Repositories containing code that is run in production as part of services supporting the build, release, or ongoing operations of Firefox.
• Repositories containing PII or 3rd party IP which Mozilla has a contractual obligation to protect

Guidelines

The guidelines below are strongly encouraged, and may be required by some groups. If you have reasons for not adopting individual ones, please document that for future reference.

Each checklist below is in MARKDOWN format to be copy/pasted into Github issues.

Membership

- [ ] All GitHub accounts granted specific access to a sensitive repository need to have a current email contact address recorded in a Mozilla system. (GitHub does not provide this feature.) For staff, that should be done in the "Github Username" field of their phonebook record, for others GitHub should be added as a "Profile Identity" in their Mozillians record, and their login added to the "Bio" section. 
- [ ] All GitHub accounts must use 2FA
- [ ] Any member given elevated permissions to a repository should be told that it is their responsibility to contact organization owners and repository admins if they ever suspect or know that any of their GitHub credentials have been leaked or compromised. (This includes any Personal Access Tokens generated by the user.)

Repository

- [ ] Sensitive repositories should only be hosted in a GitHub organization operated by Mozilla staff.
- [ ] The hosting organization should have 2FA set as a requirement.
- [ ] The branching structure of the repository should be documented.
- [ ] Committing (or merging) to a production branch should be limited to the smallest reasonable set of people.
- [ ] Branch protection should be enabled for production branches
- [ ] Branch protections should always apply to administrators as well.
- [ ] Commits (including merges) to the production branch should be GPG signed.
- [ ] Important milestones, such as releases, should be marked by a signed tag.
- [ ] When creating a release, all commits which compose that release should first be audited.
- [ ] Elevated permissions should be granted to teams, not individual accounts, whenever possible. (Only org members can be part of a team.)
- [ ] Enable [Automated Security Fixes][1] for the repository. If the vulnerability identified by Dependabot is not applicable to your repository, document that in the Dependabot PR, then close the PR (don't merge the PR).

[1]: https://help.github.com/en/articles/configuring-automated-security-fixes

GitHub Actions and Workflows

Please see GitHub Workflows & Actions for recommended practices.

Implementation

Initial

The following 3 recommendations should be implemented first:

1. Use of 2fa by everyone associated with the sensitive repository.
2. Implementing signed commits and tags into your workflows.

   Note: While conceptually "simple", in practice it is difficult to enforce and audit when GitHub web commits and commits from automation are used (which is almost always). For now, tags used to mark releases should be signed.

3. Hosting in a Mozilla staff managed organization.

The other recommendations should follow as soon as practical.

Ongoing

• Review repository and organization settings. Many of the guidelines require the cooperation of individuals to implement. At the moment, there is no automated way to assess the degree of implementation. Until such automation is in place, manual checking should be done on a regular basis. Once a quarter is recommended.

• Review Guidance for changes. The guidance should be reviewed for applicability to each sensitive repository on a regular basis. The recommendation is to do this on any significant change, or once a year.

Problems and Options

Just "flipping the switch" on some of these guidelines can, for some teams, be disruptive, and possibly add excessive friction. Please review collected solutions to various problems on the Problems and Options page. Consult with the security team supporting your project if you have any questions.

The goal is to minimize risk to an appropriate level for each repository.