Hoppr OpenSSF Scorecard Plugin

The Hoppr OpenSSF Scorecard Plugin can be used to populate component metadata in a CycloneDX Software Bill of Materials (SBOM) with data from OpenSSF Scorecard.

How to use this plugin

Get a Libraries.io API key

In order to use this plugin, an API key from Libraries.io is required.

• Log in to Libraries.io using a GitHub, GitLab, or BitBucket account
• Retrieve the API key from account settings

Once you have this API key, you can provide it to the plugin in one of the following ways:

• Set the LIBRARIES_API_KEY environment variable in the shell before running Hoppr

  export LIBRARIES_API_KEY="<your key here>"

• Create a Hoppr credentials file with an entry for https://libraries.io/api and an environment variable of your choosing that holds the value of the API key

  ---
  schemaVersion: v1
  kind: Credentials
  
  credential_required_services:
    - url: https://libraries.io/api
      user: ""
      pass_env: API_KEY_ENV_VAR

Create a transfer file

A Hoppr transfer file defines the stages to be run and which plugins will be run in those stages.

Create a transfer file that defines a stage with this plugin (identified by hoppr_openssf_scorecard.plugin) specified. For example:

---
schemaVersion: v1
kind: Transfer

stages:
  ScorecardData:
    plugins:
      - name: hoppr_openssf_scorecard.plugin
  Bundle:
    plugins:
      - name: hoppr.core_plugins.bundle_tar
        config:
          tarfile_name: tarfile.tar.gz

max_processes: 10

Run Hoppr

That's everything! Run hopctl bundle as normal and the SBOM with Scorecard data will be located in the specified bundle file.

How does it work?

Get the source control repository URL

Various API endpoints are leveraged in an attempt to retrieve a component's source control repository URL in order to request a Scorecard report.

First, a REST API or well-known metadata URL for the package manager specific to the PURL type of the component is tried.

PURL Type	URL Endpoint(s)
deb	https://sources.debian.org/api for Debian, https://api.launchpad.net/1.0 for Ubuntu
gem	https://rubygems.org/api/v1
git	Searches both https://api.github.com and https://gitlab.com/api/v4
golang	First https://proxy.golang.org, then https://libraries.io/api/Go if not found
helm	https://artifacthub.io/api/v1/packages/helm
maven	First, https://search.maven.org/remotecontent, then https://libraries.io/api/Maven if not found
npm	https://registry.npmjs.com
pypi	https://pypi.org/pypi
rpm	Repository metadata from either rpm repositories defined in the manifest file, or sensible defaults.

These are the defaults for RPM components if not provided.

Distribution	Metadata URL
Red Hat 7	http://mirror.centos.org/centos/7/os/x86_64 http://mirror.centos.org/centos/7/extras/x86_64
Red Hat/Rocky Linux 8	https://dl.rockylinux.org/pub/rocky/8/AppStream/x86_64/os https://dl.rockylinux.org/pub/rocky/8/BaseOS/x86_64/os https://dl.rockylinux.org/pub/rocky/8/PowerTools/x86_64/os https://dl.rockylinux.org/pub/rocky/8/extras/x86_64/os
Red Hat/Rocky Linux 9	https://dl.rockylinux.org/pub/rocky/9/AppStream/x86_64/os https://dl.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os https://dl.rockylinux.org/pub/rocky/9/CRB/x86_64/os https://dl.rockylinux.org/pub/rocky/9/extras/x86_64/os
Fedora	https://dl.fedoraproject.org/pub/fedora/linux/releases/<Fedora release>/Everything/x86_64/os

If a source control repository isn't found this way, the next attempt is to search Libraries.io and try to narrow down and intuit the correct repo URL from the results.

Finally, as a last-ditch effort, the GitHub API is queried in a similar fashion. If no repository URL is found by this point, the component is skipped and the plugin will move on to the next one.

If a repository URL was found during any of these passes, it gets added to the SBOM compoment's externalReferences as a URL with a type of vcs.

Request the report data from Scorecard API

For components that have a vcs repository URL (whether identified as outlined in the previous section or explicitly defined in the SBOM), a request is made to the OpenSSF Scorecard API using that project URL.

The response data is then used to populate the SBOM according to the taxonomy outlined below.

SBOM property taxonomy

Properties generated by this plugin consist of a name prefixed with hoppr:scorecard and a value corresponding to the associated Scorecard field.

Name	Description
hoppr:scorecard:date	Date of the Scorecard report
hoppr:scorecard:metadata	Metadata for the Scorecard report
hoppr:scorecard:repo:commit	Commit ref/SHA the report was run on
hoppr:scorecard:repo:name	Name of the repository
hoppr:scorecard:score	Aggregate score for all checks
hoppr:scorecard:scorecard:commit	Commit ref/SHA of Scorecard used to generate the report
hoppr:scorecard:scorecard:version	Version of Scorecard used to generate the report
hoppr:scorecard:check:Binary-Artifacts	Score for the Binary-Artifacts check
hoppr:scorecard:check:Branch-Protection	Score for the Branch-Protection check
hoppr:scorecard:check:CI-Tests	Score for the CI-Tests check
hoppr:scorecard:check:CII-Best-Practices	Score for the CII-Best-Practices check
hoppr:scorecard:check:Code-Review	Score for the Code-Review check
hoppr:scorecard:check:Contributors	Score for the Contributors check
hoppr:scorecard:check:Dangerous-Workflow	Score for the Dangerous-Workflow check
hoppr:scorecard:check:Dependency-Update-Tool	Score for the Dependency-Update-Tool check
hoppr:scorecard:check:Fuzzing	Score for the Fuzzing check
hoppr:scorecard:check:License	Score for the License check
hoppr:scorecard:check:Maintained	Score for the Maintained check
hoppr:scorecard:check:Packaging	Score for the Packaging check
hoppr:scorecard:check:Pinned-Dependencies	Score for the Pinned-Dependencies check
hoppr:scorecard:check:SAST	Score for the SAST check
hoppr:scorecard:check:Security-Policy	Score for the Security-Policy check
hoppr:scorecard:check:Signed-Releases	Score for the Signed-Releases check
hoppr:scorecard:check:Token-Permissions	Score for the Token-Permissions check
hoppr:scorecard:check:Vulnerabilities	Score for the Vulnerabilities check
hoppr:scorecard:check:Webhooks	Score for the Webhooks check

For descriptions of all the checks performed by Scorecard, see this table.