Component Remediation REST API - v2

NEW IN RELEASE 64

As a first step in providing a suggested remediation API, we provide similar data from the component intelligence panel version graph into a machine readable format.  The result of the request provides component remediation suggestions of policy violations on a per component basis.

Suggested Remediation

To find remediation options for a component's policy violation, the component is passed in and then valid remediation steps are returned.

By making an HTTP POST request to the following URL relative to IQ Server's base URL the suggested remediation for a given component can be retrieved:

Remediation by Application policy

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

The stageId query param is optional, but is required for the next-non-failing remediation output type.

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. Sample JSON request payload:

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

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

The stageId query param is optional, but is required for the next-non-failing remediation output type.

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. Sample JSON request payload:

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

Response - Version Changes

The first action for the remediation API is a version change. The first version change type is 'next-no-violations'. Here, the next closest version to the supplied version without a violation is returned. The version remediates all policy violations of any severity and if there is no version that meets this criteria nothing should be returned.  The second version change type is 'next-non-failing'. Here, the next closest version to the supplied version which does not fail any policy violations is returned for the specified stageId. Similar to the 'next-no-violations', if no version meets this criteria nothing should be returned.

It's possible to return the supplied version in the event that it satisfies requirements for the given type (e.g. it has no policy violations)


Sample JSON Response payload (formatted here for readability):

{
  "remediation" : {
    "versionChanges" : [ {
      "type" : "next-no-violations",
      "data" : {
        "component" : {
          "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": {
          "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=currentThe 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.