Component Remediation REST API

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

Note
Starting with IQ Server release 183, remediation suggestions are deduplicated between next-non-failing and next-non-failing-with-dependencies. A candidate version will appear in only one of these remediation types.

When a version satisfies both criteria, the API returns it as next-non-failing-with-dependencies, as this represents the stricter matching condition. In releases prior to 183, the same version could be returned in both remediation types.

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
This type of remediation is similar to next-no-violations above but it also guarantees that all the dependencies of the 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
This type of remediation is similar to next-non-failing above but it also guarantees that all the dependencies of the recommended version do not fail the build for the specified stageId. So, the recommended version 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.
recommended-non-breaking-with-dependencies
This is a non-breaking upgrade that remediates all policy violations for the component and all of its dependencies, without introducing breaking changes; this is also what Sonatype refers to as the Golden Version.
recommended-non-breaking
This is a non-breaking upgrade of the component that remediates policy violations for the component itself, without introducing breaking changes, but it may not remediate policy violations in that component’s dependencies.

Note
The current version will be returned as recommended if it satisfies the recommendation strategy.

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}&identificationSource={identificationSource}&scanId={scanId}

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

Note
The identificationSource and scanId query parameters are optional but are required if you want the remediation result to be based on third-party scan information.

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 Package URLs (purl) and Component Identifiers.

Here is a sample JSON payload with component information that can be submitted in the POST request body:

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

By including the input query parameter includeParentRemediation set to value true, the response will show whether the component is a direct dependency or transitive dependency and will contain the component details for remediation.

If the component is a transitive dependency, the response contains the remediation component details, based on the nearest parent dependency. The _type_field in the response indicates the type of remediation that is being suggested, i.e. version with next-no-violations-with-dependencies and next-non-failing-with-dependencies.

