Skip to main content

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

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