GitHub is a wonderful ecosystem with many extensions to make certain workflows easier. However, if you're in the 1% that host a "sensitive" repository on GitHub, you may want to follow the suggestions below.
The permissions model on GitHub for older OAuth authenticated apps is quite broad -- what you enable for one project applies to all projects you (the user) 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 hosted on GitHub.
Sensitive repositories include (but are 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.
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.
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.
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.
Not all of the guidelines can be verified independently. Some of them require a user to "self report".
- 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 people.m.o record, for others GitHub should be added as a "Profile Identity" in their Mozillians record, and their login added to the "Bio" section". (see below)
- All GitHub accounts must use 2FA
- All GitHub accounts with elevated permissions must have phone numbers removed. (This protects against 2FA bypass using SMS reset.)
- 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.)
- 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 Protection Help
- Branch protections should always apply to administrators as well. Branch Protection Help
- Commits (including merges) to the production branch should be GPG signed. GPG Signing
- Important milestones, such as releases, should be marked by a signed tag. GPG Signing
- Important milestone achievement criteria should include an audit all relevant verified commits.
- Elevated permissions should be granted to teams, not individual accounts, whenever possible. (Only org members can be part of a team.)
- Sensitive repositories should be monitored for vulnerabilities in their supply chain. Private repositories should opt in to this monitoring.
- Automatic PRs to remediate vulnerable packages should be enabled whenever available.
- A developer should be designated to triage all reported dependency vulnerability alerts.
- When appropriate, vulnerabilities which do not apply to the usage in that repository should be resolved with the reason documented.
- Project release criteria should include verifying no outstanding vulnerabilities are unresolved. At a minimum, we recommend this applies to those assigned "critical" or "high" severity.
Implementing all of these recommendations can be a major task for existing projects. Following are recommendations for an implementation order.
The top 3 recommendations should be implemented first:
- Use of 2fa by everyone associated with the sensitive repository.
- Implementing signed commits and tags into your workflows.
- Hosting in a Mozilla staff managed organization.
The other recommendations should follow as soon as practical.
-
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.
-
Threat Model gives more details on how a hijacked 3rd party app might be able to gain additional user permissions.
-
Support for GitHub login names.
Currently, it is not possible to enter a GitHub login in a manner that is programatically retrievable. Bugs are on file to remedy this, but the feature has not yet been deployed.
-
GitHub documentation of interest:
- Commit Restrictions
- Branch Protection Help
- GPG Signing for commits and tags