builder

Documentation

Overview

Package builder creates evidence packs.

A Builder constructs evidence packs by adding artifacts and sources, computing digests, generating a manifest, and creating the ZIP archive.

Example:

b := builder.New("my-org/prod")
b.AddSource("github", "1.0.0")
b.AddFile("artifacts/config.json", "/path/to/config.json")
if err := b.Build("pack.zip"); err != nil {
    log.Fatal(err)
}

For signing, call sign.SignPackFile after Build:

if err := b.Build("pack.zip"); err != nil { ... }
if err := sign.SignPackFile(ctx, "pack.zip", signer); err != nil { ... }

Package builder creates evidence packs from artifacts.

The Builder type provides a fluent interface for adding files and writing the resulting pack:

b := builder.New("myorg/stream")
b.AddFile("./config.json")
b.AddFile("./data.json")
if err := b.Write("evidence.pack"); err != nil {
    log.Fatal(err)
}

Files are automatically digested using SHA-256 and stored in the artifacts/ directory within the pack. The builder generates a manifest.json with all artifact metadata.

Artifacts are sorted by path in the manifest for deterministic output.

Index

• type ArtifactOptions
• type ArtifactSource
• type Builder
  • func New(stream string) *Builder
  • func (b *Builder) AddArtifact(name string, data []byte) error
  • func (b *Builder) AddArtifactFile(name, filePath string) error
  • func (b *Builder) AddArtifactFileWithOptions(name, filePath string, opts ArtifactOptions) error
  • func (b *Builder) AddArtifactReader(name string, r io.Reader) error
  • func (b *Builder) AddArtifactReaderWithOptions(name string, r io.Reader, opts ArtifactOptions) error
  • func (b *Builder) AddArtifactWithOptions(name string, data []byte, opts ArtifactOptions) error
  • func (b *Builder) AddArtifacts(sources []ArtifactSource) error
  • func (b *Builder) AddBytes(path string, data []byte) error
  • func (b *Builder) AddBytesWithOptions(path string, data []byte, opts ArtifactOptions) error
  • func (b *Builder) AddFile(artifactPath, filePath string) error
  • func (b *Builder) AddFileWithOptions(artifactPath, filePath string, opts ArtifactOptions) error
  • func (b *Builder) AddReader(path string, r io.Reader) error
  • func (b *Builder) AddReaderWithOptions(path string, r io.Reader, opts ArtifactOptions) error
  • func (b *Builder) AddSource(name, version string) *Builder
  • func (b *Builder) Build(outputPath string) error
  • func (b *Builder) BuildContext(ctx context.Context, outputPath string) error
  • func (b *Builder) SetProvenance(prov pack.Provenance) *Builder

Types

type ArtifactOptions

type ArtifactOptions struct {
	ContentType string   // MIME type (e.g., "application/json")
	DisplayName string   // Human-readable name
	Description string   // Description of the artifact
	CollectedAt string   // Timestamp when collected (YYYY-MM-DDTHH:MM:SSZ)
	Schema      string   // Schema identifier
	Controls    []string // Control IDs this artifact supports
}

ArtifactOptions contains optional metadata for an artifact.

type ArtifactSource

type ArtifactSource struct {
	// DestPath is the path in the pack (e.g., "artifacts/config.json").
	// If empty for file sources, defaults to "artifacts/" + basename.
	DestPath string

	// SourcePath is the file path to read from.
	// Supports glob patterns (e.g., "./reports/*.json").
	// Mutually exclusive with Data.
	SourcePath string

	// Data is raw bytes to add directly.
	// Mutually exclusive with SourcePath.
	Data []byte

	// ContentType is the optional MIME type.
	ContentType string
}

ArtifactSource describes where to get artifact content.

type Builder

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

Builder constructs evidence packs.

func New

func New(stream string) *Builder

New creates a new Builder for the given stream identifier. The stream identifies the evidence stream (e.g., "my-org/prod").

func (*Builder) AddArtifact

func (b *Builder) AddArtifact(name string, data []byte) error

