Skip to main content

Report REST APIs

The Application Composition Report is created when an evaluation occurs.

The Reports API provides a summary of an application’s most recent reports across the various stages (e.g. Build, Stage Release, and Release). The API consists of using the GET REST resource that is part of both the applications and reports APIs.

To assist in learning to use this API we will provide both the API as well as an example using the HTTP client cURL. We’ve approached this in a step-by-step manner that will start with gathering the internal application ID and then retrieving the report information.

Note

In our example below, we have isolated retrieving a report for a single application. However, if desired the reports for all applications can also be retrieved. In this case, skip to Step 2, where a corresponding tip has been included to assist.

Step 1 - Get the Application ID

First, you will use the application’s public ID to retrieve the internal application ID. This is done using the following GET REST resource from the application API.

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

Tip

All applications can always be returned by omitting the reference to the public ID.

Using the cURL command, it would look like this:

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

If you like, you can also return multiple applications by appending additional &publicId={SomeOtherPublicId} to the command above.

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 note of the id. This is the internal application ID.

Note

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

reportId

Next we will take the internal application ID from Step 1 and use that with the GET REST resource for the Reports API. This is done with our GET REST resource associated with our Reports API…

GET /api/v2/reports/applications/{applicationInternalid}

Tip

If you would like to obtain the report information for all applications, simply leave off the "id" and all report information for all applications will be provided.

Using cURL, it will look like this…

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/reports/applications/4bb67dcfc86344e3a483832f8c496419'

If any report information is found for the application, you will receive JSON formatted data. An example is included below.

[
    {
        "stage": "build",
        "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
        "evaluationDate": "2015-01-16T13:14:32.139-05:00",
        "latestReportHtmlUrl": "ui/links/application/Test123/latestReport/build",
        "reportHtmlUrl": "ui/links/application/Test123/report/474ca07881554f8fbec168ec25d9616a",
        "embeddableReportHtmlUrl": "ui/links/application/Test123/report/474ca07881554f8fbec168ec25d9616a/embeddable",
        "reportPdfUrl": "ui/links/application/Test123/report/474ca07881554f8fbec168ec25d9616a/pdf",
        "reportDataUrl": "api/v2/applications/Test123/reports/474ca07881554f8fbec168ec25d9616a"
    },
    {
        "stage": "stage-release",
        "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
        "evaluationDate": "2014-07-14T15:08:09.501-04:00",
        "latestReportHtmlUrl": "ui/links/application/Test123/latestReport/stage-release",
        "reportHtmlUrl": "ui/links/application/Test123/report/2dbfd514e5ad497598086c3e4c89c413",
        "embeddableReportHtmlUrl": "ui/links/application/Test123/report/2dbfd514e5ad497598086c3e4c89c413/embeddable",
        "reportPdfUrl": "ui/links/application/Test123/report/2dbfd514e5ad497598086c3e4c89c413/pdf",
        "reportDataUrl": "api/v2/applications/Test123/reports/2dbfd514e5ad497598086c3e4c89c413"
    },
    {
        "stage": "release",
        "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
        "evaluationDate": "2014-08-31T12:01:46.179-04:00",
        "latestReportHtmlUrl": "ui/links/application/Test123/latestReport/release",
        "reportHtmlUrl": "ui/links/application/Test123/report/97cccbeeb58d4aac83264993ef6bf4d8",
        "embeddableReportHtmlUrl": "ui/links/application/Test123/report/97cccbeeb58d4aac83264993ef6bf4d8/embeddable",
        "reportPdfUrl": "ui/links/application/Test123/report/97cccbeeb58d4aac83264993ef6bf4d8/pdf",
        "reportDataUrl": "api/v2/applications/Test123/reports/97cccbeeb58d4aac83264993ef6bf4d8"
    }
]

Note that latestReportHtmlUrl provides a stable link to the most recent report for a given application and stage, i.e. the specific report viewable at this link will vary over time as new evaluations are performed. In contrast, reportHtmlUrl provides a link to the report that is the latest for a stage at the time the REST request is made.

Raw Component's Data by Report REST API (v2)

When an application is evaluated, two very distinct sets of information are generated; the first set pertains to the components identified in an application and the vulnerabilities and licenses associated to them, we call this information the Raw Data. The second set of information is the result of evaluating the Raw Data against the policies defined in IQ.

The following steps detail how to obtain theRaw Data. The steps for obtaining the Policy data are detailed later on the section Policy Data by Report REST API (v2).

Step 1 - Sending the Request

First, let’s take a look at the GET API we’ll be using:

GET http://localhost:8070/api/v2/applications/[applicationPublicId]/reports/[reportId]/raw

Note

In previous versions of IQ, this API was located at a slightly different endpoint, http://localhost:8070/api/v2/applications/[applicationPublicId]/reports/[reportId] . That older endpoint now returns a redirect to the new endpoint.

