GitHub Branch Protections

Ebury is using Github as its Source Code Management (SCM) solution. There, repositories can be created to manage source code. To protect how changes are made on these applications, GitHub provides Pull Requests (PR) as a solution to promote source code reviews and validate new changes. PRs can be enhanced to require several conditions before they can be approved. The purpose of this RFC is to document the minimal set of branch protections that should be implemented on GitHub before changes are approved and merged to master branches.

Prerequisites

To complete this project, a GitHub organisation is required, with existing repositories that use branches

Reference Documents

Reference Document Location
Jira Epic SECENG-378

Problem Description

While developing new applications, using branches is an extended practice to isolate development work without affecting other branches, or the master branch. Furthermore, branches also help integrate new functionalities into a repository's master branch by submitting pull requests. As any other mechanism, branches can be protected in multiple ways. These protections are deployed per branch by enabling several settings on the repository. However, a lot of repositories do not make use of branch protections.

branch-protections-porkpie.png

Figure 1 - Porkpie’s monitoring repositories that have not been configured with branch protections.

Background

Several good practices have been followed when configuring GitHub repositories. Nevertheless, these practices have not been documented and it has been noticed several repositories are not configured with branch protections. This can be due to a previous migration from Bitbucket, or because branch protections have not been agreed between all the Technology teams. Branch protections are important to secure our applications integrity, and to promote better PR reviews. Also, branch protections are important considering the implementation of Ebury’s SSDLC.

Furthermore, aligning with a previous RFC raised about problems affecting GitHub permissions, on those repositories that had branch protections enabled, users with administrative rights could disable the requirement to submit changes via PR, and merge changes to the master branch without being approved by a reviewer or code owner. There is a setting to disable bypasses such as those by administrators. It is important to note that administrators can disable this protection, and that is one of the reasons why the previous RFC aims to also remove administrative access to our repositories.

To avoid future issues and to require a minimal set of branch protections to be enabled on every repository within Ebury’s GitHub organisation, this RFC proposes what settings should be enabled, providing an automated solution to deploy the settings agreed by Technology and Risk & Security teams.

Solution

All repositories must implement branch protections according to the best practice of submitting changes via pull requests. Based on the SECENG team experience, there are three main minimal settings that should be configured on every repository on GitHub:

Require a pull request before merging.

As a mandatory setting, we must require changes to be applied through PRs. When a PR is created, there are several settings that can be enabled to improve the review process:

  • Require approvals: This option allows you to choose the number of approvals required to accept a PR. Having at least two approvals was agreed with Technology teams. That means two approvals must be granted by people in the team and, one of those, must be granted by a code owner of the repository. For important repositories such as BOS, EBO, FXSuite, terraform repositories, etc, we recommend having a minimum of three approvals, including also a mandataory review of a code owner.
  • Require code owners review: Code owners are responsible for the functionality and operation of the repository where changes are made. Thus, they should review the source code submitted via PRs.
  • Require approval of the most recent reviewable push: the latest changes should be reviewed by another person, without including the person who pushed the changes.

Below you can see a screenshot of how the branch protection would look like.

branch-protections-pr-reviews

Figure 2 - Minimal branch protection settings for requiring changes to be made via PRs.

Although the options recommended above are the minimal that were agreed, there is an additional settings that we encourage teams to enable:

  • Dismiss stale pull request approvals when new commits are pushed: This option will discard approved reviews after changes have been made. Although it can be annoying sometimes, we consider a review should be done on new changes, no matter the size of the change.

The SECENG team recommends enabling this option to ensure the latest changes are reviewed. Otherwise, code updates that have received a previous approval could still be merged to master, even if malicious code or vulnerabilities are added. The SECENG team acknowledge the risk involved in disabling the option and therefore, it will be tracked as a risk.

Require status checks to pass before merging.

Every time a change is submitted to a branch, certain checks are conducted to ensure the code complies with the requirements of the repository. As an example, we could include status checks related to Aquasec or TfSec in this section so all the changes comply with the policies enforced by these solutions. Currently, we do not aim to include Aquasec or TfSec status checks, but we recommend adding status checks in this section if there are any required by the repositories.

branch-protections-status-checks

Figure 3 - Status Checks that should pass before allowing merging.

Furthermore, the option to Require branches to be up to date before merging is also recommended to be enabled when possible. This option will ensure the latest changes from master are in the branch that wants to be merged, avoiding conflicts. Depending on the type of repository, this option might not be helpful. We leave this option open to the teams to decide whether they want to have this feature.

[OPTIONAL] Do not allow bypassing the above settings.

This setting prevents administrators from bypassing the options enabled above. Administrators will no longer exist on our repositories when the changes proposed in the GitHub Organisation Structure RFC are applied. Until then, it is recommended to enable the setting.

