GitHub Organisation Structure

Ebury’s current GitHub organisation does not implement repository access control rules to limit access. This results in organisation members having permissive privileges on repositories well beyond their job requirements. This RFC proposes an improved GitHub structure that incorporates the principle of least privilege and segregation of duties to improve access management and maintain secure accessibility of repositories to members of the organisation.

Prerequisites

To complete this project, a GitHub organisation is required as well as active members that are part of it. These requirements are met considering Ebury’s GitHub organisation.

Reference Documents

Reference Document Location
Jira Epic SECENG-558

Problem Description

Ebury’s GitHub organisation aims for a full visibility source code policy. Although it can be a good approach, following the principle of least privilege should be a mandatory requirement. The technology team is the central unit controlling access to repositories. Thus, any employee added to that team will have complete visibility to almost all the repositories.

Ebury protects repositories by setting certain branch protection rules and requiring new contributions to be submitted via Pull Requests (PR). These mechanisms can help protect repositories, but it can become useless if permissions on these repositories are not correctly managed. For instance, if a team or developer are given administrative privileges, it is possible for them to disable these security settings. This may result in merging source code that has not been reviewed following our guidelines, established in the Code Review Guidelines code-review-guidelines, missing potential security vulnerabilities and bad coding practices.

The need of implementing a Secure Software Development Lifecycle (SDLC) was written in a separate RFC. Although an open policy is applied on GitHub to satisfy everyone can access everything, the concern of someone exploiting active vulnerabilities should be considered a security risk.

Also, external consultants are added to the company as regular employees. Currently, access controls do not distinguish between these users and they will be able to see most of the repositories if they are added to the technology group.

With this RFC, the SECENG team aims to improve the security of the code hosted on GitHub and implement access controls to grant the level of access required by teams.

Background

GitHub provides several ways of managing an organisation. First of all, repositories can be configured as Public, Internal or Private, to reduce the visibility of the content.

  • Public repositories can be seen by anyone.
  • Internal repositories allow any member of the organisation to access them. This visibility option is only available on organisations.
  • Private repositories limit access to only specifically allowed users or teams. Private repositories can be used in combination with access controls to restrict who and how the repository can be accessed (read, triage, write, maintain or admin).

A small set of repositories are configured with public visibility. That means, any GitHub user could get access to them. Most of the repositories set to public were forked to perform customisations on them, although not all. The problem with forked repositories is that visibility is dependent on the visibility set on the parent repository. That means public repositories can only be forked and kept as public repositories. Unless it is necessary these repositories should be configured to be internal or private to prevent exposing unnecessary code publicly.

At the moment, repositories are set to private but access is granted by adding any user to the technology group. This configuration allows nearly all users to access all repositories and is similar to having all the repositories set to internal. As a result, all access controls are lost in the process, since there is no way to organise the repositories per team since they all belong to the same (technology).

To grant permissions to users, GitHub offers multiple types of repository roles:

  • Read. Recommended for non-code contributors who want to view or discuss your project.
  • Triage. Recommended for contributors who need to proactively manage issues and pull requests without write access.
  • Write. Recommended for contributors who actively push to your project.
  • Maintain. Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
  • Admin. Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository.

Repositories at Ebury are generally configured with branch protections, especially on the master branch. These protections help control who can push changes to a project by requiring changes to be submitted via PRs. For this reason, most repository roles are not a big concern, except for admin members, who will be able to disable these settings and bypass branch protections. To prevent the abuse of repository admin privileges, later in this RFC, a solution is proposed. A subsequent RFC will be written to propose the minimum requirements branch protections should implement on every repository.

The members of an organisation can be grouped in Teams. GitHub also provides nested teams which offer a wider level of access controls and organisation structure. Child teams inherit the parents' permissions but an extra layer of restrictions can be added to child teams. That scenario is perfect for Ebury’s organisation. A department can be composed of several teams. Repositories can then be added to a certain team, or directly to a department if wider access is required. Then, access controls can be implemented to other teams and departments that need cross-access to repositories.

Solution

This RFC starts with the following premises:

  • Full read/write access should be granted to anyone in Ebury's GitHub organisation;
  • Changes to master should be submitted via Pull Request (PR);
  • PRs should pass a review process from the code owners.

Due to the requirement of giving full visibility to source code to Ebury's organisation members, the technology team can already be used to manage accessibility. However, members can also belong to different teams and it is mandatory to verify teams and members are assigned non-admin permissions.