As you may have noticed, this API uses a URL specific to the location of the report. There are two pieces of information you will need in order to retrieve the results.

  • applicationPublicId - The public ID of the specific application.

  • reportId - The ID of the specific report.

There are a variety of ways to retrieve this information, including gathering it by using the Component Search REST API. However, in our example, we’re just going to pull this information from the log output.

...

********************************************************************************
[INFO] Policy Action: None
[INFO] CLM stage: build
[INFO] Summary of policy violations: 6 critical, 11 severe, 1 moderate
[INFO] The detailed report can be viewed online at http://localhost:8070/ui/links/application/MyApp-1234/report/68b6bdb1573a40eeb4205d890b602525
[INFO]
********************************************************************************

We’ll use the link for the report to gather the information we need:

http://localhost:8070/ui/links/application/MyApp-1234/report/68b6bdb1573a40eeb4205d890b602525

In the example above, the section of the URL following "application" and before the section "report", is the application's public ID. Similarly, the section after "report" is the report ID.

Note

The report is also presented in a full GUI. To access this, simply paste the link in your browser. However, you will need to be at least a member of the developer group for the application that has been evaluated, or you will not be able to access the report.

Now, we can download the data using our HTTP request tool.

Step 2 - Downloading Component Information

Example 1:

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/applications/MyApp-1234/reports/68b6bdb1573a40eeb4205d890b602525/raw"

Note

Included in our cURL example is the default username and password for the admin account. Your account credentials may vary, but are necessary in order for the request to be processed. If the username and password provided are not at least within the developer role for the application, an error will be returned.

Response 1:

{
   "components": [
      {
         "hash": "1249e25aebb15358bedd",
         "componentIdentifier": {
            "format": "maven",
            "coordinates": {
               "artifactId": "tomcat-util",
               "groupId": "tomcat",
               "version": "5.5.23"
               "extension": "jar",
               "classifier": ""
            },
         },
         "packageUrl": "pkg:maven/tomcat/tomcat-util@5.5.23?type=jar",      
         "proprietary": false,
         "matchState": "exact",
         "pathnames": [
            "sample-application.zip/tomcat-util-5.5.23.jar"
         ],
         "licenseData": {
            "declaredLicenses": [
               {
                  "licenseId": "Apache-2.0",
                  "licenseName": "Apache-2.0"
               }
            ],
            "observedLicenses": [
               {
                  "licenseId": "No-Sources",
                  "licenseName": "No Sources"
               }
            ],
            "effectiveLicenses": [
               {
                  "licenseId": "Apache-2.0",
                  "licenseName": "Apache-2.0"
               }
            ],
            "overriddenLicenses": [

            ],
            "status": "Open"
         },
         "securityData": {
            "securityIssues": [
               {
                  "source": "cve",
                  "reference": "CVE-2007-3385",
                  "severity": 4.3,
                  "status": "Open",
                  "url": "http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-3385",
                  "threatCategory": "severe"
               }
            ]
         }
      }
   ]
}

Note

Data from the response fields can be packaged in a variety of ways. For example, you may want to use this as a bill of materials to include associated license data.

Response 2:

This example contains the response field dependencyData.

 {
    "components": [
        {
            "packageUrl": "pkg:maven/javax.inject/javax.inject@1?type=jar",
            "hash": "6975da39a7040257bd51",
            "componentIdentifier": {
                "format": "maven",
                "coordinates": {
                    "artifactId": "javax.inject",
                    "classifier": "",
                    "extension": "jar",
                    "groupId": "javax.inject",
                    "version": "1"
                }
            },
            "displayName": "javax.inject : javax.inject : 1",
            "proprietary": false,
            "matchState": "exact",
            "pathnames": [
                "org.example:Consumer-Service:jar:1.0-SNAPSHOT/javax.inject:javax.inject:jar:1"
            ],
            "licenseData": {
                "declaredLicenses": [],
                "observedLicenses": [],
                "effectiveLicenses": [],
                "overriddenLicenses": [],
                "status": "Open",
                "effectiveLicenseThreats": []
            },
            "securityData": {
                "securityIssues": []
            },
            "dependencyData": {
                "directDependency": false,
                "innerSource": false,
                "parentComponentPurls":[ 
                                        "pkg:maven/org.example/ACME-data@1.0-SNAPSHOT?type=jar",
                                        "pkg:maven/org.example/ACME-model@2.0-SNAPSHOT?type=jar"
                                ],
                                "innerSourceData": [
                                        {
                                                "ownerApplicationName": "ACM-PRODUCER",
                                                "ownerApplicationId": "17f3d3479cbf44b2809b68569d1b0b5c",
                                                "innerSourceComponentPurl": "pkg:maven/org.example/ACME-business@1.0-SNAPSHOT?type=jar"
                                        }
                                ]
            }
        },
        {
            "packageUrl": "pkg:maven/org.example/ACME-business@1.0-SNAPSHOT?type=jar",
            "hash": "cefa389a797ca9d030ef",
            "componentIdentifier": {
                "format": "maven",
                "coordinates": {
                    "artifactId": "ACME-business",
                    "classifier": "",
                    "extension": "jar",
                    "groupId": "org.example",
                    "version": "1.0-SNAPSHOT"
                }
            },
            "displayName": "org.example : ACME-business : 1.0-SNAPSHOT",
            "proprietary": false,
            "matchState": "exact",
            "pathnames": [
                "org.example:Consumer-Service:jar:1.0-SNAPSHOT/org.example:ACME-business:jar:1.0-SNAPSHOT"
            ],
            "licenseData": {
                "declaredLicenses": [],
                "observedLicenses": [],
                "effectiveLicenses": [],
                "overriddenLicenses": [],
                "status": "Open",
                "effectiveLicenseThreats": []
            },
            "securityData": {
                "securityIssues": []
            },
            "dependencyData": {
                "directDependency": true,
                "innerSource": true,
                                "innerSourceData": [
                                        {
                                                "ownerApplicationName": "ACM-PRODUCER",
                                                "ownerApplicationId": "17f3d3479cbf44b2809b68569d1b0b5c"
                                        }
                                ]
            }
        },
    ]
}

