gitbom

Documentation

Overview

Package gitbom implements GitBOM.

Read the spec at https://hackmd.io/@aeva/draft-gitbom-spec

GitBOM is neither git nor an SBOM.

It is an application of the git DAG, a widely used merkle tree with a flat-file storage format, to the challenge of creating build artifact trees in today’s language-heterogeneous open source environments. by generating artifact trees at build time, embedding the hash of the tree in produced artifacts, and referencing that hash in the next build step, GitBOM will enable the zero-end-user-effort creation of verifiable build trees. Furthermore, it will enable launch-time comparison of vulnerability data against a complete artifact tree for both open source and proprietary projects (if vuln data is traceable back to source file).

Objective It is desirable to enable efficient launch-time comparison of the verifiable and complete build tree of any executable component [1] against a then-current list of undesirable source files [2] which are known to be undesirable, where such a build tree contains unique referents for all sources from which the given executable object was composed.

[1]: binary, dynamically-linked library, container image, etc.

[2]: because vulnerabilities may be discovered between the time an executable is created and the time when it is run, these processes must be decoupled

Index

• type ArtifactTree
  • func NewGitBom() ArtifactTree
• type Identifier
  • func NewIdentifier(identity string) (Identifier, error)
• type Reference

Types

type ArtifactTree

type ArtifactTree interface {
	Identifier

	// AddReference adds a SHA1+SHA256 based git reference to the current GitBOM document.
	// obj []byte is the byte array to be tagged in the GitRef.
	// bom Identifier is the gitbom identifier of the artifact tree used to create the object.
	// The resulting reference is based on the GitRef format.
	// It returns an error if the SHA1 or SHA256 implementations fails.
	AddReference(obj []byte, bom Identifier) error

	// AddReferenceFromReader adds a SHA1+SHA256 based git reference to the current GitBOM document.
	// The resulting reference is based on the GitRef format.
	// The io.Reader will be continuously be read until the reader returns a non-null error.
	// If the io.Reader returns io.EOF, the read is considered to be complete.
	// Any other return value from Reader is an error.
	// The object length must be included.
	// If the amount of bytes read does not match the stated object length, an error is returned.
	AddReferenceFromReader(reader io.Reader, bom Identifier, objLength int64) error

	// References Returns a lsit of references in the order it will be printed.
	References() []Reference

	// String Returns the string representation of the GitBOM.
	String() string
}

ArtifactTree provides a common interface that assists with the creation and management of a GitBOM document.

func NewGitBom

func NewGitBom() ArtifactTree

NewGitBom creates a new ArtifactTree object. Thread Safety: none, apply your own controls.

Adding duplicate objects with the same Reference identity results in only one Reference entry. References are sorted in ascending order based on their UTF-8 values.

Implementation details: Adding a Reference is O(n) to discover duplicates. Generating a ArtifactTree is O(n*log(n)) as it sorts the existing refs.

type Identifier

type Identifier interface {
	Identity() string
}

func NewIdentifier

func NewIdentifier(identity string) (Identifier, error)

type Reference

type Reference interface {
	// Identity returns the GitRef identity of the object as a hex string.
	Identity() string

	// Bom returns an Identifier representing the dependency tree of the object represented by the Identity
	Bom() Identifier

	// String returns a ArtifactTree entry represented by this Reference.
	String() string
}