janbiasi/rollup-plugin-sbom

README

rollup-plugin-sbom

Create SBOMs (Software Bill of Materials) in CycloneDX format for your Vite and Rollup projects, including only the software you're really shipping to production.

A “software bill of materials” (SBOM) has emerged as a key building block in software security and software supply chain risk management. A SBOM is a nested inventory, a list of ingredients that make up software components.

– CISA (.gov) [full article]

Requirements and Compatibility

Plugin	Vite	Rollup	Rolldown	Node (latest LTS)	CDX Spec
v1	4, 5	3, 4	-	18, 20	1.5
v2	4, 5, 6	3, 4	-	18, 20, 22	1.6
v3	5, 6, 7, 8	4	1	20, 22, 24	1.6
v4	6, 7, 8	4	1	22, 24, 26	1.7

We're always supporting LTS Node.js versions and versions which still have security support. Plugin support will be dropped once a Node.js version reaches its final EOL.

Note

We currently support both CommonJS and ESM formats for now. We strongly recommend using the ESM format instead of CommonJS. The ESM format is compatible with modern platforms and runtimes, and most new libraries are now distributed only in ESM format. Learn more at https://nodejs.org/en/learn/modules/publishing-a-package#how-did-we-get-here

Installation

You can install the plugin via NPM with your favorite package manager:

npm install --save-dev rollup-plugin-sbom
pnpm install -D rollup-plugin-sbom
yarn add --dev rollup-plugin-sbom
bun add --dev rollup-plugin-sbom

Usage

Usage with Vite

import { defineConfig } from "vite";
import sbom from "rollup-plugin-sbom";

export default defineConfig({
  plugins: [sbom()],
});

// or

export default defineConfig({
  build: {
    // use rollupOptions for Vite < 8
    rolldownOptions: {
      plugins: [sbom()],
    },
  },
});

Usage with Rollup

import sbom from "rollup-plugin-sbom";

export default {
  plugins: [sbom()],
};

Usage with Rolldown

import { defineConfig } from "rolldown";
import sbom from "rollup-plugin-sbom";

export default defineConfig({
  plugins: [sbom()],
});

Configuration Options

Name	Default	Description
`specVersion`	`1.7`	The CycloneDX specification version to use
`rootComponentType`	`application`	The root component type, can be `library` or `application`
`outDir`	`cyclonedx`	The output directory where the BOM file will be saved.
`outFilename`	`bom`	The base filename for the SBOM files.
`outFormats`	`['json']`	The formats to output. Can be any of `json` and `xml` (note: `xml` requires `xmlbuilder2`).
`saveTimestamp`	`true`	Whether to save the timestamp in the BOM metadata.
`autodetect`	`true`	Whether to get the root package registered automatically.
`generateSerial`	`false`	Whether to generate a serial number for the BOM.
`sortLists`	`true`	Whether to sort lists in the BOM for deterministic output.
`includeWellKnown`	`true`	Whether to generate a SBOM in the `well-known` directory.
`supplier`	-	Provide organizational entity information
`beforeCollect`	-	Enhance the BOM before before collecting dependencies
`afterCollect`	-	Transform the BOM before after collecting dependencies

Optional Peer Dependencies

Some features require optional peer dependencies — see package.json for version details.

Serialization to XML on Node.js requires any of:
- xmlbuilder2

Debugging

This plugin added debug logs to gather information about how your SBOM is built so you can understand why which dependency was added to the graph. To enable debugging, you can set the logLevel option to "debug".

// rollup and rolldown
export default {
  logLevel: "debug",
};

// vite
export default defineConfig({
  build: {
    rollupOptions: {
      logLevel: "debug",
    },
  },
});

Example output from our test fixture "resolution"

General advice on when and how to read the debug information:

Find out which tools are registered (Registering tool <name>)
Find out which generated bundles are analyzed (Processing generated module <filename>)
Check analyzed third party modules and their tree (Processing <vendor-module> (imported by <filename> - depends on <transitive-deps>))