Possible values for the response field dependencyData are:

Value

Explanation

directDependency

The component is a direct dependency

innerSource

The component is an InnerSource Component

parentComponentPurls

The package URLs of the parent components

ownerApplicationName

The name of the owner application

ownerApplicationId

The internal ID of the owner application

innerSourceComponentPurl

The package URL of the inner source component

Note

In cases where you want a version of the report without any of the associated IQ Server navigation elements (e.g. for use in a custom tool), use the embeddableReportHtmlUrl.

Response 3:

Note

The response may include Common Platform Enumeration (CPE) and Software Identification (SWID) details, but only if they were present in the original SBOM scanned for that stage.

This example contains CPE and SWID data.

{
    "components": [
        {
            "packageUrl": "pkg:cpe/acme/application@9.1.1",
            "hash": "e9b12cbc0636db5ad3f5",
            "componentIdentifier": {
                "format": "cpe",
                "coordinates": {
                    "name": "application",
                    "namespace": "acme",
                    "version": "9.1.1"
                }
            },
            "displayName": "acme : application : 9.1.1",
            "proprietary": false,
            "matchState": "exact",
            "pathnames": [
                "test-bom.xml/pkg:cpe\\acme\\application@9.1.1"
            ],
            "identificationSource": "test",
            "licenseData": {
                "declaredLicenses": [
                    {
                        "licenseId": "UNSPECIFIED",
                        "licenseName": "Not Provided"
                    }
                ],
                "observedLicenses": [],
                "effectiveLicenses": [
                    {
                        "licenseId": "UNSPECIFIED",
                        "licenseName": "Not Provided"
                    }
                ],
                "overriddenLicenses": [],
                "status": "Open",
                "effectiveLicenseThreats": [
                    {
                        "licenseThreatGroupName": "Sonatype Special Licenses",
                        "licenseThreatGroupLevel": 5,
                        "licenseThreatGroupCategory": "severe"
                    }
                ]
            },
            "securityData": {
                "securityIssues": []
            },
            "cpe": "cpe:/a:acme:application:9.1.1",
            "swid": {
                "tagId": "swidgen-242eb18a-503e-ca37-393b-cf156ef09691_9.1.1",
                "name": "Acme Application",
                "version": "9.1.1",
                "tagVersion": 0,
                "patch": false,
                "text": {
                    "encoding": "base64",
                    "contentType": "text/xml",
                    "content": "PD94bWwgdmVyc"
                }
            }
        }
    ],
    "matchSummary": {
        "totalComponentCount": 1,
        "knownComponentCount": 1
    },
    "globalInformation": {
        "dataVersionDate": null
    }
}

Policy Violations by Report REST API (v2)

As mentioned before, in the process of scanning an application and after identifying the components and their raw data, the next step consists of evaluating this data against the policies defined in IQ.

The following API endpoint is a way to obtain the information resulting from this evaluation.

Note

It is important to note that this API endpoint is Component oriented, meaning that its results are centered around components and how the data relates to them (including the policy violations). This contrasts with the Policy Violation REST API whose results are centered around violations.

Step 1 - Sending the Request

The GET API we will be using:

GET http://localhost:8070/api/v2/applications/[applicationPublicId]/reports/[reportId]/policy

The information required for this endpoint is exactly the same as that required by the Raw Data API endpoint:

  • applicationPublicId - ThepublicIDofthe specific application.

  • reportId - The ID of the specific report.

As mentioned before, ways to obtain this information are discussed in the example shown in Step 1 for Raw Component's Data by Report REST API (v2), where it is extracted from the log output; Other ways to obtain this are discussed in the Component Search REST API.

Step 2 - Downloading the Component Information

Example:

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/applications/MyApp-1234/reports/68b6bdb1573a40eeb4205d890b602525/policy"

Response:

Response

