concept CircleCI in category system administration

This is an excerpt from Manning's book Securing DevOps. Login to get full access to this book.

Let’s summarize your toolkit: GitHub hosts the code and calls CircleCI when patches are sent. CircleCI builds the application into a container and pushes it to Docker Hub. AWS runs the infrastructure and retrieves new containers from Docker Hub to upgrade the production environment to the latest version. Simple, yet elegant.

Starting with GitHub and CircleCI, you’ll learn

The code-management infrastructure shown in figure 6.2 is a common pattern in the DevOps pipeline: a developer uses a code repository, GitHub being the popular example, to host the source code of an application and collaborate with colleagues. To test their code and build application containers, the code repository is integrated with an automated build tool, like CircleCI, Travis CI, or Jenkins, that performs several tasks every time a change is made to the source code.

Figure 6.2 The code-management infrastructure is composed of developers that publish their code in GitHub and run automated tests and builds in CircleCI. Each component provides access control that must be used to increase the security of the pipeline.

CircleCI shows Sam a Log In With GitHub button, which Sam clicks.

Sam is redirected to GitHub and prompted with an authorization request that reads “CircleCI would like to access your GitHub account, do you want to authorize access?” GitHub also shows the permissions CircleCI is requesting: access to personal user data and read/write access to all public and private repositories. This authorization prompt is shown in figure 6.5.

Sam agrees by clicking the Authorize button, and GitHub redirects her back to CircleCI with a code that CircleCI can use to access her account.

CircleCI verifies the code and authenticates Sam.

Figure 6.5 The GitHub authorization page prompts Sam to delegate access to all her repositories to CircleCI.

The critical step here is obviously step 3, where Sam grants broad permissions to CircleCI. This is what OAuth calls the “scope.” From an HTTP perspective, when CircleCI redirected Sam to GitHub for authentication, it sent her to the address shown as follows.

Listing 6.1 CircleCI oauth redirect to GitHub

https://github.com/login/oauth/authorize?client_id=78a2bb    #1  
&redirect_uri=https://circleci.com/auth/github?return-to=%2F    #2  
&scope=repo,user:email    #3  
&state=-1LihwQWDoFd    #4  

#1   Location of the oauth authentication endpoint at GitHub
#2   URL that users are redirected to after authenticating with GitHub
#3   Scope of permissions requested by CircleCI
#4   CSRF token

copy

You may recognize the client_id, redirect_uri, scope, and state fields we discussed in chapter 3. Take a closer look at the scope field and its value: repo,user:email. The list of requested scope is comma-separated, and CircleCI is requesting access to repo and user:email. The documentation over at GitHub tell us the following about these scopes: user:email grants read access to a user’s email addresses. repo grants read/write access to code, commit statuses, repository invitations, collaborators, and deployment statuses for public and private repositories and organizations (https://developer.github.com/v3/oauth/).

By logging in to CircleCI, Sam delegated to it a set of permissions that grant full control over her repositories. Should the oauth token stored by CircleCI leak, an attacker could use it to take control and modify Sam’s applications on GitHub. This is obviously worrisome.

As far as we know, CircleCI has no reason to write code, so why is it requesting such broad permissions on Sam’s account? Typically, there are two reasons for this: either the identity provider doesn’t support granular permissions, or the application wants the ability to do more for the user. It’s all too common for OAuth-integrated applications to possess a lot more permissions than needed, or that the user would normally be comfortable delegating. You should manually audit these integrations and verify if they put your security at risk, for example, by delegating sensitive accesses to third parties you may not trust.

Permissions between GitHub and CircleCI

GitHub provides granular scopes such as write:repo_hook to create webhooks, and write:public_key to create SSH deployment keys, which should fulfill the needs of CircleCI. We can assume CircleCI is asking for broader permissions to do more for the user. CircleCI uses the broad repo scope to read permissions from GitHub and decide who can make changes to CircleCI projects based on their privileges on GitHub.

After permissions are enabled for your organization, only GitHub repo admins or GitHub owners will be able to make changes to project settings on CircleCI. This is useful for larger teams to make sure your project settings are only changed by team members who have admin access.

In effect, CircleCI not only uses oauth to log the user in and create webhooks on their behalf, but it also uses oauth to check which permissions Sam has on the repository. If Sam is an admin or has write access to the repository, she’s permitted to change settings on the CircleCI side of the project. This is a powerful feature, as it centralizes permissions management in GitHub instead of creating a second layer in CircleCI.