[plugin rollup-plugin-sbom] Autodetection enabled, trying to resolve root component
[plugin rollup-plugin-sbom] Saving timestamp to SBOM
[plugin rollup-plugin-sbom] Generating serial number for SBOM
[plugin rollup-plugin-sbom] Registering tool rollup-plugin-sbom
[plugin rollup-plugin-sbom] Registering tool vite
[plugin rollup-plugin-sbom] Registering tool rollup
[plugin rollup-plugin-sbom] Processing generated module "index.js"
[plugin rollup-plugin-sbom] Found 4 external modules within "index.js"
[plugin rollup-plugin-sbom] Found 3 unique external modules accross all bundles
[plugin rollup-plugin-sbom] Processing a (imported by /rollup-plugin-sbom/test/fixtures/resolution/node_modules/a/index.js - depends on c)
[plugin rollup-plugin-sbom] Attaching nested dependency "c" to parent component a
[plugin rollup-plugin-sbom] Processing c (imported by /rollup-plugin-sbom/test/fixtures/resolution/node_modules/a/node_modules/c/index.js - depends on none)
[plugin rollup-plugin-sbom] Processing side-effect (imported by /rollup-plugin-sbom/test/fixtures/resolution/node_modules/b/node_modules/side-effect/index.js - depends on none)
[plugin rollup-plugin-sbom] Processing b (imported by /rollup-plugin-sbom/test/fixtures/resolution/node_modules/b/index.js - depends on a, side-effect)
[plugin rollup-plugin-sbom] Attaching nested dependency "a" to parent component b
[plugin rollup-plugin-sbom] Processing a (imported by /rollup-plugin-sbom/test/fixtures/resolution/node_modules/b/node_modules/a/index.js - depends on none)
[plugin rollup-plugin-sbom] Attaching nested dependency "side-effect" to parent component b
[plugin rollup-plugin-sbom] Emitting SBOM asset to plugin-outdir/filename.json
[plugin rollup-plugin-sbom] Emitting SBOM asset to plugin-outdir/filename.xml
[plugin rollup-plugin-sbom] Emitting well-known file to .well-known/sbom

Sequence chart

sequenceDiagram
  participant Bundler
  box Hook Phases
    participant SB as Start Build
    participant MP as Module Parsed
    participant GB as Generate Bundle
    participant EF as Emit Files
  end
  box Plugin
    participant AN as Analyzer
    participant PR as Package Registry
  end
  activate Bundler
  activate SB
    Bundler->>SB: Register Root Component
    Bundler->>SB: Register Tools
  deactivate SB
  Bundler-->>MP: Invoke for each module
  activate MP
    MP-->>PR: Find and load package.json
  deactivate MP
  activate GB
    Bundler->>GB: Invoke with generated chunks
    AN->>AN: Build tree (recursive)
    GB->>AN: Analyze generated chunk
    AN->>GB: Send module tree
    GB->>PR: Request package.json for module
    PR->>GB: Return normalized package
    GB->>EF: Emit SBOM files
    GB->>EF: Emit Well Known
  deactivate GB
  EF->>Bundler: Finish build
  deactivate Bundler

Contributing

The main purpose of this repository is to continue evolving the plugin, making it faster and easier to use. We are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving the plugin.

Workflow

Fork the repository to your personal account
Ensure that all tests succeed (pnpm build-fixtures & pnpm test)
Propose changes within a PR to the original repository and write down the information required by the pull request template
Wait for an approval for running the required workflow checks and a code-review from one of the maintainers

Good First Issues

We have a list of good first issues that contain bugs that have a relatively limited scope. This is a great place to get started.

Contributors

Thanks goes to these wonderful people (emoji key):

_{Jan R. Biasi}
💼 💬 🧑‍🏫 💻

_{Jan Kott}
💻 🤔 🖋

_xenobytezero
🐛 💻

_DesselBane
🐛

_{Vinícius Goulart}
🚧

_PrettyCoffee
🚇

License

The plugin is licensed under MIT License