{
   "reportTime":1552489658463,
   "reportTitle":"Build Report",
   "commitHash":"79d5810d5545dea1db31d32d17d1a98376775186",
   "initiator":"system",
   "application":{
      "id":"463ed0fa4ba14393ae4af264ab110bcf",
      "publicId":"account-storage",
      "name":"Account Storage",
      "organizationId":"6766a6b01bd64e01988e478a3f57b08c",
      "contactUserName":"test"
   },
   "counts":{
      "partiallyMatchedComponentCount":1,
      "exactlyMatchedComponentCount":30,
      "totalComponentCount":32,
      "grandfatheredPolicyViolationCount":72,
      "legacyViolationCount":72
   },
   "components":[
      {
         "hash":"47b6857af4a1cc50875a",
         "matchState":"Exact",
         "componentIdentifier":{
            "format":"maven",
            "coordinates":{
               "artifactId":"logback-access",
               "classifier":"",
               "extension":"jar",
               "groupId":"ch.qos.logback",
               "version":"0.6"
            }
         },
         "packageUrl":"pkg:maven/ch.qos.logback/logback-access@0.6?type=jar",
         "proprietary":false,
         "pathnames":[
            "sample-application.zip/logback-access-0.6.jar"
         ],
         "dependencyData":{
            "directDependency":true,
            "innerSource":false
         },
         "violations":[
            {
               "policyId":"15d67e3299e34362b548847bb38dfc89",
               "policyName":"Security-High",
               "policyThreatCategory":"SECURITY",
               "policyThreatLevel":9,
               "policyViolationId":"c8fc78d54b904d2f8045afafbe0558dc",
               "waived":false,
               "grandfathered":true,
               "legacyViolation":true,
               "constraints":[
                  {
                     "constraintId":"01996366a3fb445c800e79c7786224f7",
                     "constraintName":"cvss >= 7 and < 9",
                     "conditions":[
                        {
                           "conditionSummary":"Security Vulnerability Severity >= 7",
                           "conditionReason":"Found security vulnerability CVE-2017-5929 with severity 7.5."
                        },
                        {
                           "conditionSummary":"Label is not 'waiver-security'",
                           "conditionReason":"Did not find label 'waiver-security'."
                        },
                        {
                           "conditionSummary":"Security Vulnerability Status is not NOT_APPLICABLE",
                           "conditionReason":"Found security vulnerability CVE-2017-5929 with status 'Acknowledged', not 'Not Applicable'."
                        },
                        {
                           "conditionSummary":"Security Vulnerability Severity < 9",
                           "conditionReason":"Found security vulnerability CVE-2017-5929 with severity 7.5."
                        }
                     ]
                  }
               ]
            }
         ]
      },
      {
         "packageUrl":"pkg:maven/org.example/ACME-business@1.0.0?type=jar",
         "hash":"cefa389a797ca9d030ef",
         "componentIdentifier":{
            "format":"maven",
            "coordinates":{
               "artifactId":"ACME-business",
               "classifier":"",
               "extension":"jar",
               "groupId":"org.example",
               "version":"1.0.0"
            }
         },
         "displayName":"org.example : ACME-business : 1.0.0",
         "proprietary":false,
         "matchState":"exact",
         "pathnames":[
            "org.example:Consumer-Data:jar:1.0.0/org.example:ACME-business:jar:1.0.0",
            "org.example:Consumer-Service:jar:1.0.0/org.example:ACME-business:jar:1.0.0"
         ],
         "dependencyData":{
            "directDependency":true,
            "innerSource":true,
            "innerSourceData":[
               {
                "ownerApplicationName":"ACM-PRODUCER",
                "ownerApplicationId":"17f3d3479cbf44b2809b68569d1b0b5c"
              }
            ]
         },
         "violations":[]
      },
      {
         "packageUrl":"pkg:maven/org.example/ACME-data@1.0.0?type=jar",
         "hash":"32032f22af513c6e683d",
         "componentIdentifier":{
            "format":"maven",
            "coordinates":{
               "artifactId":"ACME-data",
               "classifier":"",
               "extension":"jar",
               "groupId":"org.example",
               "version":"1.0.0"
            }
         },
         "displayName":"org.example : ACME-data : 1.0.0",
         "proprietary":false,
         "matchState":"exact",
         "pathnames":[
            "org.example:Consumer-Data:jar:1.0.0/org.example:ACME-data:jar:1.0.0",
            "org.example:Consumer-Service:jar:1.0.0/org.example:ACME-data:jar:1.0.0"
         ],
         "dependencyData":{
            "directDependency":false,
            "innerSource":false,
            "parentComponentPurls":[
                                "pkg:maven/org.example/ACME-business@1.0.0?type=jar",
                                "pkg:maven/org.example/ACME-model@2.1.0?type=jar"
                        ],
            "innerSourceData":[
               {
                  "ownerApplicationName":"ACM-PRODUCER",
                  "ownerApplicationId":"17f3d3479cbf44b2809b68569d1b0b5c",
                  "innerSourceComponentPurl":"pkg:maven/org.example/ACME-business@1.0.0?type=jar"
               }
            ]
         },
         "violations":[]
      }
   ]
}