Example curl command

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"componentIdentifier": {"format":"maven","coordinates": {"artifactId":"logback-core,"extension":"jar","groupId":"ch.qos.logback","version":"1.3.14"}}}' 'http://localhost:8070/api/v2/components/remediation/application/{applicationInternalId}?stageId={stageId}&scanId={scanId}&includeParentRemediation=true'

Sample response if the component is a transitive dependency

{
    "remediation": {
        "versionChanges": [\
            {\
                "type": "next-no-violations-with-dependencies",\
                "data": {\
                    "component": {\
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-core@1.3.14?type=jar",\
                        "hash": null,\
                        "componentIdentifier": {\
                            "format": "maven",\
                            "coordinates": {\
                                "artifactId": "logback-core",\
                                "classifier": "",\
                                "extension": "jar",\
                                "groupId": "ch.qos.logback",\
                                "version": "1.3.14"\
                            }\
                        },\
                        "displayName": "ch.qos.logback : logback-core : 1.3.14"\
                    }\
                },\
                "directDependency": false,\
                "directDependencyData": [\
                    {\
                        "component": {\
                            "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.3.14?type=jar",\
                            "hash": null,\
                            "componentIdentifier": {\
                                "format": "maven",\
                                "coordinates": {\
                                    "artifactId": "logback-classic",\
                                    "classifier": "",\
                                    "extension": "jar",\
                                    "groupId": "ch.qos.logback",\
                                    "version": "1.3.14"\
                                }\
                            },\
                            "displayName": "ch.qos.logback : logback-classic : 1.3.14"\
                        }\
                    }\
                ]\
            },\
            {\
                "type": "next-non-failing-with-dependencies",\
                "data": {\
                    "component": {\
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-core@1.3.14?type=jar",\
                        "hash": null,\
                        "componentIdentifier": {\
                            "format": "maven",\
                            "coordinates": {\
                                "artifactId": "logback-core",\
                                "classifier": "",\
                                "extension": "jar",\
                                "groupId": "ch.qos.logback",\
                                "version": "1.3.14"\
                            }\
                        },\
                        "displayName": "ch.qos.logback : logback-core : 1.3.14"\
                    }\
                },\
                "directDependency": false,\
                "directDependencyData": [\
                    {\
                        "component": {\
                            "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.3.14?type=jar",\
                            "hash": null,\
                            "componentIdentifier": {\
                                "format": "maven",\
                                "coordinates": {\
                                    "artifactId": "logback-classic",\
                                    "classifier": "",\
                                    "extension": "jar",\
                                    "groupId": "ch.qos.logback",\
                                    "version": "1.3.14"\
                                }\
                            },\
                            "displayName": "ch.qos.logback : logback-classic : 1.3.14"\
                        }\
                    }\
                ]\
            }\
        ]
    }
}

If the component is a direct dependency, the response will contain the remediation component details and the type of remediation being suggested i.e. version with next-no-violations-with-dependencies and next-non-failing-with-dependencies.

Example curl command

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"componentIdentifier": {"format":"maven","coordinates": {"artifactId":"logback-classic,"extension":"jar","groupId":"ch.qos.logback","version":"1.3.14"}}}' 'http://localhost:8070/api/v2/components/remediation/application/{applicationInternalId}?stageId={stageId}&scanId={scanId}&includeParentRemediation=true'

Sample response if the component is a direct dependency

{
    "remediation": {
        "versionChanges": [\
            {\
                "type": "next-no-violations",\
                "data": {\
                    "component": {\
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.3.14?type=jar",\
                        "hash": null,\
                        "componentIdentifier": {\
                            "format": "maven",\
                            "coordinates": {\
                                "artifactId": "logback-classic",\
                                "classifier": "",\
                                "extension": "jar",\
                                "groupId": "ch.qos.logback",\
                                "version": "1.3.14"\
                            }\
                        },\
                        "displayName": "ch.qos.logback : logback-classic : 1.3.14"\
                    }\
                },\
                "directDependency": true\
            },\
            {\
                "type": "next-non-failing",\
                "data": {\
                    "component": {\
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.3.14?type=jar",\
                        "hash": null,\
                        "componentIdentifier": {\
                            "format": "maven",\
                            "coordinates": {\
                                "artifactId": "logback-classic",\
                                "classifier": "",\
                                "extension": "jar",\
                                "groupId": "ch.qos.logback",\
                                "version": "1.3.14"\
                            }\
                        },\
                        "displayName": "ch.qos.logback : logback-classic : 1.3.14"\
                    }\
                },\
                "directDependency": true\
            },\
            {\
                "type": "next-no-violations-with-dependencies",\
                "data": {\
                    "component": {\
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.3.14?type=jar",\
                        "hash": null,\
                        "componentIdentifier": {\
                            "format": "maven",\
                            "coordinates": {\
                                "artifactId": "logback-classic",\
                                "classifier": "",\
                                "extension": "jar",\
                                "groupId": "ch.qos.logback",\
                                "version": "1.3.14"\
                            }\
                        },\
                        "displayName": "ch.qos.logback : logback-classic : 1.3.14"\
                    }\
                },\
                "directDependency": true\
            },\
            {\
                "type": "next-non-failing-with-dependencies",\
                "data": {\
                    "component": {\
                        "packageUrl": "pkg:maven/ch.qos.logback/logback-classic@1.3.14?type=jar",\
                        "hash": null,\
                        "componentIdentifier": {\
                            "format": "maven",\
                            "coordinates": {\
                                "artifactId": "logback-classic",\
                                "classifier": "",\
                                "extension": "jar",\
                                "groupId": "ch.qos.logback",\
                                "version": "1.3.14"\
                            }\
                        },\
                        "displayName": "ch.qos.logback : logback-classic : 1.3.14"\
                    }\
                },\
                "directDependency": true\
            }\
        ]\
    }
}

Tip

You may experience longer response times, based on the number of dependencies detected for the specified component identifier. You can set includeParentRemediation to "false", to exclude the dependency remediation details, for a faster response.
This is currently available for Maven ecosystem only.

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}&identificationSource={identificationSource}&scanId={scanId}

Note
The identificationSource and scanId (or reportId) query parameters are optional but are required if you want the remediation result to be based on third-party scan information.

The identificationSource can be obtained from the Component Details Page in the UI.

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:

Assuming a local installation of IQ Server with its default configuration, the following example uses 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}'

Remediation by repository policy

The following endpoint, relative to IQ Server's base URL, may be invoked to list remediation recommendations for a repository component.

POST /api/v2/components/remediation/repository/{repositoryId}

Here is a sample JSON payload with component information that can be submitted in the POST request body:

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/repository/{repositoryId}'

Using package URL Identifiers

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

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

Item	Description
type=next-no-violations	The component version has no violations. The current version will be returned as recommended if it satisfies the recommendation strategy.
type=next-non-failing	The component version 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.
type=next-no-violations-with-dependencies	The component version 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.
type=next-non-failing-with-dependencies	The component version would not fail a build for the provided `stageId`, and in addition, its dependencies also would not fail a build for the provided `stageId`. The current version will be returned as recommended if it satisfies the recommendation strategy. Note: `stageId` is required for this type to be returned.
data	Component details for the version that matches the `type`.

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