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.
Remediation Output 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.
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 Sonatype 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 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 (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:
{
"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 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}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 Sonatype 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 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/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 |
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.