Sometimes managers and/or team leads may need to apply updates to repositories. In order to avoid requiring a ticketing system to manage these changes and instead of assigning them admin privileges, the maintainer role was found to be a perfect candidate to perform such operations. If the maintainer role does not fulfill all the needs teams may have, a custom role can be created. Should this be the case, the RFC will be updated to include this information.

GitHub supports nested teams. That means an employee can be a member of a team, and the team can be part of a wider department. A representation of this configuration is shown below:

github-repository-access-controls

Figure 1 - Access control implementation on GitHub repositories.

According to Figure 1, the employee is a member of the Money Flows team due to be part of one of the child teams, PAY or ABC. Repositories can be set to a parent team, in this case, Money Flows. With that configuration, the level of access will be kept within the parent team and any member of the child teams will be allowed to access the repositories of their colleagues. That means repositories will be accessible by the entire department.

The previous structure is proposed as optional. Should a team or department decide to work on a private repository only accessible by certain members, the repository can be added directly to a team (such as PAY or ABC), or to the parent team (department), in case it should be shared across the entire department. Of course, exceptions can be configured and other teams can be granted access. As it may be obvious on Figure 1, the employee will not be able to access any repository that belongs to the Platform team, unless explicit permissions are granted.

Regarding team memberships, employees should only be added to child teams. In certain cases, it might be necessary to add a user to a parent team. As an example, a team lead might require full visibility of other child teams. Thus, it is proposed that parent teams are kept empty, and only Team Leads are added to them. A Money Flows department structure is proposed in Figure 2.

github-department-structure

Figure 2 - Money Flows team GitHub structure example.

From Figure 2, we can see the following:

  • Only ABC and PAY team leads are members of the Money Flows GitHub team;
  • The Money Flows GitHub team is set as parent of the ABC and PAY teams;
  • Only ABC team members will have access to Repository A and Repository B;
  • Only PAY team members will have access to Repository C;
  • ABC and PAY team leads will have access to every repository under money flows;
  • If cross-team access should be limited, it can be controlled within the team’s visibility.

Inheritance should be taken into account, since child teams may inherit permissions from their parents. As an example, a parent team that is given administrative permissions over certain repositories could potentially extend these access levels to its child teams. Thus, employees may inherit these permissions, enabling them to perform unauthorised actions, such as disabling security measures or circumventing Ebury’s processes.

GitHub repository permissions should also be considered when assigning a repository to a team. Repository roles such as read, write and triage are not considered dangerous since repositories should be configured with branch protection rules, requiring changes to be approved during PR reviews. However, admin permissions might be dangerous and can be maliciously used to bypass branch protection rules, such as the need to pass a review before merging a PR to master. Hence, it is recommended to remove repository administrators. As it was mentioned previously, Team Leads may need more permissions to manage repositories. To do so, GitHub facilitates the maintainer role. In the future, if the maintainer role is not enough in terms of permissions, a custom role(s) can be created to aid satisfying the requirements. An update of the RFC will be released accordingly should a change be done.

Repository visibility should also be managed. Currently, there are 52 repositories that are set to public, most of them being forked from public repositories, indicating these repositories can be accessed by anyone on the Internet. Forked repositories visibility can only be set to the parents’ visibility. Since most of the forked repositories are related to public repositories, only public visibility can be configured.

Depending on the license of the repository, it might be possible to modify, distribute and use it privately, letting it available for commercial purposes as well. When the license permits, instead of keeping repositories public, Ebury must import them into private repositories. Thus, the public footprint of Ebury will be reduced and its risk to Internet attackers reduced. When the actions above are established, contributions via forked repositories to public projects will not be possible since we will be making changes to an Ebury owned private repository. However, developers can still contribute to open source projects from their personal forks.

From the set of public repositories, some of them require to be publicly accessible (i.e.: chamaleon and huha) due to its open-source nature. Others might be required to be public, but it will be required to be justified. To control public and forked repositories, teams are required to submit a ticket to BAS in the following form, by going to Other Cloud applications > GitHub.

Considering the above, repositories must remain internal or private, unless it is strictly necessary (and justified).

Considering the above, it is suggested to keep the technology team as the central unit to control access to repositories. However, teams within technology inherit permissions from the parent team, meaning that children teams will not provide any advantage on managing permissions and repository access. For this reason, it is proposed to move out children teams from technology and use them as a way to provide a mapping between the teams and the repositories they own. Thus, users will belong to two teams: their own team/department and the technology team. In this way, everyone will have access to every repository and inheritance issues will not occur,making it easier to identify what team owns a repository and inheritance errors.

