Endor Labs Upgrade Impact Analysis

Find safe dependency upgrades that fix vulnerabilities with minimal risk. Uses pre-computed data from the Endor Labs platform -- no scanning required.

Workflow

Step 1: Find Project UUID

The project UUID is often available from a prior scan. Check .endor/scan-full-results.json or the scan output first.

npx -y endorctl api list --resource Project -n <NAMESPACE> --filter "uuid==\"<PROJECT_UUID>\"" --field-mask="uuid,meta.name" 2>/dev/null

Or use getresource MCP tool with resourcetype: Project and name: {repo_name}.

If not found, inform the user and stop.

Step 2: Get Best Upgrade Recommendations

Query pre-computed safe upgrades. Do NOT run a scan.

npx -y endorctl api list -r VersionUpgrade -n <NAMESPACE> \
  --filter="context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==\"<PROJECT_UUID>\" and spec.upgrade_info.is_best==true and spec.upgrade_info.worth_it==true" \
  --field-mask="uuid,spec.name,spec.upgrade_info.is_best,spec.upgrade_info.is_latest,spec.upgrade_info.from_version,spec.upgrade_info.to_version,spec.upgrade_info.to_version_age_in_days,spec.upgrade_info.total_findings_fixed,spec.upgrade_info.total_findings_introduced,spec.upgrade_info.score_explanation,spec.upgrade_info.worth_it,spec.upgrade_info.upgrade_risk,spec.upgrade_info.direct_dependency_package" \
  --list-all 2>/dev/null

If user asked about a specific package, filter results to it. If general ("what should I upgrade?"), present all.

Step 3: Present Results

Pick the best upgrade per package: most totalfindingsfixed with lowest upgrade_risk.

## Upgrade Impact Analysis

**Project:** {project_name}

### Recommended Upgrades

| Package | From | To | Findings Fixed | Risk | Best? | Latest? |
|---------|------|----|---------------|------|-------|---------|
| {direct_dependency_package} | {from_version} | {to_version} | {total_findings_fixed} | {upgrade_risk} | {is_best} | {is_latest} |

### {package}: {from_version} -> {to_version}

| Metric | Value |
|--------|-------|
| Findings Fixed | {total_findings_fixed} |
| Findings Introduced | {total_findings_introduced} |
| Upgrade Risk | {upgrade_risk} |
| Target Version Age | {to_version_age_in_days} days |
| Score Explanation | {score_explanation} |

### Recommendation

- **LOW risk**: Safe to upgrade.
- **MEDIUM risk**: Review changes carefully. Test thoroughly before deploying.
- **HIGH risk**: Breaking code-level changes detected. See detailed CIA below.

For install commands, read references/install-commands.md.

Step 4: Evaluate High-Risk Upgrades (On Request Only)

Fetch CIA details only if user wants to evaluate a high-risk upgrade:

Only fetch if user asks about a HIGH risk upgrade:

npx -y endorctl api list -r VersionUpgrade -n <NAMESPACE> \
  --filter="context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==\"<PROJECT_UUID>\" and uuid==\"<UUID>\"" \
  --field-mask="spec.upgrade_info.cia_results" 2>/dev/null

Present CIA results: API changes, removed functions, signature changes, behavioral changes. Include action items and recommendation on whether to proceed.

Key Concepts

• isbest / worthit: Endor Labs' recommended upgrade with best fixes-vs-risk balance
• upgrade_risk: LOW (auto-upgrade safe), MEDIUM (review needed), HIGH (breaking changes via call graphs)
• cia_results: Code-level breaking changes for high-risk upgrades (fetched on demand)

For data source policy, read references/data-sources.md.

Error Handling