Nexus IQ for Git

Overview

Nexus IQ for GitHub/GitLab puts the information needed to quickly remediate vulnerablities in software solutions at the fingertips of developers by pushing policy evaluation information into the SCM 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 status. This can be seen on pull requests or on individual commits.

GitHub

Here 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 (see below for more details).

GitLab

Here is an image of the IQ Policy Evaluation as seen on a GitLab commit. A link to the full IQ Policy Evaluation report is available by clicking on 'IQ Policy Evaluation'.

GitLab can be configured to prevent merge requests from being merged if there is a pipeline failure, which could be caused by a policy evaluation failure.  See the sections below on protecting target branches for more information.

Nexus IQ

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.

Setting up Nexus IQ for Git(x)

The steps required to view Nexus IQ Policy Evaluation results for a GitHub or GitLab commit or pull request are as follows:

Create an access token for your source control management (SCM) system

GitHub Access Token

Permission for IQ server to communicate status to your GitHub instance is granted via a GitHub access token with the repo:status scope enabled.  In GitHub the access token is generated in Settings / Developer settings / Personal access tokens.

Reminder: the token needs to have the  repo:status scope enabled.  Copy the access token somewhere safe for later use as once you leave the generate token dialog you will not be able to view it again.

GitLab Access Token

In GitLab a personal access token is created as follows:

  1. Log in to GitLab.
  2. In the upper-right corner click your avatar and select Settings.
  3. On the User Settings menu select Access Tokens.
  4. Choose a name and optional expiry date for the token.
  5. Choose the api scope.
  6. Click the Create personal access token button.
  7. Save the personal access token somewhere safe. Once you leave or refresh the page you won’t be able to access it again.

Inform IQ Server about your access token

Retrieving a Nexus IQ Server Organization Identifier

In order to interact with the Nexus IQ source control API you'll need IQ server's identifier for the organization you're interested in.  

Use the following API to discover the ID of an organization:

curl -u <username>:<password> http://<iq server url>/api/v2/organizations

This will produce content like the following which includes the organization IDs for the organizations the given user is authorized for:

{
  "organizations":[
    {
      "id":"6cf046750b564d86a001c2d71ccc7f0f",
      "name":"Sandbox Organization",
      "tags":[
      ]
    }
  ]
}

Creating the Source Control Entry for an Organization

To create the source control entry use the source control organization API with the `organizationId` returned from the previous API call, as so:

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

Example:

curl -u admin:admin123 \
-d '{"token": "0c005b687eee16fb2bb6c3bca3607995e971f19b", "provider": "GitHub"}' \
-H "Content-Type: application/json" \
-X POST http://172.16.16.5:8070/api/v2/sourceControl/organization/6cf046750b564d86a001c2d71ccc7f0f

Hereafter, when a policy evaluation request comes in for any IQ application in that same organization Nexus IQ for Git will use the specified access token to communicate status information back to your repository.  

Run a policy evaluation

Policy evaluations can originate from your CI environment, such as Jenkins, utilizing the IQ CLI directly or one of the Nexus IQ plugins provided for your respective CI system.  See this page for more information:  https://help.sonatype.com/integrations/nexus-and-continuous-integration

You can also run a policy evaluation using the Nexus IQ command line interface (CLI) directly, as described here:  https://help.sonatype.com/integrations/nexus-iq-cli

The Nexus IQ client tooling will determine the commit hash and repository details for the given build and include that information in the policy evaluation request sent to IQ server.  

On top of the Evaluate Applications permission, a user needs the View IQ Elements and Edit IQ Elements permissions in the designated parent organization to be able to automatically onboard applications in Nexus IQ for Git through policy evaluations.  The user must have the correct role assigned for the required permissions to be granted.

View the Nexus IQ Policy Evaluation Report 

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 itself by clicking the status icon then clicking the Details link to the right of the IQ Policy Evaluation component summary on the checks popup.

GitLab

The IQ Policy Evaluation report that was run for the last commit of a pull request can be accessed by clicking on the pipeline status for the respective stage (i.e. IQ Policy Evaluation).

Protecting the Target Branch

The target branch can be protected from merges with a failing IQ Policy Evaluation as described in the appropriate section below for your SCM system.

Protecting the Target Branch in GitHub

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.  Next, check Require status checks to pass before merging.  Finally, 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.

Protecting the Target Branch in GitLab

GitLab projects can be configured to prevent merge requests from being merged if their pipeline did not succeed.  A failing IQ policy evaluation will cause the pipeline to fail, which in turn will prevent the merge request from being able to be merged.  You can enable this feature via the project settings as shown below.  See this page for more information:  https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds

Additional Nexus IQ Source Control API Operations

Retrieving a Nexus IQ Server application identifier

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 a Source Control Entry for an application

If you need to use a different access token for a given repository or if that repository belongs to a different Git source control manager, like GitLab for instance, you'll need to create a repository specific source control entry, like so:

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

Example:

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

Retrieving the Source Control Entry for an application or organization

To retrieve the existing source control entry for a given IQ application or organization run the following command:

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

Example:

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

The response will look something like this:

{
  "id":"34b7f72b18ea45f4987241e79cd2af53",
  "ownerId":"223ae9684c1b4515975ae7226f32a4ea",
  "repositoryUrl":"https://github.com/my-org/my-repo",
  "token":"#~FAKE~SECRET~KEY~#",
  "provider":"github"
}

Updating a Source Control Entry

Updating a source control entry is very similar to creating the entry. Use the information in the response from the list command above to make an update, as so:

curl -u admin:admin123 \
-d '{"repositoryUrl":"<repository url>","token":"<access token>", "provider": "<GitHub | GitLab>"}' \
-H "Content-Type: application/json" \
-X PUT http://172.16.16.5:8070/api/v2/sourceControl/<scope: application | organization>/<scoped id>

Example:

curl -u admin:admin123 \
-d '{"repositoryUrl":"https://github.com/:org/:repo/","token":"99995b687eee16fb2bb6c3bca3607995e9719999","provider":"GitHub"}' \
-H "Content-Type: application/json" \
-X PUT http://172.16.16.5:8070/api/v2/sourceControl/organization/6cf046750b564d86a001c2d71ccc7f0f

Deleting a Source Control Entry

Deleting the source control entry for an organization will prevent Nexus IQ for Git from sending policy evaluation results as status back to the source control system.  The exception being that source control entries for individual applications, if any were created, will continue to function.

Deleting the source control entry for an individual application will cause Nexus IQ for Git to use the token set for the organization, if there is one, for communicating policy evaluation results as status back to the source control system.  If there is no organization level source control entry then no future status information will be sent to the source control system for that application.

To delete a source control entry, run the following command:

curl -u <username>:<password> \
-X DELETE http://172.16.16.5:8070/api/v2/sourceControl/<scope: application | organization>/<scoped id>

Example:

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