Nexus IQ for GitHub

Overview

Nexus IQ for GitHub puts the information needed to quickly remediate vulnerablities in software solutions at the fingertips of developers by pushing policy evaluation information into GitHub commits and pull requests, where developers work.

When a policy evaluation is requested against a Git commit, the policy evaluation violation counts for components affected are summarized on the commit in GitHub. This can be seen on pull requests or on indivdual commits.

Above is an image of the IQ Policy Evaluation as seen on a GitHub pull request. A link to the full IQ Policy Evaluation report is available by clicking the Details link to the right of the components affected summary counts.

As a GitHub Status, an IQ Policy Evaluation check that results in vulnerable components can be configured to disallow a pull request from being merged into the target branch of a GitHub Repository in GitHub Settings.

Clicking the Details link opens the IQ Policy Evaluation report where the developer will see the current version used and other vulnerable and non-vunerable versions of that component.

This gives developers the information they need to quickly remediate vulnerable components at their finger tips.

Minimum Steps

The minimum steps to view Nexus IQ Policy Evaluation results on a GitHub commit or pull request are as follows:

  • Create a GitHub access token, with repo:status permissions, to allow Nexus IQ Server to send GitHub commit status messages to the GitHub repository commit.
  • Create a Source Control entry that connects a Nexus IQ Server application to the GitHub repository and access token.
  • Run Policy Evaluations for the application, that include the current commit hash.
  • View the Policy Evaluation reports and result summaries from GitHub.

Configure Nexus IQ for GitHub

Nexus IQ for GitHub provides an API for configuring repositories for IQ Policy Evaluation.

Each application in Nexus IQ Server setup for Nexus IQ for GitHub will need source control information consisting of a GitHub repository url and an access token. The Nexus IQ Server REST API will be used to configure the application's repository information.

Adding Repositories

Creating a GitHub Access Token

GitHub repository information is needed in order for Nexus IQ for GitHub to post GitHub status checks for a GitHub commit. The information needed is the repository url and the GitHub generated access token, with repo:status permissions, in GitHub Settings / Developer settings / Personal access tokens.

Copy the access token created as it will be needed to create the Nexus IQ for GitHub Source Control entry.

Creating a Nexus IQ for GitHub Source Control Entry

The application in IQ Server will need to be associated with the source control system that hosts the associated project.  In order to do this the information described above (GitHub project url and access token) need to be pushed into IQ Server.

Retrieving the Nexus IQ Server Application Identifier

A web service is provided in order for you to provide this information to IQ Server.  You can manually create this 'source control entry' in IQ as described below.

First, however, you'll need to obtain the application ID for the application on IQ Server.

curl -u <username>:<password> http://<iq server url>/api/v2/applications?publicId=<public id>

example,

curl -u admin:admin123 http://172.16.16.5:8070/api/v2/applications?publicId=WebGoat

The response will look something like this,

{
  "applications":[
    {
      "id":"432a297b263a45139d3a71381eed9457",
      "publicId":"WebGoat",
      "name":"WebGoat",
      "organizationId":"6cf046750b564d86a001c2d71ccc7f0f",
      "contactUserName":null,
      "applicationTags":[]
    }
  ]
}

The application id is the value of the "id" attribute returned.

Creating the Source Control Entry

Now that you have the internal application ID you can use that to create the source control entry on IQ Server.

curl -u <username>:<password> \
-d '{"applicationId": "<application id>", "repositoryUrl": "<repository url>", "token": "<access token>"}' \
-H "Content-Type: application/json" \
-X POST http://<iq server url>/api/v2/sourceControl/<application id>

example,

curl -u admin:admin123 \
-d '{"applicationId": "432a297b263a45139d3a71381eed9457", "repositoryUrl": "https://github.com/my-org/my-repo/", "token": "0c005b687eee16fb2bb6c3bca3607995e971f19b"}' \
-H "Content-Type: application/json" \
-X POST http://172.16.16.5:8070/api/v2/sourceControl/432a297b263a45139d3a71381eed9457

