An upgrade runbook for a vulnerable dependency should let any engineer confirm they are affected, choose a safe version, test the change, ship it with a rollback plan, and record the outcome. Write it once as a template, then copy it for each case so nobody starts from a blank page.
Why a template helps
Dependency fixes look simple, but the same mistakes repeat: upgrading the wrong copy, missing a transitive path, breaking a minor behavior, or closing the ticket before the fix reaches production. A runbook turns hard won habits into steps.
The template
1. Confirm exposure
- Which services use the package, at which version, directly or through another package?
- Is the vulnerable code reachable in how we use it?
- Is the service exposed to the conditions the advisory describes?
- Record the answers in the ticket.
2. Choose the target
- Find the earliest fixed version in the advisory and the latest compatible one.
- Read the release notes for breaking changes between your version and the target.
- If no fixed version exists, stop and use the options in patch or mitigate.
3. Change and test
- Update the manifest and the lock file in one pull request.
- Rebuild from clean and check the resolved version, including transitive copies.
- Run the test suite and any smoke test for the affected feature.
- Rescan to confirm the finding is gone.
4. Roll out
- Deploy to staging, then production by your normal path.
- Watch error rate and key metrics for a set period.
- State who is watching and when.
5. Roll back
- Name the previous build and the command or button to restore it.
- Say what signals trigger a rollback.
6. Close out
- Confirm the fixed version is live in every affected service.
- Update the ticket with the date, versions and evidence.
- Add a note if you learned something for the template.
Quick reference table
| Step | Done when |
|---|---|
| Confirm | Affected services and reachability are written down |
| Choose | Target version and breaking changes are noted |
| Change | Lock file updated, clean build resolves the target |
| Roll out | Production runs the fixed version |
| Close | Rescan is clean and evidence is attached |
Pitfalls to name in the runbook
- A lock file that was not committed, so CI resolves a different version.
- Multiple copies of the package at different versions in a monorepo.
- Container images built before the fix and still running.
- Fix merged but not deployed.
If you want help choosing between version strategies, see Maven or Gradle pinning.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how a fixed version and the changes needed are shown together, which is what steps 2 and 3 of the runbook ask you to find.
Where Safeguard fits
Safeguard's autonomous remediation can open fix pull requests for dependency issues. It is off by default, and every category is set to Manual until your team changes it, so a person stays in the loop.
Quick check
Should the runbook name a specific package?
No. Keep it generic and copy it into the ticket for each case, filling in the package, versions and services.
When is the ticket really done?
When the fixed version runs in every affected service in production, and a rescan confirms it.
Last reviewed: 19 October 2026.
