Integrating Inspect into the GitHub Pull Request Workflow

This article is an overview of how you can integrate ShiftLeft into your GitHub workflow, so Inspect analyzes your code automatically whenever you create a new Pull Request (PR), and CircleCI builds your application. The ShiftLeft analysis process is a post-build job.

Prerequisites

We assume that you have CircleCI and GitHub accounts and that you're using Git as the version control system for your source code.

If you're prefer to use Jenkins instead of CircleCI, please refer to the following video for instructions:

Step 1: Create the GitHub Repository

You will need to have a GitHub repository that contains your source code, and your repository should include the .circleci/config.yml file that CircleCI looks for when building your application.

Inspect's analysis is a post-build job, and you can add this functionality to your CircleCI workflow by including the ShiftLeft Orb. If this is the first time you’re using a third-party Orb, you’ll need to opt into using third-party Orbs.

Step 2: Provide Your ShiftLeft Credentials to CircleCI

Please make sure that you’ve created the SHIFTLEFT_ORG_ID and SHIFTLEFT_ACCESS_TOKEN environment variables so that CircleCI can communicate with ShiftLeft. You can get the values for these variables via the ShiftLeft Dashboard (click on the User icon in the top-right and click Account Settings).

Step 3: Configure Your Repository

You will need to make the following changes to the repository where you will be pushing your code changes:

  1. Enable the GitHub Checks CircleCI setting

  2. Set your branch protection rules. To do so, navigate to your GitHub repository. Go to Settings > Branches and under the Branch protection rules area, click Add rule

  3. Enter * under Branch name pattern to make sure that the rule applies to all branches

  4. Under Protect matching branches, check the Require status checks to pass before merging option and select the status checks that you want to be required under the Status checks found in the last week for this repository heading

  5. Scroll to the bottom of the page and click Create to proceed

At this point, CircleCI will automatically build and test your newly-created Pull Requests.

Step 4: Call ShiftLeft for Your Results

Once Inspect has analyzed your code, you can call the ShiftLeft Vulnerabilities API for the results of Inspect's analysis. ShiftLeft tests its findings against your build rules, which are used to test for the existence of vulnerabilities classes, and your build rules are based on the filters you create. In essence, you are providing ShiftLeft with the parameters that you find acceptable for your implementation.

You can trigger specific actions to occur based on these results. For example, you can choose to fail a build, trigger an email or Slack notification alerting your staff to the presence of vulnerabilities in your code, or some combination thereof.

Step 5: Review Your Results

If desired, you can manually review the results of an Inspect analysis. In its results output, Inspect will provide you with a URL you can use to access the ShiftLeft Dashboard, which displays the vulnerabilities found.

For each identified vulnerability, you can set its status to indicate what (if any) work is needed. ShiftLeft offers the following status values:

Status

Description

Assign

Indicates that the vulnerability has been assigned to a responsible party. The Dashboard will also display that person's name

Fixed

The identified vulnerability has been fixed; no further work is needed

Ignore

The identified vulnerability will be ignored

We also recommend using the vulnerability management system of your choice to track work that has been done regarding identified vulnerabilities, as well as work that is needed. For items marked as Ignore, you can choose to modify your ShiftLeft policy to ignore those types of vulnerabilities.