Although having this setting can be beneficial in some small repositories, it could pose a problem if we restrict the permissions to people who deal with incidents. Should an incident responder need to merge changes during the night, when no one else is awake to review and accept the changes, or to bypass a status check that fails, the action could be blocked. To avoid that, on-call teams might be considered to have elevated permissions (i.e.: SRE). It should be noted these permissions will only be used in extreme situations, and teams with such privileges must agree on complying with the established pull request review process. If this configuration is accepted, the previous GitHub Organisation Structure RFC will be updated to reflect these changes.

branch-protections-admin-bypass

Figure 4 - Block potential bypasses of the previous settings by administrators.

Action Plan

A script to enable the agreed settings has been created on the SECENG repository. By providing some settings in a config file, minimal branch protections can be deployed automatically in a fast way. Thus, when the RFC is approved, the changes will be implemented on every repository after the changes are communicated to the Technology teams.

Since the creation of repositories is still managed manually, guidelines to the BAS team will be provided to ensure the agreed settings are configured on new repositories.

Should additional settings be added, the tool can be modified and adapted to the requirements agreed on this RFC.

Success Criteria

To consider the RFC a success, old and new repositories should be created with the previous settings enabled at least on the master branch. These settings can also be applied to other branches such as devel or staging, but we accept if branch protections are only active on master branches.

In order to prevent future abuses, the SECENG team will monitor GitHub’s audit log to ensure bypasses do not happen. Furthermore, after the GitHub organisation structure changes are applied, administrators will be reduced to a minimum, and only BAS (owner), DXP (owner) and SECENG (admin) will have elevated privileges on GitHub.

Alternatives

The only alternative possible is to continue with the current configuration. In that case, branch protections will not be enforced on every repository and it is possible that changes are committed to master branches without being reviewed.

Caveats

Following the action plan proposed, caveats should be reduced to a minimum. Luckily, main repositories have been configured with these settings beforehand, and only some additional features might be enabled. For those repositories that have not been configured with branch protections, developers will see changes must be submitted in a different and safer way, but a direct negative impact will not be caused.

Nevertheless, depending on how status checks are configured, those could produce some blockers while deploying new changes.

Operation

After the action plan has been conducted, future maintenance of GitHub branch protections will be performed by submitting tickets to BAS form.

GitHub ownership is shared between DXP, in charge of the maintenance of the service, and BAS, in charge of providing support to teams on their daily operations. Should it be necessary, SECENG can also be contacted to provide security assistance on making changes.

A collaborative approach is suggested with GitHub service owners. Nevertheless, the Security Engineering team can conduct the action plan proposed with little guidance from other teams.

Security Impact

Security will be improved due to the enhancement of access controls which will limit what is exposed to each user. By adopting this proposal and incorporating robust access control mechanisms, Ebury can significantly enhance its overall security posture and protect valuable products. Several advantages are listed below:

  • Enhanced protection of intellectual property: Proper access control measures help safeguard sensitive data and intellectual property, reducing the risk of data leaks, theft, or misuse.

  • Mitigation of insider threats: Implementing adequate access restrictions can prevent employees with malicious intent from accessing, manipulating, or deleting sensitive data, source code, or configurations, thereby protecting the organisation from potential harm.

  • Reduced attack surface: Adhering to the principle of least privilege and granting only necessary privileges to users can minimise the attack surface, making it more challenging to exploit vulnerabilities and access critical resources.

  • Improved monitoring and auditing capabilities: Implementing robust access control measures enables better tracking of user activities, facilitating the detection of suspicious behaviour and timely response to potential security incidents.

  • Compliance with legal and regulatory requirements: Protecting intellectual property and sensitive data by implementing access control best practices helps ensure compliance with industry regulations, avoiding financial penalties and reputational damage.

Performance Impact

Performance should not be impacted following the action plan proposed.

Developer Impact

As it was considered in the Caveats, developers should not experience problems since source code reviews must be performed as part of the teams processes. The goal of this RFC is to establish the minimum settings to protect contributions to repositories. Nevertheless, if they experience problems while updating repositories, the Security Engineering team as well as DXP and BAS will help them in the process, reducing the impact to a minimum.

Data Contracts

The new GitHub branch protections will not affect any data source.

Deployment

The deployment of the new GitHub branch protections will follow the action plan proposed.

Dependencies

There are no dependencies affecting the new GitHub branch protections proposal.

References

  • https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
  • https://seceng.ebury.rocks/ssdlc/github/branch-protection/introduction/
  • https://seceng.ebury.rocks/ssdlc/github/branch-protection/settings/