Under semantic versioning, a major version increase means incompatible changes. For a scanner that can mean renamed flags, different output formats, new default rules or changed exit codes. Test it in report only mode on a few repositories before it can block a single build.
What the version number promises
Semantic Versioning describes three parts. MAJOR increases when you make incompatible API changes, MINOR when you add functionality in a backward compatible way, and PATCH for backward compatible bug fixes. The key word is API. For a command line scanner, the API is its flags, its configuration file and its output.
Not every project follows the specification closely, and scanners have extra moving parts such as bundled rules and databases. A minor release can still change what is reported. Read release notes at every level.
What can break in a scanner upgrade
| Area | Example of a breaking change | Effect in CI |
|---|---|---|
| Flags | A flag renamed or removed | Job fails to start |
| Config | New file format or key names | Settings silently ignored |
| Output | Field names or structure change | Parsers and dashboards break |
| Exit codes | Different meaning for codes | Gates pass or fail wrongly |
| Rules | New default checks enabled | Sudden new findings |
| Data | Different advisory sources | Counts shift |
The silent ones hurt most. A job that fails to start gets noticed in minutes. A gate that now passes everything can go unnoticed for weeks.
A safe upgrade routine
- Read the release notes and note anything about flags, config, output or defaults.
- Pick three repositories: a small one, a large one and one with unusual layout.
- Run the new version in report only mode beside the old one.
- Diff the findings by package and version. Investigate differences in both directions.
- Confirm exit codes with a deliberately failing test case, so you know a failure still fails.
- Update parsers or dashboards that read the output.
- Roll out in waves, with a way to pin back.
Pin so the upgrade is your decision
Do not let a floating tag upgrade you. Pin the scanner version in your pipeline definition, change it in a reviewed pull request, and keep the previous pin in history so rollback is one revert.
Tell developers first
A new scanner version that suddenly reports 200 more findings will cost you trust. Post a short notice before the change: what is changing, when, and whom to ask. Share the diff you ran, so developers see the new findings are real and not noise.
Set a standing policy
Write the policy once: patch and minor versions after one repository smoke test, major versions after the full routine above. That keeps upgrades boring, which is what you want from security tooling. Safeguard handles tool updates inside its platform, and policies and gates give you one place to define what blocks a pull request, so a version change does not rewrite your rules.
Quick check
Can a patch release change my findings?
Yes, if the update includes new data or detection fixes. Version numbers describe code compatibility, not the content of reports.
Should I wait for the second release after a major version?
Often reasonable. Waiting for early fixes costs little, but do not wait so long that you fall outside the supported versions.
Sources
- Semantic Versioning, semver.org
Last reviewed: 19 October 2026.
