Understanding Golden Versions (Suggested Non-Breaking Versions) in IQ Server

.

Summary

When IQ Server evaluates components with security or policy violations, we provide remediation recommendations called "golden versions" or "suggested non-breaking versions." This article explains what golden versions are, how we select them, and why you might see different recommendations for the same component across your applications.

What are Golden Versions?

A golden version is our top recommended upgrade path for a vulnerable or policy-violating component. It represents the safest, most compatible version we can recommend based on our analysis.

Important: Your current version can be the golden version! If you're already using the optimal version, we'll confirm this rather than suggesting an unnecessary upgrade.

Requirements for a Golden Version

For a version to qualify as a golden version, it must meet all of these criteria:

• Non-Breaking Changes: Our data services score the version as having non-breaking changes
• No Critical Violations: The version has no policy violations with severity level 2 or higher (only low-severity violations are acceptable)
• Clean Dependencies: All transitive dependencies also have no critical violations
• Highest Compatibility Score: Among all qualifying versions, this version has the highest compatibility score from our analysis

In the Component Remediation API response, golden versions appear with the type recommended-non-breaking-with-dependencies.

How We Select Golden Versions

Our recommendation engine follows this process:

1. Feature Check: The developerSuggestNonBreakingVersion feature must be enabled in your IQ Server configuration.
2. Component Format: Currently, golden versions are only available for Maven components. Other formats (npm, NuGet, PyPI, etc.) receive basic remediation options only.
3. Version Analysis: We retrieve all available versions from our Hosted Data Services (HDS) and score them based on compatibility.
4. Policy Evaluation: We filter versions to those with severity less than 2 (no critical or high-severity violations).
5. Dependency Check: If you have our Advanced Recommendation Strategies license feature, we verify that all transitive dependencies also meet the severity requirements.
6. Top Selection: The highest-scored version that meets all criteria becomes your golden version recommendation.

Why Golden Versions May Differ Across Applications

You might see different golden versions for the same component in different applications. This is expected behavior because:

• Different applications may be using different major or minor version lines of the same component
• We recommend the best upgrade path from your current version, not a universal "best version"
• Application A on version 1.5.0 might get a golden version recommendation of 1.9.0, while Application B on version 2.0.0 gets 2.5.0

When You Might Not See a Golden Version

You won't receive a golden version recommendation if any of these conditions apply:

• Non-Maven Component: The component is not in Maven format (npm, NuGet, PyPI, Go, etc.)
• Feature Disabled: The developerSuggestNonBreakingVersion feature flag is not enabled
• No Compatible Versions: Our data services found no non-breaking versions for your component, or all non-breaking versions have critical policy violations
• Dependency Issues: All otherwise-qualifying versions have dependencies with critical violations
• Unknown Component: Our data services don't have sufficient data about the component (very new or obscure components)

Note: Even without a golden version, you'll still receive other remediation options like next-no-violations or next-non-failing if applicable.

Understanding Different Remediation Types

IQ Server provides several remediation recommendation types, each with different criteria:

Golden Versions (recommended-non-breaking-with-dependencies)

• Criteria: Severity < 2 (allows low-severity violations)
• Focus: Balance between compatibility and security
• Best for: Minimizing risk while avoiding breaking changes

Next No Violations (next-no-violations)

• Criteria: Absolutely zero violations of any severity
• Focus: Complete policy compliance
• Best for: Organizations requiring zero-tolerance policies

Next Non-Failing (next-non-failing)

• Criteria: No policy actions marked as "fail"
• Focus: Build success
• Best for: Preventing build failures
• Note: Requires a stage ID in the API request

Key Difference: Violation Thresholds

A version with one low-severity violation (severity level 1) will:

• Qualify as a golden version (severity 1 < 2)
• Not qualify as next-no-violations (requires zero violations)

This means you may see a golden version recommendation even when next-no-violations is not available.

Frequently Asked Questions

Can my current component version be the golden version?

Yes! If you're already on the optimal version based on our scoring and policy evaluation, we'll indicate that your current version is the golden version. This confirms you've made a good choice and don't need to upgrade.

Why do I see the same version in multiple recommendation categories?

Sometimes the same version meets the criteria for multiple recommendation types (golden version, next-no-violations, and next-no-violations-with-dependencies). Our API automatically deduplicates these, keeping only the highest-priority recommendation (golden version) in the response.

What if my component isn't Maven?

Golden version recommendations are currently only available for Maven components. For other formats (npm, NuGet, PyPI, Go, etc.), you'll receive basic remediation options like next-no-violations and next-non-failing.

Do I need special licensing for golden versions?

The basic golden version feature (recommended-non-breaking) requires the developerSuggestNonBreakingVersion feature flag to be enabled. The enhanced version with dependency checking (recommended-non-breaking-with-dependencies) requires our Advanced Recommendation Strategies license feature.