sbomfs

README

sbomfs

A Go filesystem implementation that reads and writes data from a Software Bill of Materials (SBOMs).

Purpose

SBOMfs allows applications to store arbitrary data in standard SBOM files. Undearneath, it uses OpenSSF's Protobom stack, making it format agnostic (SPDX & CycloneDX sboms are supported).

Information stored in the SBOM data is exposed to go programs via SBOMfs' io/fs implementation.

Example

This example reads an existing SBOM, embeds provenance metadata into it, and reads it back using the standard io/fs interfaces:

package main

import (
	"fmt"
	"io/fs"
	"log"

	"github.com/carabiner-dev/sbomfs"
	"github.com/protobom/protobom/pkg/mod"
	"github.com/protobom/protobom/pkg/reader"
)

func main() {
	// Parse an existing SBOM file using protobom's reader.
	// The SPDX properties mod is needed to read properties stored as annotations.
	r := reader.New(reader.WithMod(mod.SPDX_READ_ANNOTATIONS_TO_PROPERTIES))
	doc, err := r.ParseFile("mysbom.spdx.json")
	if err != nil {
		log.Fatal(err)
	}

	// Create the sbomfs filesystem backed by the document.
	sfs := sbomfs.New(doc)

	// Write provenance data into the SBOM.
	provenance := []byte(`{"_type":"https://in-toto.io/Statement/v1","subject":[{"name":"my-project"}]}`)
	if err := sfs.WriteFile("provenance.intoto.json", provenance); err != nil {
		log.Fatal(err)
	}

	// Read the file back using the standard fs.ReadFile interface.
	data, err := fs.ReadFile(sfs, "provenance.intoto.json")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(data))

	// List all files stored in the SBOM.
	entries, err := fs.ReadDir(sfs, ".")
	if err != nil {
		log.Fatal(err)
	}
	for _, e := range entries {
		fmt.Println(e.Name())
	}
}

The module is lightweight, it has Protobom as its only dependency.

Current Uses

SBOMfs was developed as a component of the AMPEL attestation collector, allowing SBOMs to embed attested information.

License & Contributing

SBOMfs is released under the Apache 2.0 license by Carabiner Systems. Patches are welcome!

Documentation

Overview

Package sbomfs implements an fs.FS backed by protobom SBOM node properties.

Files are stored as properties on the root nodes of an SBOM document. A property with Name "sbomfs:hello.txt" and Data containing base64-encoded bytes represents a file named "hello.txt" with those decoded bytes as content.

Index

• type FS
  • func New(doc *sbom.Document) *FS
  • func (f *FS) Open(name string) (fs.File, error)
  • func (f *FS) ReadDir(name string) ([]fs.DirEntry, error)
  • func (f *FS) ReadFile(name string) ([]byte, error)
  • func (f *FS) RemoveFile(name string) error
  • func (f *FS) WriteFile(name string, data []byte) error

Types

type FS

type FS struct {
	// contains filtered or unexported fields
}

FS implements fs.FS, fs.ReadFileFS, and fs.ReadDirFS backed by protobom SBOM node properties. Files are stored as base64-encoded property values on the document's root nodes.

func New

func New(doc *sbom.Document) *FS

New creates a new FS from the given protobom document.

func (*FS) Open

func (f *FS) Open(name string) (fs.File, error)

Open opens the named file. It implements fs.FS.

func (*FS) ReadDir

func (f *FS) ReadDir(name string) ([]fs.DirEntry, error)

ReadDir reads the root directory and returns its entries. It implements fs.ReadDirFS.

func (*FS) ReadFile

func (f *FS) ReadFile(name string) ([]byte, error)

ReadFile reads the named file and returns its contents. It implements fs.ReadFileFS.

func (*FS) RemoveFile

func (f *FS) RemoveFile(name string) error

RemoveFile removes the named file from the filesystem.

func (*FS) WriteFile

func (f *FS) WriteFile(name string, data []byte) error

WriteFile writes data to the named file, creating it if it doesn't exist or overwriting it if it does. The data is base64-encoded and stored as a property on the first root node of the document.