Note

As part of our inclusive language initiatives stemming from one of Sonatype's core values "Embrace Inclusion", the response fields grandfatheredPolicyViolationCount and grandfathered have been deprecated. Use legacyViolationCount and legacyViolation response fields, respectively.

Refer to Legacy Violations for more information.

Note

The returned component hash value is truncated and is meant to be used as an identifier that can be passed into subsequent REST API calls. It is not intended to be used as a checksum.

Note

The policyThreatCategory property as well as some nested properties in thecounts property or the counts property itself might not be available in older reports.

Retrieving Application Evaluation Policy Violation Diffs

Nexus IQ for SCM allows policy evaluations to be linked to the Git commit hash of the scanned commit. Using the hash, the diff on policy violations for two commits with associated policy evaluations is executed. This diff report enables users to track the impact of their changes on policy violations.

Requirements

  • In order for policy evaluations to be associated with commits, the commit hash must be included with the policy evaluation request. The capability to include the commit hash with the policy evaluation request is supported on various Nexus IQ Server Integrations.

  • Ensure that the commits being compared have policy evaluations executed against them.

  • The user executing the API call requires "View IQ Elements" permission for the specified Application.

The ability to find policy evaluations for specific commits will be impacted by Data Retention Policies set up in Sonatype IQ Server. Once Application Reports have been purged following Data Retention Policies, diff operations can no longer be requested for the associated commits.

Retrieving the Policy Violation Diff

Once commits have been identified for comparison, the Policy Violation Diff can be retrieved using the following API call:

GET /api/v2/applications/{applicationPublicId}/reports/policyViolations/diff?fromCommit={fromCommit}&toCommit={toCommit}

The table below describes the parameters required in the API call:

Parameter

Description

applicationPublicId

The public application Id used to uniquely identify the application.

fromCommit

This is the commit hash for the "from" commit which the "to" commit will be compared to.

toCommit

This is the commit hash for the "to" commit which will be compared to the "from" commit.

The latest policy evaluation report associated with each commit will be compared to return a diff. This report entails violations introduced, removed, or unchanged by the updated commit.

Policy violations used for comparison and returned by the API are based on the data available in the Application Reports at the time the request is made.

An example of the API call with specified parameters is shown here:

GET /api/v2/applications/MyAppID1/reports/policyViolations/diff?fromCommit=4d9a62d4356d2b194bd19c457a8db7f33049c67b&toCommit=ab187c2fd7737859bd8268c8427be33b2cf48c12

The API also supports abbreviated commit hashes, an example is shown here:

GET /api/v2/applications/MyAppID1/reports/policyViolations/diff?fromCommit=4d9a62d&toCommit=ab187c2

Application Ids and commit hashes are unique. The values shown here are for reference only.

Using our cURL example, a possible cURL command is shown here:

curl -u admin:admin123 -X GET  'http://localhost:8070/api/v2/applications/MyAppID1/reports/policyViolations/diff?fromCommit=4d9a62d&toCommit=ab187c2'

If your query was successful, the system will respond with the following:

