Build an SBOM from an renv lockfile

sbom_renv() describes the packages that an renv.lock pins. It reads the lockfile with renv, and it runs no code from the project and makes no network requests, except that advisories = TRUE downloads OSV's advisory data.

Usage

sbom_renv(
  lockfile = "renv.lock",
  library = NULL,
  author = getOption("sbom.author"),
  organization = getOption("sbom.organization"),
  regid = getOption("sbom.regid"),
  timestamp = NULL,
  overrides = NULL,
  embedded = TRUE,
  system = TRUE,
  advisories = FALSE,
  advisories_on_error = c("error", "continue")
)

Arguments

lockfile

The path to an renv.lock file.

library

Library paths to compare with the lockfile and to read what the lockfile does not record from. Each must exist. NULL uses the project's renv library when there is one.

author, organization

Who made the SBOM, recorded in its metadata. author may name several people; NA and empty names are dropped. Without either, an issue is recorded.

regid

The registration id of organization: the domain name, or URL, of the organization, under which it registers SWID tags (ISO/IEC 19770-2). A SWID tag names the organization as its creator with this regid. It must be a single string, from which leading and trailing white space is dropped. NULL, NA and an empty or blank string mean none; then the tag uses the placeholder http://invalid.unavailable, and when an organization was given, an issue is recorded. The default is the sbom.regid option, as author and organization read sbom.author and sbom.organization.

timestamp

The creation time, as a date-time or as seconds since 1970-01-01 UTC. An explicit timestamp wins. Without one, the SOURCE_DATE_EPOCH environment variable is used when it is set, so that builds are reproducible, and a note says so; otherwise it is now. Nix sets SOURCE_DATE_EPOCH to 1980-01-01 in every nix-shell, and when the timestamp is that value a note says it is a placeholder.

overrides

Values to assert where sbom found none, or found something different. NULL, a data frame or the path to a CSV file, with the character columns component (the name or ref of one component, as sbom built it, before any row moves it; embedded and system components only by ref), field, value, asserted_by and reason. field is one of "version", "license_spdx", "supplier_name", "supplier_url", "maintainer", "purl" and "download_location". Rows are applied in order, and each is recorded with who asserted it and why. An override that contradicts a found value wins and adds an override-conflict issue. Asserting "version" makes it the exact version, and moves the component's package URL to it unless a row asserts the "purl": a package URL at the old version takes the new one, and one without a version gains it when its type is cran, github, gitlab or bitbucket. A package file named for the old version is renamed for the new one, and any other is dropped, as are the checksums of the version found. An asserted version of R is also the version of the base packages, each with a record of the assertion. Asserting a CRAN "purl" (pkg:cran) makes the component a CRAN package, or a Bioconductor package when its repository_url names bioconductor.org. When a component's ref is its package URL, the ref follows the package URL that the overrides leave, and every reference to it moves too; a ref that another component already has is an error. Any other ref, such as unknown/<name>, stays as it is. An asserted field removes the component's issues that it answers, such as version-missing or purl-inferred. An issue that also states a fact that stays true is reworded instead, as info: that a package came from a git repository, once its package URL is asserted; that a dependency is missing, once its version and package URL are both asserted; and that a LinkingTo package is not installed, once its version is. The issues that name the components without a version, such as system-version-unknown, name only those still without one, and go when none is left. A blank value, an unknown component or field, or a missing column, is an error.

embedded

Whether to record the code that packages carry inside them. A package named in LinkingTo is recorded as an embedded component of the package that compiles it in, nested under that package, as inferred, at the version and with the license that the library, lockfile or manifest records for it now. A C or C++ library that a package copies into its src/ folder (source packages), or names in its COPYRIGHTS file or cph entries (source and installed packages), is recorded as a vendored component of that package, from the rules in inst/extdata/vendored.csv. The version is read from the library's header when there is one, and is otherwise unknown. A JavaScript or CSS library declared in htmlwidgets YAML, or found by the header comment of a file under www/, htmlwidgets/lib/ or lib/ (under inst/ in source packages), is recorded as an npm component of that package, from the rules in inst/extdata/javascript.csv. Its license is not read.

