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 (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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
New creates a new Builder for the given stream identifier. The stream identifies the evidence stream (e.g., "my-org/prod").
func (*Builder) AddArtifact ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
AddReader adds an artifact from an io.Reader. The entire content is read into memory. Use AddFile for large files.
func (*Builder) AddReaderWithOptions ¶
AddReaderWithOptions adds an artifact from a reader with metadata options. Reading is bounded by MaxArtifactSizeBytes to prevent memory exhaustion.
func (*Builder) AddSource ¶
AddSource adds a source collector to the manifest. Sources are informational and do not affect verification.
func (*Builder) Build ¶
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 ¶
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.
Source Files