{ 
    "application" :{ 
       "id" : "0f93f912fa294d7fa85332c1b07cf580" , 
       "publicId" : "MyAppID1" , 
       "name" : "MyApplications" , 
       "organizationId" : "36d7e629462a4038b581488c347959bc" , 
       "contactUserName" : "AppContact" 
    }, 
    "fromCommit" :{ 
       "commitHash" : "4d9a62d4356d2b194bd19c457a8db7f33049c67b" , 
       "scanId" : "c0ddefc4512f42d0bcbe29029e2be117" , 
       "reportUrl" : "ui/links/application/MyAppID1/report/c0ddefc4512f42d0bcbe29029e2be117" , 
       "scanTime" : "2019-12-07T15:13:48.357-05:00" 
    }, 
    "toCommit" :{ 
       "commitHash" : "ab187c2fd7737859bd8268c8427be33b2cf48c12" , 
       "scanId" : "5ea5363997ee2ba0c8730a5f785ae2c6" , 
       "reportUrl" : "ui/links/application/MyAppID1/report/5ea5363997ee2ba0c8730a5f785ae2c6" , 
       "scanTime" : "2019-12-08T20:52:27.659-05:00" 
    }, 
    "diffTime" : "2019-12-09T10:15:18.621+-05:00" , 
    "addedViolations" :[ 
       { 
          "policyId" : "2aadd95bd58345e69723815413dd4a97" , 
          "policyName" : "Security-High" , 
          "threatLevel" : 9 , 
          "constraintViolations" :[ 
             { 
                "constraintId" : "42b8b763e2dc497eb7e3f3c217a884d5" , 
                "constraintName" : "High risk CVSS score" , 
                "reasons" :[ 
                   { 
                      "reason" : "Found security vulnerability CVE-2018-11307 with severity 9.8." 
                   }, 
                   { 
                      "reason" : "Found security vulnerability CVE-2018-11307 with severity 9.8." 
                   }, 
                   { 
                      "reason" : "Found security vulnerability CVE-2018-11307 with status 'Open', not 'Not Applicable'." 
                   } 
                ] 
             } 
          ], 
          "component" :{ 
             "packageUrl" : "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.11.1?type=jar" , 
             "hash" : "341edc63fdd8b44e17b2" , 
             "componentIdentifier" :{ 
                "format" : "maven" , 
                "coordinates" :{ 
                   "artifactId" : "jackson-databind" , 
                   "classifier" : "" , 
                   "extension" : "jar" , 
                   "groupId" : "com.fasterxml.jackson.core" , 
                   "version" : "2.8.11.1" 
                } 
             }, 
             "proprietary" : false 
          } 
       } 
    ], 
    "sameViolations" :[ 
       { 
          "policyId" : "2aadd95bd58345e69723815413dd4a97" , 
          "policyName" : "Security-High" , 
          "threatLevel" : 9 , 
          "constraintViolations" :[ 
             { 
                "constraintId" : "42b8b763e2dc497eb7e3f3c217a884d5" , 
                "constraintName" : "High risk CVSS score" , 
                "reasons" :[ 
                   { 
                      "reason" : "Found security vulnerability CVE-2019-12086 with severity 7.5." 
                   }, 
                   { 
                      "reason" : "Found security vulnerability CVE-2019-12086 with severity 7.5." 
                   }, 
                   { 
                      "reason" : "Found security vulnerability CVE-2019-12086 with status 'Open', not 'Not Applicable'." 
                   } 
                ] 
             } 
          ], 
          "component" :{ 
             "packageUrl" : "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.9.8?type=jar" , 
             "hash" : "11283f21cc480aa86c4d" , 
             "componentIdentifier" :{ 
                "format" : "maven" , 
                "coordinates" :{ 
                   "artifactId" : "jackson-databind" , 
                   "classifier" : "" , 
                   "extension" : "jar" , 
                   "groupId" : "com.fasterxml.jackson.core" , 
                   "version" : "2.9.8" 
                } 
             }, 
             "proprietary" : false 
          } 
       } 
    ], 
    "removedViolations" :[ 
       { 
          "policyId" : "2aadd95bd58345e69723815413dd4a97" , 
          "policyName" : "Security-High" , 
          "threatLevel" : 9 , 
          "constraintViolations" :[ 
             { 
                "constraintId" : "42b8b763e2dc497eb7e3f3c217a884d5" , 
                "constraintName" : "High risk CVSS score" , 
                "reasons" :[ 
                   { 
                      "reason" : "Found security vulnerability CVE-2019-0199 with severity 7.5." 
                   }, 
                   { 
                      "reason" : "Found security vulnerability CVE-2019-0199 with severity 7.5." 
                   }, 
                   { 
                      "reason" : "Found security vulnerability CVE-2019-0199 with status 'Open', not 'Not Applicable'." 
                   } 
                ] 
             } 
          ], 
          "component" :{ 
             "packageUrl" : "pkg:maven/org.apache.tomcat.embed/tomcat-embed-core@9.0.14?type=jar" , 
             "hash" : "c3959b59158063aeb4f0" , 
             "componentIdentifier" :{ 
                "format" : "maven" , 
                "coordinates" :{ 
                   "artifactId" : "tomcat-embed-core" , 
                   "classifier" : "" , 
                   "extension" : "jar" , 
                   "groupId" : "org.apache.tomcat.embed" , 
                   "version" : "9.0.14" 
                } 
             }, 
             "proprietary" : false 
          } 
       } 
    ] 
}

Response Fields

The table below describes the various elements returned by the API call:

Field name

Description

addedViolations

Policy violations that are present in the evaluation report for the updated commit but not in the report for the original commit.

sameViolations

Policy violations that are present in the evaluation reports for both the original and the updated commits.

removedViolations

Policy violations that are present in the evaluation report for the original commit but do not appear in the report for the updated commit.

policyName

The name of the policy as shown in Nexus IQ Server.

threatLevel

The threat level of the policy that was violated.

constraintViolations

List of violations for the given constraints.

constraintId

The internal ID for the constraint and is not visible in Nexus IQ Server.

constraintName

The name of the constraint as shown in Nexus IQ Server.

component

The component to which the listed violations are attributed.

hash

The hash value for the component. For example, Java components, are matched to a Java repository (e.g. Central). If user configures proprietary components, the components would be matched against the user list of proprietary components.

The returned hash value is truncated and is meant to be used as an identifier that can be passed into subsequent REST API calls. It is not intended to be used as a checksum.

componentIdentifier

The format and coordinates for the affected component.

format

The format, such as maven, npm, go, etc.

coordinates

This will depend on the format. An example would be Maven, which uses a G : A : E : C : V (Group, Artifact Id, Extension, Classifier, and Version) for the component.

