Securing GitHub organizations

Interior view of Stockholm Public Library via wikimedia.org

If your security team is concerned about supply chain risk, it’s a good idea to look at your GitHub settings. GitHub describes several security features and best practices in their documentation for account security and organization security, but this post goes beyond the documentation. It’s a step-by-step process for securing your GitHub organization.

This guide is based on GitHub Enterprise Cloud — other products may have different features.

Reduce organizational owners

First, ensure your GitHub organizational owners group is well-defined. Fewer owners reduces the risk of account takeover. It’s also easier to communicate security standards and ensure people follow them. You will spend time and effort getting security settings to an ideal state. An unaware administrator can make changes that waste that time and effort. Consider all organizational GitHub roles: billing managers, security managers, and app managers.

Be warned — removing owners can break workflows and slow down the team. Send out a survey or interview each owner to see what access they need. Create manual or automated processes to delegate common GitHub owner actions. Build consensus with leadership for these changes. Communicate them to the engineering team to avoid blowback.

Setup configuration as code

Infrastructure as code tools like Terraform helps enforce safe change management. You can gate changes behind a review and approval process. You can determine who made a previous change and revert it. You can scale modules of configuration across teams and repositories. Here are a few articles about how Terraform can manage GitHub:

• Managing Github permissions with Terraform
• Using Terraform Cloud to Manage GitHub Repositories
• How to manage your GitHub Organization with Terraform

Terraform is not an all-or-nothing decision. Not all GitHub configurations need to use Terraform. Pick the riskiest and most complex areas of configuration and use Terraform. Manage the rest through the web. You’ll need to create a GitHub service account to use Terraform. I’ll discuss service accounts in more detail below.

Setup log auditing

You can use Github audit logs to ensure your standards are being followed. For example, how will you know if someone adds an unapproved administrator? You can perform regular manual reviews of the audit log for your organization. It’s even better to export the logs to a SIEM with alerting capabilities using the GitHub Audit Log API.

Enforce 2FA

You should require two-factor authentication in your organization. Communicate the change to the team beforehand. Make sure to include details of how to recover your account if you lose your 2FA credentials. Two-factor authentication is a well-recognized part of modern account security strategy.

Understand how SAML and 2FA play together. GitHub two-factor enforcement applies to the GitHub user. Authenticating via SAML will have a separate 2FA step from the identity provider. This is because one GitHub user could have multiple SAML identities. See two-factor authentication and SAML single sign-on.

Turn on SAML as option

Next, you can enable (but not require) SAML single sign-on for your organization. Make sure to communicate this change in advance to users, since it can be quite disruptive. A user will sign in to GitHub and associate their GitHub account with the SAML identity provider. Afterwards, they’ll need to sign in to the SAML identity provider for all GitHub access to your organization. Keep an eye out for broken integrations during this transition. Personal Access Tokens and SSH keys will stop working until the user enables them for SAML. Users will also need to re-authenticate to any OAuth applications.

It’s strongly recommended to use Enterprise Managed Users. However, many organizations have GitHub users use their personal account. It can make life easier as a developer to keep a single persistent identity.

At this point, SAML is available but not required. Make sure to follow the next steps before you enforce it.

Migrate external users to collaborators

Consider users on your GitHub team who are not a user in your identity provider. They will either need accounts in the identity provider or you should convert them to an outside collaborator. Note that if you enforce 2FA, outside collaborators will also have to have 2FA.

Create service accounts in your identity provider

Some GitHub users don’t correspond to real people. We call these users “service accounts”. You want SAML for all users, so you need to create these bots and service accounts in your identity provider. You can follow guidelines like the ones in my service account standard blog post. You can then connect these service users to your GitHub account using SAML. If you have a service account using SSH, consider using a deploy key. Deploy keys can replace service accounts. They’re also read-only by default, and only apply to a single repository.

Enforce SAML

You’re ready to enforce SAML for all members of your organization. Update your security processes to remove GitHub access for a compromised account. Create a backup plan in case the Identity Provider is down. See downloading your organization’s SAML single sign-on recovery codes. Review the guide to enforce SAML single sign-on in your organization. Then follow the guide to Enforcing SAML single sign-on for your organization.

Turn on SCIM

Once you’ve enabled SAML, enable SCIM to secure offboarding access. Without SCIM, GitHub only logs out users from their web session when you remove them from your SAML identity provider. They will still be able to use their authorized SSH keys and tokens. If you don’t enable SCIM, ensure that you have an alternative plan. Create a process for removing offboarded users from your GitHub organization.

Sync teams from your identity provider

Once you have SAML enabled, start synchronizing your teams with identity provider groups. Your identity provider should be the source of truth for organizational hierarchy and roles. This will allow you to enforce least privilege access, as defined below.

Determine teams and repository access

Now you’ve combined your GitHub organization and your identity provider. You can build out authorization controls to streamline least privilege access. At large organizations, defining access can be more of an art than a science. First, make sure you understand how GitHub access and roles work:

• Access permissions on GitHub
• Managing teams and people with access to your repository
• Managing custom repository roles for an organization
• Setting base permissions for an organization

Next, consider these guidelines for defining a role-based access strategy for GitHub repositories:

• Categorize your repositories by risk using topics. Identify repositories that access sensitive data. Identify repositories that produce software supply chain artifacts. Focus your security controls your access reduction efforts on the riskiest assets.
• Configure repository access through infrastructure as code. Track changes over time and make consistent changes across repositories.
• Whenever possible, remove humans from the judgment loop of who gets access to what. Define access through organizational position and role information specified in an HRIS.
• Make sure there’s a “golden path” for new repositories. Access and other security settings should be correct out-of-the-box. Use repo templates to standardize good practices.

Next steps

Following the steps above gets you to an authentication and access control baseline. Some next steps for securing your GitHub instance could include:

• Turn on branch protection for repositories
• Consider setting up additional security controls for SSH keys. You can use SSH certificate authorities or Hashicorp Vault to secure SSH credentials.
• Discourage personal access tokens. Use OAuth or GitHub apps instead. It’s easy to drop a PAT somewhere and have it get compromised. If you do have PAT, require users to set expirations or scopes.
• Consider restricting the allowed IP addresses for your organization.
• Audit software publication flows. Are CI and Github actions configured with minimal access? Look at permissions to software artifact libraries like Docker Hub, npm, etc.
• Review OAuth applications in GitHub by reviewing your organization’s installed integrations. Think about implementing OAuth App access restrictions.
• Look to integrate code authenticity mechanisms like commit signature verification.

Addressing software supply chain risk is difficult. Each piece of code you depend on and publish introduces an attack surface. This results in risky code pulling in even riskier code. Do your part in shoring up this vast web of trust by securing your GitHub organization.

Thanks Neil Matatall for the review 🤙