Third-Party Scan REST API - v2

NEW IN RELEASE 77

The Third-Party Scan REST API allows for single, or multiple components, to be scanned against a specific application and associated policies, generating an Application Composition Report. 

Some possible use cases:

  • Program analysis has already identified the data. The data will go through the policy engine and be shown in an Application Composition Report.
  • Nexus IQ Server performs the program analysis. Nexus IQ Server will identify the data. Then go through the policy engine and be shown in an Application Composition Report.

This API uses the following REST resources:

  • POST - to submit a list of components, allows to submit a list of components in CycloneDx format, to evaluate policies against an existing IQ application.
  • GET - to get the result of the components submitted in with the POST resource.

For the API below is a step-by-step example using the HTTP client cURL, though any HTTP client tool could be used. In addition, we’ll reference other APIs such as the one required to obtain an application’s internal ID.

Step 1 - Get the Application ID

First, you will need to pick the application you want to evaluate your component against. This begins with obtaining the application’s public ID, which is used to retrieve the internal application ID.

The public ID can be found via the IQ Server GUI by navigating to the respective application and copying the application ID, which is located just below the application name.

This is done using the following GET REST resource from our application API:

GET /api/v2/applications?publicId={YourPublicId}

Using the cURL command, it would look like this:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/applications?publicId=MyApplicationID'

Information will be returned (unique to your application). This has been formatted for readability:

{
    "applications": [
        {
            "id": "4537e6fe68c24dd5ac83efd97d4fc2f4",
            "publicId": "MyApplicationID",
            "name": "MyApplication",
            "organizationId": "bb41817bd3e2403a8a52fe8bcd8fe25a",
            "contactUserName": "NewAppContact",
            "applicationTags": [
                {
                    "id": "9beee80c6fc148dfa51e8b0359ee4d4e",
                    "tagId": "cfea8fa79df64283bd64e5b6b624ba48",
                    "applicationId": "4bb67dcfc86344e3a483832f8c496419"
                }
            ]
        }
    ]
}

From the information returned above, make a note of the id. This is the internal application ID.

Step 2 - Submit SBOM content for evaluation

The API only allows valid SBOM files to be processed (version 1.1 supported); this one should include a list of components to be evaluated. The SBOM (Software Bill-of-Materials) is a list of components of a piece of software, for this API in particular, we are going to use CycloneDX SBOM which generates a lightweight software bill-of-material (SBOM) specification designed for use in application security contexts and supply chain component analysis. Please visit CycloneDX for more information about it in order to generate one.

Alright, by now you should have the SBOM, as well as the internal application ID and source. We’ll put this information together using the POST REST resource:

POST /api/v2/scan/applications/{applicationInternalId}/sources/{source}?stageId={stageId}

The stageId query param is optional, if not sent build is used by default 

Added to this will be an SBOM XML formatted body:

<bom xmlns="http://cyclonedx.org/schema/bom/1.1" serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1">
  <components>
    <component type="library">
      <group>org.apache.tomcat</group>
      <name>tomcat-catalina</name>
      <version>9.0.14</version>
      <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?packaging=jar</purl>
    </component>
  </components>
</bom>

If desired, multiple components can be included.

Remember initially only components with <purl> will be processed.

Together, this should look like this:

curl -u admin:admin123 -X POST -H "Content-Type: application/xml" -d '<bom xmlns="http://cyclonedx.org/schema/bom/1.1" serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"> <components> <component type="library"> <publisher>Apache</publisher> <group>org.apache.tomcat</group> <name>tomcat-catalina</name> <version>9.0.14</version> <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?packaging=jar</purl> </component> </components> </bom>' '/api/v2/scan/applications/4537e6fe68c24dd5ac83efd97d4fc2f4/sources/clair'

A successful POST will result in JSON formatted data providing a confirmation that the evaluation was submitted.

{
    "statusUrl": "api/v2/scan/applications/a20bc16e83944595a94c2e36c1cd228e/status/9cee2b6366fc4d328edc318eae46b2cb"
}

Step 3 - Checking Status URL to get scan result

After step 2, with the statusUrl result we get, it's possible to check the status of the scan, this is done using the following GET REST resource from our application API:

GET /api/v2/scan/applications/{applicationInternalId}/status/{statusId}

Using the cURL command, it would look like this:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/scan/applications/a20bc16e83944595a94c2e36c1cd228e/status/9cee2b6366fc4d328edc318eae46b2cb'

The status URL is not implemented yet, so it'll return 404 Not Implemented, to check the result please see the latest report for the application in the UI. This will be available in a coming release.