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 consists in 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. Accepted values are: develop, build, stage-release, release, and operate.

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">
      <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?type=jar</purl>
    </component>
  </components>
</bom>

Note: if in an unlikely case of the same component found more than once in the bom, only the data of the first component will be processed/shown.

NEW IN RELEASE 78

In addition to the identity data shown above, each component can also include vulnerability data as shown in the example below.

<?xml version="1.0"?>
<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
     xmlns="http://cyclonedx.org/schema/bom/1.1"
     xmlns:v="http://cyclonedx.org/schema/ext/vulnerability/1.0">
  <components>
    <component type="library" bom-ref="pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.9.9?type=jar">
      <publisher>FasterXML</publisher>
      <group>com.fasterxml.jackson.core</group>
      <name>jackson-databind</name>
      <version>2.9.9</version>
      <purl>pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.9.9?type=jar</purl>
      <v:vulnerabilities>
        <v:vulnerability ref="pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.9.9?type=jar">
          <v:id>CVE-2018-7489</v:id>
          <v:source name="NVD">
            <v:url>https://nvd.nist.gov/vuln/detail/CVE-2018-7489</v:url>
          </v:source>
          <v:ratings>
            <v:rating>
              <v:score>
                <v:base>9.8</v:base>
                <v:impact>5.9</v:impact>
                <v:exploitability>3.0</v:exploitability>
              </v:score>
              <v:severity>Critical</v:severity>
              <v:method>CVSSv3</v:method>
              <v:vector>AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H</v:vector>
            </v:rating>
          </v:ratings>
          <v:cwes>
            <v:cwe>184</v:cwe>
            <v:cwe>502</v:cwe>
          </v:cwes>
          <v:description>FasterXML jackson-databind before 2.7.9.3, 2.8.x before 2.8.11.1 and 2.9.x before 2.9.5 allows unauthenticated remote code execution because of an incomplete fix for the CVE-2017-7525 deserialization flaw. This is exploitable by sending maliciously crafted JSON input to the readValue method of the ObjectMapper, bypassing a blacklist that is ineffective if the c3p0 libraries are available in the classpath.</v:description>
          <v:recommendations>
            <v:recommendation>Upgrade</v:recommendation>
          </v:recommendations>
          <v:advisories>
            <v:advisory>https://github.com/FasterXML/jackson-databind/issues/1931</v:advisory>
            <v:advisory>http://www.securityfocus.com/bid/103203</v:advisory>
            <v:advisory>http://www.securitytracker.com/id/1040693</v:advisory>
            <v:advisory>http://www.securitytracker.com/id/1041890</v:advisory>
          </v:advisories>
        </v:vulnerability>
      </v:vulnerabilities>
    </component>
  </components>
</bom>

Please note we currently support vulnerabilities specified within each component level only. And also you must specify at least the base score for each vulnerability rating.

If desired, multiple components can be included.

NEW IN RELEASE 81

When there is no Package URL available, a component can also be specified using the coordinates tags:

  • <name>: mandatory (even when <purl> is set)
  • <version>: mandatory (even when <purl> is set)
  • <group>: optional
  • <publisher>: optional

In addition each component can also include licenses data as shown in the example below.

<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>
      <licenses>
      	<license>
      	  <id>Apache-2.0</id>
      	</license>
      </licenses>
      <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?type=jar</purl>
    </component>
  </components>
</bom>


NEW IN RELEASE 83

When there is no Package URL available, a component can also be specified using its content hash (SHA-1) along with its <name> and <version> :

<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
xmlns="http://cyclonedx.org/schema/bom/1.1"
xmlns:v="http://cyclonedx.org/schema/ext/vulnerability/1.0">
   <components>
       <component type="library">
            <name>tomcat-catalina</name>
            <version>9.0.16</version>
            <hashes>
                 <hash alg="SHA-1">e6b1000b94e835ffd37f4c6dcbdad43f4b48a02a</hash>
            </hashes>
        </component>
   </components>
</bom>

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?type=jar</purl> </component> </components> </bom>' 'http://localhost:8070/api/v2/scan/applications/4537e6fe68c24dd5ac83efd97d4fc2f4/sources/cyclone'

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"
}

NEW IN RELEASE 78

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'

A successful GET will result in JSON formatted data providing information related to the result of the scan; there are different scenarios:

When the report that’s being consulted is ready:

{
    "policyAction": "None",
    "reportHtmlUrl": "http://localhost:8070/ui/links/application/my-app/report/95c4c14e"
    "isError": false,
    "componentsAffected": {
        "critical": 0,
        "severe": 0,
        "moderate": 0
    },
    "openPolicyViolations": {
        "critical": 0,
        "severe": 0,
        "moderate": 0
    },
    "grandfatheredPolicyViolations": 0
}

When the report that’s being consulted is ready and there are policy actions:

{
    "policyAction": "Failure",
    "reportHtmlUrl": "http://localhost:8070/ui/links/application/my-app/report/95c4c14e"
    "isError": false,
    "componentsAffected": {
        "critical": 1,
        "severe": 0,
        "moderate": 0
    },
    "openPolicyViolations": {
        "critical": 2,
        "severe": 1,
        "moderate": 0
    },
    "grandfatheredPolicyViolations": 0
}

NEW IN RELEASE 84

The following fields were added to the scan status response:

  • componentsAffected
  • openPolicyViolations
  • grandfatheredPolicyViolations


When the scan/report is not ready yet, the next message is returned with HTTP Status 404:

Report with status id a20bc16e83944595a94c2e36c1cd228e for application with id a20bc16e83944595a94c2e36c1cd228e is not ready.

When the scan does not exist in IQ, the next message is returned with HTTP Status 404:

Policy evaluation status with id a20bc16e83944595a94c2e36c1cd228e for public application id cyclone was not found.

When there was an error while doing the scan:

{
    "isError": true,
    "errorMessage": “Unable to evaluate policy, the scan 123456783944595a94c2e36c1cd228e could not be processed.”
}