Extend Advisor to contain project health metrics

[mxleann]

Objective

We integrated new plugins to advise about dependency project health (In reference to #3317). From the suggested list we integrated CrOSSD and OpenSSF Scorecard. This integration is the basis for project health advice and enables the implementation of further plugins that use the existing infrastructure.

Calling the new plugins

location: plugins/commands/advisor/src/main/kotlin/AdviseCommand.kt and plugins/commands/plugins/src/main/kotlin/PluginsCommand.kt

With the new command flag --project-health or -p the project health providers can be called.

Project Health Providers

Client/API Integration

CrOSSD

location: clients/crossd/
Because an openAPI document is not available for CrOSSD, the needed enpoints have been implemented manually:

• getAvailableSnapshots(packageId)
• getAverageValues() --> average metric score value to determine score criticality
• getMetrics(packageId, snapshot)

OpenSSF Scorecard

location: clients/scorecard
The openAPI document for Scorecard was used to automatically generate the needed classes to request project health metrics from the database:

• /projects/{platform}/{org}/{repo}

Plugin Registration

For registering plugins that generate project health metric, a ProjectHealthProviderFactory has been implemented, that exists parallel to the AdviceProviderFactory. The plugins use this new factory.

CrOSSD

location: plugins/advisors/crossd/
@OrtPlugin(id = "Crossd", factory = ProjectHealthProviderFactory::class)

OpenSSF Scorecard

location: plugins/advisors/scorecard/
@OrtPlugin(id = "Scorecard", factory = ProjectHealthProviderFactory::class)

Advisor Result

location: model/src/ProjectHealth.kt
A project health class was defined and is used to hold the plugins outputs. It generalises the different outputs from the plugins.
The class has the following attributes:

package org.ossreviewtoolkit.model

enum class Criticality {
    Low,
    Medium,
    High,
    Critical
}

data class ProjectHealth(
    /** The name of project health metric.*/
    val name: String,

    /** The metric score.*/
    val value: Double,

    /**A rating how critical the value is.*/
    val criticality: Criticality? = null,

    /** The reason for the score.*/
    val reason: String? = null,

    /** Details about the findings.*/
    val details: List<String> = emptyList(),

    /** Summary of documentation about the metric.*/
    val documentation: String? = null,

    /** Link to the documentation about the metric.*/
    val documentationLink: String? = null,

    /** The id of the advisor plugin that fetched the metric.*/
    val source: String
)

CrOSSD

Criticality: The score criticality is determined by the scores deviation from the fetched AverageValues. These deviations can be configured in the plugins config.
Metric Documentation: The metrics documentation is taken from the official CrOSSD documentation and stored in plugins/advisors/crossd/src/main/kotlin/CrossdMetrics.kt for mapping.

OpenSSF Scorecard

Criticality: The score criticality is determined using the thresholds that are used in the webinteface. There was no documentation regarding the thresholds so we determined them by looking up different projects.
Metric Documentation: The metric documentation is provided by the API.

Project Health in Reports

This will be part of the second PR.

Priority One

• plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedModel.kt extended to include new plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedProjectHealth.kt
• plugins/reporters/web-app/src/main/kotlin/WebAppReporter.kt extended to include new model from 'plugins/reporters/web-app-template/src/models' and new components from plugins/reporters/web-app-template/src/components

AsciiDocs formated with the same Apache FreeMarker Template

Template: plugins/reporters/asciidoc/src/main/resources/templates/asciidoc/vulnerability_report.ftl

• PdfTemplate
• DocBookTemplate
• HtmlTemplate
• ManPageTemplate

Individual Implementation

• PlainTextTemplate (plugins/reporters/freemarker/src/main/resources/templates/plain-text/NOTICE_DEFAULT.ftl & NOTICE_SUMMARY.ftl)
• StaticHTML (StaticHtmlReporter.kt)

SBOM formats that might be changed

• SpdxDocument (SpdxDocumentModelMapper.kt)
• CycloneDX (CycloneDxModelMapper.kt)

proprietary file type, that should not be changed:

• AOSD2.1
• CtrlXAutomation
• Opossum
• FossID
• FossIdSnippet
• TrustSource