AddArtifact adds an artifact from in-memory bytes with auto-prefixed path. The name is automatically prefixed with "artifacts/" (e.g., "config.json" becomes "artifacts/config.json").

This is a convenience wrapper around AddBytes for the common case where all artifacts go in the artifacts/ directory.

func (*Builder) AddArtifactFile

func (b *Builder) AddArtifactFile(name, filePath string) error

AddArtifactFile adds an artifact from a file with auto-prefixed path. The name is automatically prefixed with "artifacts/" (e.g., "config.json" becomes "artifacts/config.json").

This is a convenience wrapper around AddFile for the common case where all artifacts go in the artifacts/ directory.

func (*Builder) AddArtifactFileWithOptions

func (b *Builder) AddArtifactFileWithOptions(name, filePath string, opts ArtifactOptions) error

AddArtifactFileWithOptions adds an artifact from a file with auto-prefixed path and metadata options.

func (*Builder) AddArtifactReader

func (b *Builder) AddArtifactReader(name string, r io.Reader) error

AddArtifactReader adds an artifact from an io.Reader with auto-prefixed path. The name is automatically prefixed with "artifacts/".

func (*Builder) AddArtifactReaderWithOptions

func (b *Builder) AddArtifactReaderWithOptions(name string, r io.Reader, opts ArtifactOptions) error

AddArtifactReaderWithOptions adds an artifact from a reader with auto-prefixed path and metadata options.

func (*Builder) AddArtifactWithOptions

func (b *Builder) AddArtifactWithOptions(name string, data []byte, opts ArtifactOptions) error

AddArtifactWithOptions adds an artifact with auto-prefixed path and metadata. The name is automatically prefixed with "artifacts/".

func (*Builder) AddArtifacts

func (b *Builder) AddArtifacts(sources []ArtifactSource) error

AddArtifacts adds multiple artifacts to the builder.

For sources with SourcePath containing glob patterns, all matching files are added. For sources with SourcePath pointing to a file, that file is added. For sources with Data, the raw bytes are added directly.

func (*Builder) AddBytes

func (b *Builder) AddBytes(path string, data []byte) error

AddBytes adds an artifact from in-memory bytes. The path must start with "artifacts/" per the spec.

func (*Builder) AddBytesWithOptions

func (b *Builder) AddBytesWithOptions(path string, data []byte, opts ArtifactOptions) error

AddBytesWithOptions adds an artifact from bytes with metadata options.

func (*Builder) AddFile

func (b *Builder) AddFile(artifactPath, filePath string) error

AddFile adds an artifact from a file on disk. The path must start with "artifacts/" per the spec. The file size is checked before reading to prevent memory exhaustion.

func (*Builder) AddFileWithOptions

func (b *Builder) AddFileWithOptions(artifactPath, filePath string, opts ArtifactOptions) error

AddFileWithOptions adds an artifact from a file with metadata options. The file is opened once and size-checked via Fstat to prevent TOCTOU races.

func (*Builder) AddReader

func (b *Builder) AddReader(path string, r io.Reader) error

AddReader adds an artifact from an io.Reader. The entire content is read into memory. Use AddFile for large files.

func (*Builder) AddReaderWithOptions

func (b *Builder) AddReaderWithOptions(path string, r io.Reader, opts ArtifactOptions) error

AddReaderWithOptions adds an artifact from a reader with metadata options. Reading is bounded by MaxArtifactSizeBytes to prevent memory exhaustion.

func (*Builder) AddSource

func (b *Builder) AddSource(name, version string) *Builder

AddSource adds a source collector to the manifest. Sources are informational and do not affect verification.

func (*Builder) Build

func (b *Builder) Build(outputPath string) error

Build creates the evidence pack at the specified output path. This computes all digests, generates the manifest, and creates the ZIP. If a signer was configured, it also signs the pack.

func (*Builder) BuildContext

func (b *Builder) BuildContext(ctx context.Context, outputPath string) error

BuildContext creates the evidence pack with a context for cancellation.

func (*Builder) SetProvenance

func (b *Builder) SetProvenance(prov pack.Provenance) *Builder

SetProvenance sets the provenance for the manifest. Use this when creating merged packs to document source packs.