Integrate scans with build pipelines

The Contrast CLI has commands that let you run a scan without using the Contrast web interface.

This topic provides instructions for using the Contrast CLI to integrate scans into any build pipeline.

You can also use the Contrast Maven plugin to integrate Contrast Scan into your project's Maven build,

Before you begin

  • In the Contrast web interface, under user menu > User settings > Profile, locate and copy this information:

    • API key

    • Organization ID

    • Contrast URL

    • Authorization header

  • Ensure that a WAR or JAR file is available in an accessible location.

Steps

  1. In your build pipeline workflow, add the command to download the latest version of the Contrast CLI .

    npm i -g @contrast/contrast-cli@latest
  2. Set environment variables for the API key, the organization ID, the Contrast URL, and the Authorization header.

    This example shows how to set the environment variables with GitHub secrets. Use the appropriate method for your environment.

    CT_API_KEY: ${{ secrets.CONTRAST__API__API_KEY }}
    CT_AUTH_TOKEN: ${{ secrets.CONTRAST__API__AUTH_TOKEN }}
    ORG_ID: ${{ secrets.CONTRAST__API__ORGANIZATION_ID }}
    URL: ${{ secrets.CONTRAST__API__URL }}
  3. Add a command similar to the following to start each scan:

    ccontrast-cli  --scan ../scan-cli-testing/java/apps/param.war \
    --api_key $CT_API_KEY \
    --authorization $CT_AUTH_TOKEN \
    --organization_id $ORG_ID \
    --host $URL \
    --project_name MY-Project \
    --language JAVA --wait_for_scan

    When this command runs for the first time, Scan creates a project using the name specified in the --project_name option.

    The output from the command looks similar to this example:

    project created ID is 788f9734-b933-4f05-b391-c130931baf88
     Uploaded file successfully.
     Response:  {
      id: '5091d134-93ea-4873-8110-8cf99d14606e',
      organizationId: '74f4cd04-6ca9-4eb7-a7a7-78909c2101cc',
      projectId: '788f9734-b933-4f05-b391-c130931baf88',
      filename: 'param.war',
      createdTime: '2022-04-04T10:06:16.952+00:00'
    }
    Timeout set to 5 minutes
    Waiting for results...
    New Results:  5
    Fixed Results: 0
    Total Results:  5

    The next time you run the command for the same project, Scan adds the uploaded files to the original project. The output from the command looks similar to this example:

    project already exists with this name. Getting ID...
     project ID is 788f9734-b933-4f05-b391-c130931baf88
     Uploaded file successfully.
     Response:  {
      id: '94b4e065-0e0f-46bb-b1d8-9f85bd03c602',
      organizationId: '74f4cd04-6ca9-4eb7-a7a7-78909c2101cc',
      projectId: '788f9734-b933-4f05-b391-c130931baf88',
      filename: 'param.war',
      createdTime: '2022-04-04T10:07:01.230+00:00'
    }
    Timeout set to 5 minutes
    Waiting for results...
    New Results:  5
    Fixed Results: 0
    Total Results:  5
  4. After the scan completes, go to the Contrast web interface to view the Scan project details and results.

    ScanAfterCLI.png

Examples