Build an SBOM from a Posit Connect manifest

sbom_rsconnect() describes a content item that is deployed, or ready to deploy, to Posit Connect. It reads the manifest.json that rsconnect::writeManifest() writes, and it runs no code from the project and makes no network requests, except that advisories = TRUE downloads OSV's advisory data.

Usage

sbom_rsconnect(
  manifest = "manifest.json",
  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

manifest

The path to a manifest.json file.

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 package in the manifest is listed at the version the manifest records, as declared, with its source (CRAN or another repository, Bioconductor, GitHub, GitLab, Bitbucket, another git repository or a local source), read from its description or, when that names no repository, from the entry's own Source and Repository. A package whose source the manifest does not record is of ecosystem "unknown", with an issue. R is listed at the version in platform. A package that a recorded package depends on, but that the manifest does not record, is listed as unknown, with an issue. A package whose description records only its name, version and source says nothing of its dependencies, so it gets no dependency entry in CycloneDX, rather than an empty one, with an issue.

The folder of the manifest is the root, an application, with its git commit as the version when it is in a git repository. Each entry of the manifest's files is a component of type "file", contained by the root, with the MD5 checksum the manifest records; sbom does not read the files. As for sbom_renv(), the packages the root uses directly are inferred from the code in the folder, or, when none are found, from the recorded packages that no other recorded package requires.

Examples

sbom_rsconnect(file.path(sbom_example("connect-app"), "manifest.json"), system = FALSE)
#> <sbom> connect-app
#> Components: 8
#> Relationships: 8
#> Issues: 4 (see sbom_issues())
#> Advisories: not requested.