Automated remediation
Automated remediation
Sonatype Lifecycle can create new pull requests (PRs) to update dependencies to versions without policy violations. Whenever a scan of your SCM repository’s default branch finds a component with a policy violation that hasn't already been identified, and a newer version without the violation is available, Lifecycle will try to update the component to that newer version. This approach is the preferred way to remediate a policy violation. The pull request contains links to the full Lifecycle report that triggered it, as well as links to any security vulnerability details.
Supported platforms: Azure DevOps, Bitbucket Cloud, Bitbucket Server, GitHub, GitLab
Supported ecosystems: Maven, npm, Gradle, Go
Golden PRs
The automated PRs created contain recommendations to upgrade dependencies to Golden Versions, when available.
Note
Automated remediation pull requests are created only for Maven components by default. For other ecosystems, pull requests are not created unless non-golden pull requests are enabled using the Source Control REST API.
Refer to Golden Versions and PRs for more details.
Automated Pull Requests to Update InnerSource Dependencies
Sonatype Lifecycle can automatically create new pull requests to update InnerSource dependencies to newer versions.
When a new non-major version of an InnerSource component is detected at the release stage during evaluation of an application, automated pull requests to update the older version of the InnerSource component are created in the SCM system.
To configure your SCM to enable creation of automated pull requests, refer to Automated PRs for InnerSource.
Prerequisites
To use Automatic Pull Requests:
| Topic | Requirement |
|---|---|
| Ecosystem | Maven, npm, Gradle, Go |
| Platform | Azure DevOps, Bitbucket Cloud, Bitbucket Server, GitHub.com, GitHub Enterprise, Gitlab |
| Repository Visibility | Repositories must be set to Private. Exceptions are GitHub Enterprise, which permits any visibility, and GitLab, which allows for Private or Internal repositories. |
| Token | You must have a token for your SCM system, and the token permissions must be configured correctly. |
| Manifest | The source repository must contain a manifest, like a pom.xml file, that includes version data for included components. |
| Repository URL | Your Application inside IQ Server must have a repository URL, which much be entered as an HTTPS, e.g. https://github.com/samplecount/samplerepo. The trailing .git is optional. If an ssh:// URL is used, Lifecycle will attempt to convert it to HTTPS. The .git:// style URL is not supported. Also note that the same URL may be used for multiple applications. |
| Pull Request option | The Automated remediation with GoldenPRs option must be enabled. |
| Default Branch | Your repository must have a default branch to use as the "base branch" for the pull request. The default value is the master branch. |
| IQ Server Build Stage | Any except for the develop stage. |
Also, note that the repository URL is configured at the Application level, but the other attributes can be at the Application, Organization, or Root Organization level.
The following diagram illustrates the ways that the creation of an automated remediation pull request can be triggered.
IQ Server Clone Directory Configuration
For each configured application, the repository will be cloned on the host that the IQ Server runs on. The default location is:
<sonatypeWork>/source-control
Note that the default for sonatypeWork is ./sonatype-work/clm-server.
To change the location of the repository clone for IQ Server Release 140 and later, use the Source Control Configuration REST API.
For release 139 and earlier, use the config.yml
sourceControl:
cloneDirectory: /your/path/here
Note that if the cloneDirectory does not have a leading "/", then the path will be relative to <sonatypeWork>.
Understanding Automated remediation with GoldenPRs behavior
The automated pull request functionality behaves in a specific, predictable way:
- The automated pull request workflow is triggered whenever your SCM repository's base branch is scanned.
- automated pull requests only work on components. It does not find or fix other vulnerabilities in your code.
- automated pull requests only bumps components to non-violating versions. It does not take any other remediation action. Review the pull requests and the linked Lifecycle report thoroughly to see other remediation options.
- A manifest file with component version information must be included in the repository. E.G. a pom.xml file
- The automated pull request follows a hierarchy when selecting a new component version:
- If a version resolves violations for the target component and violations for that component's transitive dependencies, that version is used.
- Otherwise, a version that resolves all violations for the target component is used.
- If neither of the above is true, then no pull request is generated.
- Solving transitive dependencies alone is not currently supported.
- This means that no pull request is created when bumping versions would only remediate a violation in a transitive dependency.
Component Versions Recommended by Automated PRs
- The Automated PR only bumps to component versions that are free from all violations. It will not bump to a version with fewer violations or less severe violations.
- The Automated PR will not recommend or bump to any pre-release versions of a component. For example, component versions like canary, ea, nightly, milestone, alpha, beta, pre, preview, dev, snapshot etc. will be excluded.
Golden-only automated pull request behavior
Automated remediation pull requests create pull requests only for Golden Versions by default.
Note
InnerSource components are not affected by this behavior and continue to receive automated pull requests when a remediation version is available.
- For Maven components, pull requests are created only when a Golden Version is available.
- For non-Maven components, pull requests are not created by default because Golden Version data is not available.
Non-golden pull requests can be enabled using the Source Control REST API. For instructions, see Enable non-Golden automated pull requests. There is no UI option for enabling non-golden pull requests.
Reading an Automated Pull Request
Pull requests generated by the automated pull request feature look like the example below, and contain useful information that helps developers evaluate the pull request for appropriateness.
- The description calls out the component or components being addressed by the pull request, along with the component versions.
- The Policy table shows which policy or policies are being violated.
- This section shows the Application and Organization's name as it exists inside IQ Server. It also shows the date of the evaluation and the IQ Server build stage associated with the evaluation.
- This link takes users to the full Lifecycle evaluation report associated with the pull request.
Daily Automated Pull Requests
The Source Control Configuration Overview screen displays recent activity related to automated pull request creation.
Summary information for each attempt to create a pull request will be shown in a table. This information is purged on a daily rotating basis determined by when the server was last started, so at any time a maximum of 24 hours of results is shown.
How to Access Daily Automated Pull Requests:
- Log in to Sonatype IQ Server.
- Navigate to Applications.
- Select the IQ application for which source control is configured.
- Scroll down to the Source Control section.
- Under Configuration, click the configured source control entry (for example, the repository URL). The Source Control Configuration page opens.
- Scroll to the bottom of the Source Control Configuration page.
- View the Daily Automated Pull Requests table, which displays recent automated pull request activity.
The Daily Automated Pull Requests table displays the daily automated PR activity. Hover on the icons in the Status column for a description of the reasons indicating a successful/unsuccessful PR creation.
| Status | Description |
|---|---|
| Indicates that a direct dependency in the project configuration could not be found. | |
| Indicates that a PR was created successfully to remediate the policy violation. | |
| Indicates an error occurred while creating this PR. Check server logs for more information. |
The Time Spent shows the total time taken in milliseconds, to checkout, remediate, push, and create the PR. The Start Time shows the timestamp and time zone when the process to create the automated PR was initiated.
Breaking Changes
If a pull request bumps a component to a different version that is likely to break the application, the pull request will inform the developer of these breaking changes, as in the image below.
Breaking Changes alerts the developer that this remediation path will require some extra effort. For more information about the violation and other potential remediation paths or strategies, users can click View Full Report at the bottom of the Pull Request.