HTTP Response Codes

The table below describes the HTTP response codes returned by the API request:

Code

Description

400

There was a problem with the request, most likely a missing or invalid parameter.

404

The policy violation diff could not be determined for the given request.

Retrieving the Scan Report History

Use the GET method to retrieve a list of the latest reports (100 maximum) for a given application.

Example:

Obtain the internal application ID and use the GET request to retrieve the policy evaluation history.

GET /api/v2/reports/applications/{applicationInternalId}/history

Using the cURL command and the application ID from the example above, it would look like this:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/reports/applications/4537e6fe68c24dd5ac83efd97d4fc2f4/history'

Response:

{
    "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
    "policyEvaluations": [
        {
            "stage": "develop",
            "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
            "evaluationDate": "2020-06-03T13:43:10.816-03:00",
            "latestReportHtmlUrl": "ui/links/application/MyApplicationID/latestReport/develop",
            "reportHtmlUrl": "ui/links/application/MyApplicationID/report/53a99dd8b58e4d819c0791a8087df62c",
            "embeddableReportHtmlUrl": "ui/links/application/MyApplicationID/report/53a99dd8b58e4d819c0791a8087df62c/embeddable",
            "reportPdfUrl": "ui/links/application/MyApplicationID/report/53a99dd8b58e4d819c0791a8087df62c/pdf",
            "reportDataUrl": "api/v2/applications/MyApplicationID/reports/53a99dd8b58e4d819c0791a8087df62c/raw",
            "policyEvaluationId": "6ccd7900214f45d6b7fe5d99324b16c9",
            "scanId": "53a99dd8b58e4d819c0791a8087df62c",
            "isReevaluation": false,
            "isForMonitoring": false,
            "commitHash": "7951853e5d0f048ae48925820b138e0bcc4148f2",
            "scanTriggerType": "WEB_UI",
            "policyEvaluationResult": {
                "alerts": [],
                "affectedComponentCount": 14,
                "criticalComponentCount": 9,
                "severeComponentCount": 4,
                "moderateComponentCount": 1,
                "criticalPolicyViolationCount": 35,
                "severePolicyViolationCount": 17,
                "moderatePolicyViolationCount": 2,
                "grandfatheredPolicyViolationCount": 0,
                "legacyViolationCount": 0
            }
        },
        {
            "stage": "release",
            "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
            "evaluationDate": "2020-06-03T13:42:41.311-03:00",
            "latestReportHtmlUrl": "ui/links/application/MyApplicationID/latestReport/release",
            "reportHtmlUrl": "ui/links/application/MyApplicationID/report/a2be87580faa40dcb6c5ca6408d30b8e",
            "embeddableReportHtmlUrl": "ui/links/application/MyApplicationID/report/a2be87580faa40dcb6c5ca6408d30b8e/embeddable",
            "reportPdfUrl": "ui/links/application/MyApplicationID/report/a2be87580faa40dcb6c5ca6408d30b8e/pdf",
            "reportDataUrl": "api/v2/applications/MyApplicationID/reports/a2be87580faa40dcb6c5ca6408d30b8e/raw",
            "policyEvaluationId": "c52c14df046f4f0fb5ee9723165f866d",
            "scanId": "a2be87580faa40dcb6c5ca6408d30b8e",
            "isReevaluation": false,
            "isForMonitoring": false,
            "commitHash": "7951853e5d0f048ae48925820b138e0bcc4148f2",
            "scanTriggerType": "WEB_UI",
            "policyEvaluationResult": {
                "alerts": [],
                "affectedComponentCount": 14,
                "criticalComponentCount": 9,
                "severeComponentCount": 4,
                "moderateComponentCount": 1,
                "criticalPolicyViolationCount": 35,
                "severePolicyViolationCount": 17,
                "moderatePolicyViolationCount": 2,
                "grandfatheredPolicyViolationCount": 0,
                "legacyViolationCount": 0
            }
        }
    ]
}

Using the query parameters stage and/or limit allows you to retrieve reports from a specific stage and/or limited to a given count (most recent reports.)

Example:

curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/reports/applications/4537e6fe68c24dd5ac83efd97d4fc2f4/history?stage=release&limit=1'

Response:

