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 version of the provided component that does not violate any policies. If no version meets this criteria, this remediation type will not be present in the response. If there is a version that meets this criteria, it will be returned as the recommendation for this remediation type.
  • next-non-failing : This type of remediation contains the version of the provided component that does not fail the build for the specified stageId. So, the recommended version in this remediation type could potentially trigger warnings based on the policies, but would not fail the build. 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 be present in the response. If there is a version that meets this criteria, it will be returned as the recommendation for this remediation type.
  • next-no-violations-with-dependencies[1] NEW IN RELEASE 91 : This type of remediation is similar to next-no-violations above but it also guarantees that all the dependencies of recommended version do not violate any policy. If no version meets this criteria, this remediation type will not be present in the response. If there is a version that meets this criteria, it will be returned as the recommendation for this remediation type.
  • next-non-failing-with-dependencies[1] NEW IN RELEASE 91 This type of remediation is similar to next-non-failing above but it also guarantees that all the dependencies of recommended version do not fail the build for the specified stageId. So, the recommended verision in this remediation type could potentially trigger warnings based on the policies and its dependencies could also potentially trigger warnings based on the policies, but the recommended component version and its dependencies will not fail the build. Note that this type of remediation is only returned if the {stageId} parameter is supplied in the endpoint. If no version meets this criteria, this type will not be present in the response. If there is a version that 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 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 and next-non-failing-with-dependencies  remediation types 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 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 and next-non-failing-with-dependencies  remediation types 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/ch.qos.logback/logback-classic@1.2.3?type=jar",
                        "hash": null,
                        "componentIdentifier": {
                            "format": "maven",
                            "coordinates": {
                                "artifactId": "logback-classic",
                                "classifier": "",
                                "extension": "jar",
                                "groupId": "ch.qos.logback",
                                "version": "1.2.3"
                            }
                        }
                    }
                }
            },
            {
                "type": "next-non-failing",
                "data": {
                    "component": {
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.2.0?type=jar",
                        "hash": null,
                        "componentIdentifier": {
                            "format": "maven",
                            "coordinates": {
                                "artifactId": "logback-classic",
                                "classifier": "",
                                "extension": "jar",
                                "groupId": "ch.qos.logback",
                                "version": "1.2.0"
                            }
                        }
                    }
                }
            },
            {
                "type": "next-no-violations-with-dependencies",
                "data": {
                    "component": {
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.2.3?type=jar",
                        "hash": null,
                        "componentIdentifier": {
                            "format": "maven",
                            "coordinates": {
                                "artifactId": "logback-classic",
                                "extension": "jar",
                                "groupId": "ch.qos.logback",
                                "version": "1.2.3"
                            }
                        }
                    }
                }
            },
            {
                "type": "next-non-failing-with-dependencies",
                "data": {
                    "component": {
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.2.0?type=jar",
                        "hash": null,
                        "componentIdentifier": {
                            "format": "maven",
                            "coordinates": {
                                "artifactId": "logback-classic",
                                "extension": "jar",
                                "groupId": "ch.qos.logback",
                                "version": "1.2.0"
                            }
                        }
                    }
                }
            }
        ]
    }
}
ItemDescription
type=next-no-violationsThe component version which has no violations. The current version will be returned as recommended if it satisfies the recommendation strategy.
type=next-non-failingThe component version which does not fail any policy violations. The current version will be returned as recommended if it satisfies the recommendation strategy.
Note: stageId is required for this type to be returned.
NEW IN RELEASE 91
type=next-no-violations-with-dependencies
The component version that does not violate any policies, and in addition its dependencies also do not violate any policies. The current version will be returned as recommended if it satisfies the recommendation strategy.
NEW IN RELEASE 91
type=next-non-failing-with-dependencies
The component version that would not fail a build for provided stageId, and in addition its dependencies also would not fail a build for provided stageIdThe current version will be returned as recommended if it satisfies the recommendation strategy.
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.


[1]  The  next-no-violations-with-dependencies and next-non-failing-with-dependencies  recommendation strategies are advanced features that are made available through opt-in to the Advanced Development Pack for Lifecycle. These recommendation strategies will not be available in the API response if not enrolled into this feature.