With the examples showed above and to implement such structure, the following action plan is proposed:

Action Plan

The following action plan is proposed to successfully reorganise GitHub, reducing the impact to its users as much as possible:

  1. Map users with the teams and departments they belong to. Progress can be tracked on a Google Spreadsheet;
  2. Create the teams and departments on GitHub;
  3. Assign each user with the teams and departments they belong to;
  4. Revisit admin privileges granted to users and teams to reduce them when possible.
  5. Add every repository to the technology team;
  6. Grant write permissions to members of the technology team;
  7. Ask Team Leads to collect a list of repositories actively maintained by the teams;
  8. Add the repositories listed by Team Leads to the teams and departments;
  9. Implement maintainer access controls;
  10. Revisit repositories visibility. Set public repositories to internal or private unless public visibility is necessary (considering forked repositories);
  11. Reduce the number of GitHub owners;
  12. Clean up old repositories that are no longer used;

Users are already mapped to their teams and tracked on a spreadsheet. Most of Team Leads have been contacted in the process so they are already aware of the actions proposed by this RFC.

The proposed action plan will also help identify repositories that are outdated and no longer used. That could trigger clean up operations to get rid of them and reduce the amount of repositories we should maintain. Additionally, administrators should be reviewed to also clean up excessive permissions granted to users.

Success Criteria

The new GitHub structure implementing access control will considered to be successful in the following cases:

  • Technology team members have write access to all repositories;
  • Users are organised in teams and departments;
  • Repositories are assigned to the respective teams and departments;
  • Clean up operations are conducted to remove old teams, permissions and repositories;
  • Access control rules are implemented to minimise accessibility to repositories;
  • Administrative permissions are restricted to a limited set of users;
  • Repository admins are completely removed;
  • GitHub owners actively maintain the proposed structure.

Alternatives

The only alternative possible is to continue with the current configuration. In that case, access controls will not be implemented and broken accessibility controls to repositories will be configured.

Caveats

Following the action plan proposed, caveats should be reduced to a minimum. However, taking into account the current organisational structure, some users may experience visibility problems on certain repositories while teams and departments are created. It should not be the case if the technology team is maintained. In any case, visibility issues can be quickly fixed by administrators, including the Security Engineering team.

Operation

After the action plan has been conducted, future maintenance of GitHub will be performed by submitting tickets. Below, several scenarios are evaluated:

  • Adding/removing new users. Managing these operations via tickets will permit us to keep track of the changes and add new actions to the owner’s team backlog. Even though that might add extra actions to the teams involved, actions should take less than a minute and will provide a lot of benefits, including an easy to maintain solution as well as better security.

  • Adding/removing user to a team. A ticket should be submitted to request to be added to a team providing details. When a user is created, it will be necessary to add him to the technology team to grant access to repositories, and to the team it belongs, to provide a better organisational structure. If necessary, the Security Engineering team will provide guidance to the service owners to continue implementing the principle of least privilege on our GitHub organisation.

The Security Engineering team has been working with DXP, BPA and BAS, expected to share the ownership of GitHub, to agree on the proposed action plan. GitHub ownership is not clear at the moment and a document to state clear responsibilities is under development. In the future, DXP will own the organisational management of GitHub, BAS will provide support and BPA will provide automated tools to manage repositories, users and teams.

To provide support, BAS can be contacted on this form by going to Other Cloud applications > GitHub.

A collaborative approach is suggested on all the tasks defined in the RFC. 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. Nevertheless, if they experience problems accessing certain repositories, the Security Engineering team as well as DXP will help them in the process, reducing the impact to a minimum.

Data Contracts

The new GitHub structure will not affect any data source.

Deployment

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

Dependencies

There are no dependencies affecting the new GitHub structure proposal.

References

  • Repository visibility: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility
  • Forked repositories visibility: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks
  • Repository access controls: https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization
  • Nested teams: https://github.blog/2017-06-13-nested-teams-add-depth-to-your-team-structure/
  • SSDLC RFC: https://github.com/Ebury/ebury-blueprints/blob/63244d5ac6071635d1ba406f18dc974fe6130236/docs/processes/ssdlc-process.md
  • Code Review Guidelines: https://github.com/Ebury/ebury-blueprints/blob/master/docs/processes/code-review-guidelines.md
  • Code Ownership: https://github.com/Ebury/ebury-blueprints/blob/master/docs/processes/code-ownership.md