Standardizing SBOM inclusion in npm package tarballs

[lcarva]

Packages distributed through npm registries currently have no standard mechanism for communicating what's inside them beyond package.json dependencies and source code inspection. This is particularly problematic for packages that ship compiled binaries or native addons. Consumers have no practical way to know what native libraries are statically linked into a .node binary or prebuilt executable.

An SBOM (Software Bill of Materials) included in the package tarball could address this gap. A well-known file location (e.g. sbom.cdx.json or sbom.spdx.json at the package root) would allow tooling, registries, and consumers to discover and use this information in a consistent way.

I couldn't find any existing work or prior discussion on this topic.

I'm raising this here because this feels like a packaging convention question. Please, let me know if another forum is better for this.

I'd be happy to help drive this effort forward with the community if there's an interest.

[ljharb]

An SBOM generated by the package author is useless to consumers - the exact layout of dependencies is unknowable until install time.

OpenSSF and SBOM folks have been claiming for years that maintainers should ship SBOMs, but unless they're shipping built binaries, there's simply no value to be had there.

[lcarva]

Thanks for the feedback, @ljharb.

I think there might be a misunderstanding about what's being proposed here, so let me try to clarify.

This isn't about describing the dependency tree or resolution graph. I agree that that's determined at install time. The goal is to provide better transparency into what each package itself contains. Consider a package shipping a prebuilt .node binary, what native libraries are statically linked into it? What versions? That's fully knowable by the author but currently there's no standard way to communicate it AFAIK.

unless they're shipping built binaries, there's simply no value to be had there.

I'd actually like to highlight that this acknowledges there is value for packages shipping built binaries, which is a significant part of what this proposal aims to address.

But SBOMs do carry value beyond binaries too. For example, packages that bundle dependencies via webpack or vendor code from other projects create invisible transitive dependencies that don't show up in package.json. An SBOM allows those dependencies to be surfaced, making CVE detection, for example, more accurate.

I do concede that for packages that don't bundle any dependency nor data, and don't contain binary content, the value of an SBOM is negligible.

To be clear, this proposal is about standardizing a convention for maintainers who choose to include an SBOM. It doesn't propose making them required. The idea is that when someone does want to provide this information, there's a consistent place and format for tooling and consumers to find it.

[ljharb]

There are very very few packages that have built binaries, though - I'd expect it to be a tiny fraction of a percent. Certainly these packages should be shipping some kind of BOM for their build output.

No packages should be including bundle output. Those that do are causing innumerable problems for downstream users, and including an SBOM isn't going to ameliorate them.

I think it's fine to declare a convention, but it won't achieve anything unless we can get enough packages that do ship binaries to adopt it. Do you have a plan for that?

[lcarva]

I think working with a few early adopters who ship prebuilt binaries would be the ideal approach. This will help validate that the convention is reasonable and actually solves the problem before opening for broader adoption. I don't have connections to the maintainers of those packages so help connecting would be greatly appreciated.