Listing Nexus IQ for GitHub Source Control Entries

To retrieve a Nexus IQ for GitHub source control entry, run the following command:

curl -u <username>:<password> http://<iq server url>/api/v2/sourceControl/<application id>

example,

curl -u admin:admin123 http://172.16.16.5:8070/api/v2/sourceControl/432a297b263a45139d3a71381eed9457

The response will look something like this,

{
  "id":"9412eb8efc4849a6ab04cfb4cad12ae6",
  "applicationId":"432a297b263a45139d3a71381eed9457",
  "repositoryUrl":"https://github.com/my-org/my-repo/",
  "token":"#~FAKE~SECRET~KEY~#"
}

Updating a Nexus IQ for GitHub Source Control Entry

Updating a Nexus IQ for GitHub source control entry is very similar to creating the entry. Use the response from the list command above and make updates.

curl -u admin:admin123 \
-d '{"id":"9412eb8efc4849a6ab04cfb4cad12ae6","applicationId":"432a297b263a45139d3a71381eed9457","repositoryUrl":"https://github.com/:org/:repo/","token":"99995b687eee16fb2bb6c3bca3607995e9719999"}' \
-H "Content-Type: application/json" \
-X PUT http://172.16.16.5:8070/api/v2/sourceControl/432a297b263a45139d3a71381eed9457

Deleting a Nexus IQ for GitHub Source Control Entry

Deleting a source control entry will cause features, e.g. GitHub status checks, to no longer run for the GitHub repository.

To delete a Nexus IQ for GitHub source control entry, run the following command:

curl -u <username>:<password> \
-X DELETE http://172.16.16.5:8070/api/v2/sourceControl/<application id>/<source control id>

example,

curl -u admin:admin123 \
-X DELETE http://172.16.16.5:8070/api/v2/sourceControl/432a297b263a45139d3a71381eed9457/9412eb8efc4849a6ab04cfb4cad12ae6

Run a Policy Evaluation Request

Using the Nexus IQ CLI

Nexus IQ for GitHub leverages a new --metadata-file, -m parameter added to the Nexus IQ CLI that allows a file containing JSON to be passed into the policy evaluation request. This gives Nexus IQ for GitHub the information it needs to send GitHub Status checks to GitHub commits.

Here is an example use the of the Nexus IQ CLI for Nexus IQ for GitHub:

java -jar ./nexus-iq-cli-<version>.jar -i Test123 -s http://localhost:8070 -a username:password -t release -m metadata.json sample-application.zip

Please see the Nexus IQ CLI documentation for details.

Currently, the metadata consists of a single, required 'commitHash' entry, as shown here:

{
  "commitHash": "79bc00d647f2d4ddc71a9730845e11bb25d2c238"
}

To create a metadata.json file from the command line in the git project folder:

export COMMIT=$(git rev-parse HEAD); echo "{\"commitHash\": \"${COMMIT}\"}" > metadata.json

View the Nexus IQ Policy Evaluation Report from GitHub

The IQ Policy Evaluation report that was run for the last commit of a pull request can be accessed by clicking the Details link to the right of the IQ Policy Evaluation component summary line.

The IQ Policy Evaluation report can also be accessed from a commit by clicking the status icon then, clicking the Details link to the right of the IQ Policy Evaluation component summary on the checks popup.

Protecting the Target Branch in GitHub Project Settings

The target branch can be protected from merges with a failing IQ Policy Evaluation by configuring a branch protection rule in the repository's settings under Branches.

In the branch protection rule, add a new rule or edit an existing rule then, check Require status checks to pass before merging then, check IQ Policy Evaluation.

The IQ Policy Evaluation status check will not appear in the list of status checks found in the last week for this repository until the first policy evaluation status has been added to the repository.