system

Whether to detect system libraries. A package's SystemRequirements text is mapped to system libraries and programs with the rules of the pak package, when it is installed. sbom turns off pak's update of those rules, so pak uses the rules it has cached or ships and makes no network request. The shared libraries that installed compiled code links are read with otool (macOS) or ldd (Linux).

advisories

Whether to list the OSV security advisories for the SBOM's packages, from the R Consortium advisory database that OSV publishes; see sbom_advisories(). Only exact versions are compared, of the packages whose package URL is a CRAN one (pkg:cran), packages from CRAN-like repositories among them, matched by name. A package with a CRAN package URL and a minimum version, or none, is named in an advisories-no-exact-version issue. An R package that is not known to come from CRAN, because sbom could not tell where it came from (as for a package that is not installed), or because it was installed from a local source or from GitHub, GitLab, Bitbucket or git, is named in an advisories-not-cran issue. Bioconductor packages are not compared: OSV does not cover them yet, and when the SBOM holds one a note says so. Matching is local, with the versions and package URLs after overrides, so no package name leaves the machine.

FALSE, the default, lists none, makes no network request and adds a note that no advisory data was on hand. TRUE downloads OSV's CRAN export, https://osv-vulnerabilities.storage.googleapis.com/CRAN/all.zip, and looks up the CVSS ratings of the upstream records it names at https://api.osv.dev, sending only their public ids. On a machine without network access, download that all.zip elsewhere and pass its path: it is read where it is, without the network and without ratings.

The SBOM lists what OSV says about these exact versions: a package without an advisory is not shown to be free of flaws, and an upstream CVSS rating describes the upstream flaw, not how exposed the R package is.

advisories_on_error

What happens when the advisory data cannot be downloaded or read, as when the download fails or the zip is damaged: "error", the default, is an error of class sbom_advisories_error that names the problem; "continue" builds the SBOM without advisories, with an R warning of class sbom_advisories_unavailable, a warning issue and a note that no advisory data was on hand. A download larger than 50 MB is refused as an error too. A CVSS rating that cannot be looked up never fails the call: it is left out, with an issue. The lookups stop at the first that times out or fails at the connection, and take at most two minutes in all.

Value

An <sbom> object. See sbom_components() to read it.

Details

Every locked package is listed at its locked version, as declared, with its source: CRAN or another repository, Bioconductor, GitHub, GitLab, Bitbucket, another git repository, or a local source. A package whose source the lockfile does not record is of ecosystem "unknown", with an issue. renv's Hash field is not a file checksum, so it is not recorded. R is listed at the version the lockfile names.

The project folder, the directory of the lockfile, is the root, with its git commit as the version when it is in a git repository. A lockfile does not say which packages the project uses directly. They are inferred: the locked packages that renv::dependencies() finds in the project's code, or, when it finds none, the locked packages that no other locked package requires. Both are recorded as inferred. renv itself, which renv infers from the lockfile, is left out, as is the code of a project nested in a subfolder and, in a package folder, the files a package does not ship.

Lockfiles from older versions of renv record only the names a package requires, or nothing at all, and no license or maintainer. What is missing is read from the installed package, but only when its version is the locked one. Otherwise it is recorded as unknown, with an issue. A package whose dependencies are unknown gets no dependency entry in CycloneDX, rather than an empty one.

When library is given, the versions installed there are compared with the lockfile, and each package missing on one side or installed at another version is an issue. Without library, the project's renv library is compared, together with the recommended packages in R's own library that the lockfile locks, since renv leaves those there. Without either, an issue says that nothing was compared. The SBOM still lists the locked versions.

Examples

sbom_renv(file.path(sbom_example("connect-app"), "renv.lock"), system = FALSE)
#> <sbom> connect-app
#> Components: 9
#> Relationships: 8
#> Issues: 5 (see sbom_issues())
#> Advisories: not requested.