Create an endpoint that returns project health metrics #6250

Activity

1. mnonnenmacher

   added

   apiIssues related to the API.Issues related to the API.

   backendIssues related to the backend.Issues related to the backend.

   on Oct 15, 2026
2. mnonnenmacher

   added a parent issue on Oct 15, 2026

   • Add support for ORT's new project health model #6248
3. mnonnenmacher

   added the

   Feature

   issue type on Oct 15, 2026
4. mnonnenmacher

   marked this as blocked on Oct 15, 2026

   • Store project health metrics #6249
5. mnonnenmacher

   marked this as blocking on Oct 15, 2026

   • Show project health metrics in the UI #6251
6. Etsija commented on Oct 23, 2026

   

   Etsija

   on Oct 23, 2026

   Last edited by Etsija

   Contributor

   More actions

   OpenAI / Claude Opus 5.5: While building a local UI mock-up for #6251 against real Scorecard and CrOSSD results, we arrived at this API shape. It is a suggestion for whoever picks this up, not a decision.

   enum class HealthMetricCriticality { LOW, MEDIUM, HIGH, CRITICAL }
   
   data class HealthMetric(
       val advisor: AdvisorDetails,
       val name: String,
       val value: Double,
       val criticality: HealthMetricCriticality? = null,
       val reason: String? = null,
       val details: List<String> = emptyList(),
       val documentation: String? = null,
       val documentationLink: String? = null
   )
   
   data class PackageHealthMetrics(
       val identifier: Identifier,
       val purl: String,
       // The number of metrics for each criticality, leaving out zero counts.
       val criticalityCounts: Map<HealthMetricCriticality, Int>,
       val metrics: List<HealthMetric>
   )

   • GET /runs/{runId}/health-metrics returns a paged list of PackageHealthMetrics, filtered by identifier, purl and advisors, and sorted by identifier, purl or criticalityCounts (the number of CRITICAL metrics, then HIGH, then MEDIUM). The default is -criticalityCounts.
   • GET /runs/{runId}/health-metrics/advisors returns the names of the advisors that reported metrics, for the advisor filter.

   Why this shape:

   • One item per package, not one per metric as for vulnerabilities: a package has up to 22 metrics from the two advisors, which would bury each package in a flat list.
   • Counts per criticality, not a single highest criticality: for the 348 dependencies of express library that had metrics, 347 had at least one CRITICAL metric, mostly from Scorecard checks such as CII-Best-Practices and Fuzzing. So the highest criticality does not tell packages apart.
   • Documentation inline in the API, even if the database stores it only once as suggested in Store project health metrics #6249.

   Gaps in the ORT model worth knowing: there is no scale and no flag saying whether a higher value is better (Scorecard uses 0 to 10, CrOSSD mixes counts and percentages), and ORT drops the overall Scorecard score as well as checks that Scorecard could not compute.