Component Remediation REST API - v2

NEW IN RELEASE 64

The APIs listed on this page provide a way to obtain suggestions for remediation of policy violations on a per component basis. The remediation recommendations provided via these APIs are similar to those provided on the component intelligence panel (CIP) version graph. A component can be validated against policies that are either associated with an application or associated with an organization.

The endpoints return the following set of remediation output types:

  • next-no-violations : This type of remediation contains the next version of the provided component version that does not violate any policies. If no version meets this criteria, this remediation type will not contain a recommended component version. If the supplied version of the component meets this criteria, it will be returned as the recommendation for this remediation type.
  • next-non-failing : This type of remediation contains the next version of the provided component version that does not fail any policy violations for the specified {stageId}. So, the returned component in this remediation type may contain the next version of the provided component which could potentially trigger warnings based on the policies, but not have a failing violation. Note that this type of remediation is only returned if the {stageId} parameter is supplied in the endpoint. Similar to  next-no-violations  remediation type, if no version meets this criteria, this type will not contain a recommended component version. If the supplied version of the component meets this criteria, it will be returned as the recommendation for this remediation type.

Remediation by Application policy

The following endpoint, relative to IQ Server's base URL, may be invoked to list remediation recommendations for a component's violations based on policies set at the application level. This is the most commonly used endpoint which is also leveraged by the component intelligence panel (CIP) version graph.

POST /api/v2/components/remediation/application/{applicationInternalId}?stageId={stageId}

The stageId query param is optional, but is required for the next-non-failing remediation type to be returned in the response.

You can use the Application REST API to obtain the applicationInternalId for an application.

With the POST request, you will need to provide the component details in the payload.  For help finding components, see Component Search REST API.  For help with other formats, see Formats with the REST API. Here is a sample JSON payload with component information that can be submitted in the POST request body (you may provide the component payload information using package URL identifiers, see an example of the response details here):

{
  "componentIdentifier": {
    "format": "maven",
    "coordinates": {
      "artifactId": "tomcat-util",
      "extension": "jar",
      "groupId": "tomcat",
      "version": "5.5.23"
     }
  }
}


Assuming a local installation of IQ Server with its default configuration, the following example using the cURL tool finds applicable remediation steps for a component:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"componentIdentifier": {"format":"maven","coordinates": {"artifactId":"tomcat-util","extension":"jar","groupId":"tomcat","version":"5.5.23"}}}' 'http://localhost:8070/api/v2/components/remediation/application/{applicationInternalId}?stageId={stageId}'

Remediation by Organization policy

The following endpoint, relative to IQ Server's base URL, may be invoked to list remediation recommendations for a component's violations based on policies set at the organization level. This endpoint may prove to be useful in cases where a component needs to be evaluated against the policies set at the organization level.

POST /api/v2/components/remediation/organization/{organizationId}?stageId={stageId}

The stageId query param is optional, but is required for the next-non-failing remediation type to be returned in the response.

You can use the Organization REST API to obtain the organizationId for an organization.

With the POST request, you will need to provide the component details in the payload.  For help finding components, see Component Search REST API.  For help with other formats, see Formats with the REST API. Here is a sample JSON payload with component information that can be submitted in the POST request body (you may provide the component payload information using package URL identifiers, see an example of the response details here):

{
  "componentIdentifier": {
    "format": "maven",
    "coordinates": {
      "artifactId": "tomcat-util",
      "extension": "jar",
      "groupId": "tomcat",
      "version": "5.5.23"
     }
  }
}

Assuming a local installation of IQ Server with its default configuration, the following example using the cURL tool finds applicable remediation steps for a component:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"componentIdentifier": {"format":"maven","coordinates": {"artifactId":"tomcat-util","extension":"jar","groupId":"tomcat","version":"5.5.23"}}}' 'http://localhost:8070/api/v2/components/remediation/organization/{organizationId}?stageId={stageId}'


Using package URL Identifiers

NEW IN RELEASE 67

In addition to providing the component identifier information in the payload as detailed above, the APIs now support providing the request payload as a package URL identifier. Here are examples of the same requests provided above using package URL identifiers in the request body:

{
   "packageUrl":"pkg:maven/tomcat/tomcat-util@5.5.23?type=jar"
}

Similarly, here are the corresponding example of the cURL commands using package URL identifiers in the request payload:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"packageUrl":"pkg:maven/tomcat/tomcat-util@5.5.23?type=jar"}' 'http://localhost:8070/api/v2/components/remediation/organization/{organizationId}?stageId={stageId}'

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"packageUrl":"pkg:maven/tomcat/tomcat-util@5.5.23?type=jar"}' 'http://localhost:8070/api/v2/components/remediation/application/{applicationInternalId}?stageId={stageId}'


Sample response

Here is a sample response that could be returned by either of the above API endpoints. The response field "packageUrl" is available from release 67. NEW IN RELEASE 67

{
  "remediation" : {
    "versionChanges" : [ {
      "type" : "next-no-violations",
      "data" : {
        "component" : {
          "packageUrl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.11.2?type=jar",
          "hash": null,
          "componentIdentifier" : {
            "format" : "maven",
            "coordinates" : {
              "artifactId" : "log4j-core",
              "classifier": "",
              "groupId" : "org.apache.logging.log4j",
              "version" : "2.11.2"
            }
          }
        }
      }
    }, {
      "type": "next-non-failing",
      "data": {
        "component": {
          "packageUrl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.11.2?type=jar"
          "hash": null,
          "componentIdentifier": {
            "format": "maven",
            "coordinates": {
              "artifactId": "log4j-core",
              "classifier": "",
              "extension": "jar",
              "groupId": "org.apache.logging.log4j",
              "version": "2.11.2"
            }
          }
        }
      }
    }]
  }
}

ItemDescription
type=next-no-violationsThe next closest component version which has no violations.
type=next-non-failingThe next closest component version which does not fail any policy violations. Note: stageId is required for this type to be returned.
type=current The current version supplied, if there is no other suggestion. Note, this is now bundled with the next-* types.
dataComponent details for the version that matches the type.

The returned component hash 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.