Report-related REST APIs - v2

The Application Composition Report is created when an evaluation occurs. There are three available REST APIs associated with obtaining information related to these reports:

Reports URL REST API (v2)

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.

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 our application API…

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

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.

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.

Step 2 - Get Report URLs

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}

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",
        "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",
        "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",
        "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"
    }
]'

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

NEW IN RELEASE 65

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 asociated 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 the Raw 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

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 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.

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

Again, in our example we are going to use cURL, though any HTTP client could be used. Here is what our request looks like:

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

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.

Looking at the result through a JSON Viewer, you should see something like this:


NEW IN RELEASE 67

The response field "packageUrl" is available from release 67.

{
   "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"
               }
            ],
            "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"
               }
            ]
         }
      }
   ]
}

Now that you have access to this data, it 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.

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.

Policy Violations by Report REST API (v2) 

NEW IN RELEASE 65

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.

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 Violation REST API - v2 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/[appPublicId]/reports/[scanId]/policy

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

  • applicationPublicId - The public ID of the 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 API.

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/policy"

and our results should look like this

{
  "reportTime": 1552489658463,
  "reportTitle": "Build Report",
  "application": {
    "id": "463ed0fa4ba14393ae4af264ab110bcf",
    "publicId": "account-storage",
    "name": "Account Storage",
    "organizationId": "6766a6b01bd64e01988e478a3f57b08c",
    "contactUserName": "test"
  },
  "counts": {
    "partiallyMatchedComponentCount": 1,
    "exactlyMatchedComponentCount": 30,
    "totalComponentCount": 32,
    "grandfatheredPolicyViolationCount": 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"
    ],
    "violations": [{
      "policyId": "15d67e3299e34362b548847bb38dfc89",
      "policyName": "Security-High",
      "policyThreatCategory": "SECURITY",
      "policyThreatLevel": 9,
      "waived": false,
      "grandfathered": 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."
        }]
      }]
    }]
  }]
}

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