{
    "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
    "policyEvaluations": [
        {
            "stage": "release",
            "applicationId": "4537e6fe68c24dd5ac83efd97d4fc2f4",
            "evaluationDate": "2020-06-03T13:42:41.311-03:00",
            "latestReportHtmlUrl": "ui/links/application/MyApplicationID/latestReport/release",
            "reportHtmlUrl": "ui/links/application/MyApplicationID/report/a2be87580faa40dcb6c5ca6408d30b8e",
            "embeddableReportHtmlUrl": "ui/links/application/MyApplicationID/report/a2be87580faa40dcb6c5ca6408d30b8e/embeddable",
            "reportPdfUrl": "ui/links/application/MyApplicationID/report/a2be87580faa40dcb6c5ca6408d30b8e/pdf",
            "reportDataUrl": "api/v2/applications/MyApplicationID/reports/a2be87580faa40dcb6c5ca6408d30b8e/raw",
            "policyEvaluationId": "c52c14df046f4f0fb5ee9723165f866d",
            "scanId": "a2be87580faa40dcb6c5ca6408d30b8e",
            "isReevaluation": false,
            "isForMonitoring": false,
            "commitHash": "7951853e5d0f048ae48925820b138e0bcc4148f2",
            "scanTriggerType": "WEB_UI",
            "policyEvaluationResult": {
                "alerts": [],
                "affectedComponentCount": 14,
                "criticalComponentCount": 9,
                "severeComponentCount": 4,
                "moderateComponentCount": 1,
                "criticalPolicyViolationCount": 35,
                "severePolicyViolationCount": 17,
                "moderatePolicyViolationCount": 2,
                "grandfatheredPolicyViolationCount": 0
            }
        }
    ]
}

Field scanTriggerType is now included in the response payload.

Response Fields

Response field

Description

stage

The stage specified when the policy evaluation was run, such as 'develop', 'build', 'release' etc.

latestReportHtmlUrl

The relative URL to the latest report for the given application and stage

reportHtmlUrl

The relative URL where the full report can be viewed

embeddableReportHtmlUrl

The relative URL to an embeddable version of the full report

reportPdfUrl

The relative URL to a PDF version of the full report

reportDataUrl

The relative URL where the report data can be retrieved

scanId

The scan ID associated with the report

isReevaluation

Indicates whether this policy evaluation is a reevaluation of an older policy evaluation

isForMonitoring

Indicates whether this policy evaluation was triggered by continuous monitoring

commitHash

The commit hash of the associated source control commit, if available

scanTriggerType

The trigger type of the scan

affectedComponentCount

The count of components identified

criticalComponentCount

The count of components with critical policy violations

severeComponentCount

The count of components with severe policy violations

moderateComponentCount

The count of components with moderate policy violations

criticalPolicyViolationCount

The count of critical policy violations

severePolicyViolationCount

The count of severe policy violations

moderatePolicyViolationCount

The count of moderate policy violations

grandfatheredPolicyViolationCount (deprecated)

The count of grandfathered policy violations. This response field has been replaced with legacyViolationCount to show Legacy Violations.

legacyViolationCount

The count of Legacy Violations.

Application Dependency Tree REST API

Note

This endpoint works for Java (Maven) and NPM applications.

Step 1 - Sending the Request

Use the GET method:

GET http://localhost:8070/api/v2/applications/[applicationPublicId]/reports/[reportId]/dependencyTree

There are two pieces of information required in order to retrieve the results:

  • applicationPublicId - The public ID of the specific application.

  • reportId - The ID of the specific report.

Step 2 - Downloading the Component Information

Our request should look like this

curl -u admin:admin123 -X GET "http://localhost:8070/api/v2/applications/MyApp-1234/reports/68b6bdb1573a40eeb4205d890b602525/dependencyTree"

and our results should look like this

{
    "dependencyTree": {
        "children": [
            {
                "packageUrl": "pkg:npm/hawk@4.1.2",
                "componentIdentifier": {
                    "format": "npm",
                    "coordinates": {
                        "packageId": "hawk",
                        "version": "4.1.2"
                    }
                },
                "children": [
                    {
                        "packageUrl": "pkg:npm/sntp@2.1.0",
                        "componentIdentifier": {
                            "format": "npm",
                            "coordinates": {
                                "packageId": "sntp",
                                "version": "2.1.0"
                            }
                        },
                        "children": [
                            {
                                "packageUrl": "pkg:npm/hoek@4.2.1",
                                "componentIdentifier": {
                                    "format": "npm",
                                    "coordinates": {
                                        "packageId": "hoek",
                                        "version": "4.2.1"
                                    }
                                }
                            }
                        ]
                    },
                    {...}
                ]
            }
        ]
    }
}

Dependency data is not available

{
    "dependencyTree": {}
}

HTTP Response Codes

The table below describes the HTTP response codes returned by the API request:

Code

Description

400

There was a problem with the request, most likely a missing or invalid parameter.

404

The requested dependency tree was not found.

Data Definition

The tables below describe the various elements returned by the API call:

Name

Type

Required

Description

children

List<DependencyTreeNode>

yes

List of direct dependencies that an application use, each direct dependency can have zero or more transitive dependencies

Dependency Tree Node Structure

Name

Type

Required

packageUrl

String

yes

componentIdentifier

ComponentIdentifier

yes

children

List<DependencyTreeNode>

no

Component Identifier Structure

Name

Type

Required

format

String

yes

coordinates

Coordinates

yes

Coordinates Structure (NPM)

Name

Type

Required

packageId

String

yes

version

String

yes

Coordinates Structure (Maven)

Name

Type

Required

artifactId

String

yes

classifier

String

no

extension

String

yes

groupId

String

yes

version

String

yes