image

package
v1.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2026 License: MIT Imports: 41 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Delete added in v1.1.0 

func Delete(ctx context.Context, s3Ref string) error

Delete removes an image tag from S3 by deleting all files under manifests/<image>/<tag>/. Only works with v1.1.0 layout. Blobs in blobs/sha256/ are NOT deleted — use GC for that.

func IsAttestationPlatform added in v1.8.0 

func IsAttestationPlatform(p string) bool

IsAttestationPlatform returns true if the platform represents an attestation manifest rather than a runnable image.

func ParseBucketRef added in v1.2.0 

func ParseBucketRef(s3Ref string) (bucket, prefix string, err error)

ParseBucketRef parses "s3://bucket/", "gs://bucket/", "az://container/", "local://path/", etc. into (bucket, prefix). For local:// refs with relative paths (./dir or ../dir), the full relative path is used as the bucket so that "local://./store/" gives bucket="./store".

func ParseConfigRef added in v1.2.0 

func ParseConfigRef(s3Ref string) (bucket, image string, err error)

ParseConfigRef parses a config reference into bucket and optional image name. s3://bucket/ -> bucket="bucket", image="" s3://bucket/myapp -> bucket="bucket", image="myapp" s3://bucket/dev/* -> bucket="bucket", image="dev/*" gs://bucket/myapp -> bucket="bucket", image="myapp" az://container/myapp -> bucket="container", image="myapp" local://./store/ -> bucket="./store", image="" local://./store/myapp -> bucket="./store", image="myapp"

func ParseDuration added in v1.2.0 

func ParseDuration(s string) (time.Duration, error)

ParseDuration parses durations like "7d", "30d". Standard Go durations (e.g. "24h") also work.

func Pull 

func Pull(ctx context.Context, s3Ref, imageTag string, opts PullOptions) error

Pull downloads an OCI image from S3 and imports it into the local Docker daemon. Supports both v1.1.0 (global blobs/sha256/ + manifests/) and v1.0.0 (per-tag) layouts.

func Push 

func Push(ctx context.Context, imageRef, s3Ref string, opts PushOptions) error

Push exports a local Docker image and uploads it to S3 using the v1.1.0 layout:

  • blobs -> blobs/sha256/<digest> (global, Intelligent-Tiering, cross-image dedup)
  • manifests -> manifests/<image>/<tag>/ (Standard storage class)

func SBOM added in v1.11.0 

func SBOM(ctx context.Context, s3Ref string, opts SBOMOptions) error

SBOM generates a Software Bill of Materials for an image stored in object storage. Output is written to opts.OutputPath or stdout if empty. Supported formats: cyclonedx (default), spdx-json, spdx.

func Scan added in v1.5.0 

func Scan(ctx context.Context, s3Ref string, opts ScanOptions) (int, error)

Scan downloads an image from S3 and scans it for vulnerabilities with Trivy. Returns the Trivy exit code (non-zero when vulnerabilities are found at the requested severity), and an error for non-Trivy failures (S3, IO, etc.).

func SetBucketConfig added in v1.2.0 

func SetBucketConfig(ctx context.Context, client storage.Backend, bucket string, cfg *BucketConfig) error

SetBucketConfig writes the bucket config to storage.

Types

type BucketConfig added in v1.2.0 

type BucketConfig struct {
	Default  ImageConfig            `yaml:"default,omitempty" json:"default,omitempty"`
	Images   map[string]ImageConfig `yaml:"images,omitempty" json:"images,omitempty"`
	Policies []PolicyRule           `yaml:"policies,omitempty" json:"policies,omitempty"`
}

BucketConfig holds the full s3lo configuration for a bucket, stored at s3://bucket/s3lo.yaml. Default applies to all images. Images contains per-image overrides keyed by name or glob pattern.

func GetBucketConfig added in v1.2.0 

func GetBucketConfig(ctx context.Context, client storage.Backend, bucket string) (*BucketConfig, error)

GetBucketConfig reads the bucket config from storage. Returns an empty config if not set.

func LoadBucketConfigFromFile added in v1.2.0 

func LoadBucketConfigFromFile(data []byte) (*BucketConfig, error)

LoadBucketConfigFromFile parses a BucketConfig from a local YAML file's bytes.

func (*BucketConfig) EffectiveConfig added in v1.2.0 

func (c *BucketConfig) EffectiveConfig(imageName string) ImageConfig

EffectiveConfig returns the resolved configuration for imageName by merging the bucket default with the first matching image override. More specific patterns (no wildcards, longer) take precedence over broader ones.

func (*BucketConfig) IsImmutable added in v1.2.0 

func (c *BucketConfig) IsImmutable(imageName string) bool

IsImmutable returns true if the effective config for imageName has immutability enabled.

type CopyOptions added in v1.3.0 

type CopyOptions struct {
	// Platform filters to a specific platform (e.g. "linux/amd64").
	// Empty means copy all platforms.
	Platform string
	// Force overwrites an existing tag even if the destination bucket is immutable.
	Force bool
	// OnStart is called once with the total bytes to transfer before any blobs are processed.
	OnStart func(totalBytes int64)
	// OnBlob is called for each content blob (config or layer) after it is processed.
	// platform is the OCI platform string (e.g. "linux/amd64") or "single" for single-arch.
	// skipped is true if the blob already existed at the destination.
	OnBlob func(platform, digest string, size int64, skipped bool)
}

CopyOptions controls copy behavior.

type CopyResult added in v1.2.0 

type CopyResult struct {
	BlobsCopied  int
	BlobsSkipped int
	Platforms    int // number of platforms copied (1 for single-arch)
}

CopyResult summarizes a copy operation.

func Copy added in v1.2.0 

func Copy(ctx context.Context, src, destRef string, opts CopyOptions) (*CopyResult, error)

Copy copies an image from src to dest. src can be:

  • s3://bucket/image:tag (S3 source)
  • <registry>/<image>:<tag> (OCI registry, e.g. ECR or Docker Hub)

dest must be s3://bucket/image:tag.

type CostEstimate added in v1.7.0 

type CostEstimate struct {
	S3Monthly        float64 `json:"s3_monthly" yaml:"s3_monthly"`
	S3NoDedupMonthly float64 `json:"s3_no_dedup_monthly" yaml:"s3_no_dedup_monthly"`
	ECRMonthly       float64 `json:"ecr_monthly" yaml:"ecr_monthly"`
	SavingsVsECR     float64 `json:"savings_vs_ecr" yaml:"savings_vs_ecr"`
	SavingsPct       float64 `json:"savings_pct" yaml:"savings_pct"`
}

CostEstimate holds projected monthly cost figures for a bucket.

type DoctorIssue added in v1.8.0 

type DoctorIssue struct {
	Image   string `json:"image"`
	Message string `json:"message"`
}

DoctorIssue describes a single problem found during a bucket health check.

type DoctorResult added in v1.8.0 

type DoctorResult struct {
	Bucket         string        `json:"bucket"`
	Scheme         string        `json:"scheme"`
	LayoutOK       bool          `json:"layout_ok"`
	ConfigOK       bool          `json:"config_ok"`
	ManifestIssues []DoctorIssue `json:"manifest_issues,omitempty"`
	OrphanedBlobs  int           `json:"orphaned_blobs"`
	OrphanedBytes  int64         `json:"orphaned_bytes"`
}

DoctorResult holds the findings of a bucket health check.

func Doctor added in v1.8.0 

func Doctor(ctx context.Context, s3BucketRef string) (*DoctorResult, error)

Doctor performs a health check on the given S3 bucket and returns findings. It checks layout structure, manifest integrity (all referenced blobs exist), orphaned blobs, and config validity.

type Finding added in v1.2.0 

type Finding struct {
	Label string
	OK    bool
}

Finding describes an observed bucket setting with a good/bad status.

type GCResult added in v1.1.0 

type GCResult struct {
	Scanned    int
	Deleted    int
	FreedBytes int64
	DryRun     bool
}

GCResult summarizes the outcome of a GC run.

func GC added in v1.1.0 

func GC(ctx context.Context, s3BucketRef string, dryRun bool) (*GCResult, error)

GC removes blobs in blobs/sha256/ that are not referenced by any manifest. If dryRun is true, no deletions are performed (safe to run at any time).

type HistoryEntry added in v1.8.0 

type HistoryEntry struct {
	PushedAt  time.Time `json:"pushed_at"`
	Digest    string    `json:"digest"`
	SizeBytes int64     `json:"size_bytes"`
}

HistoryEntry records a single push event for an image tag.

type ImageConfig added in v1.2.0 

type ImageConfig struct {
	Immutable *bool                 `yaml:"immutable,omitempty" json:"immutable,omitempty"`
	Lifecycle *LifecycleImageConfig `yaml:"lifecycle,omitempty" json:"lifecycle,omitempty"`
}

ImageConfig holds per-image s3lo configuration. All fields are pointers so we can distinguish "not set" from zero/false.

type ImageEntry 

type ImageEntry struct {
	Name string   `json:"name" yaml:"name"`
	Tags []string `json:"tags" yaml:"tags"`
}

ImageEntry represents an image and its available tags in the registry.

func List 

func List(ctx context.Context, s3Ref string) ([]ImageEntry, error)

List lists all images in a storage path. Supports both v1.1.0 (manifests/ prefix) and v1.0.0 (per-tag root) layouts. s3Ref should be like "s3://my-bucket/" or "local:///path/to/store/".

type ImageHistorySummary added in v1.8.0 

type ImageHistorySummary struct {
	Name           string    `json:"name" yaml:"name"`
	Tags           int       `json:"tags" yaml:"tags"`
	LastPushedAt   time.Time `json:"last_pushed_at" yaml:"last_pushed_at"`
	TotalSizeBytes int64     `json:"total_size_bytes" yaml:"total_size_bytes"`
}

ImageHistorySummary is the Mode A (bucket-level) output: one row per image.

func ListImageHistory added in v1.8.0 

func ListImageHistory(ctx context.Context, bucketRef string) ([]ImageHistorySummary, error)

ListImageHistory returns push-history summaries for every image in the bucket (Mode A). Scans all manifests/<image>/<tag>/history.json, groups by image.

type ImageInfo 

type ImageInfo struct {
	Reference string `json:"reference" yaml:"reference"`
	IsIndex   bool   `json:"is_index" yaml:"is_index"`
	// Single-arch fields (IsIndex == false).
	Manifest   ocispec.Manifest `json:"-" yaml:"-"`
	Layers     []LayerDetail    `json:"layers,omitempty" yaml:"layers,omitempty"`
	TotalSize  int64            `json:"total_size,omitempty" yaml:"total_size,omitempty"`
	Signatures []SignatureInfo  `json:"signatures,omitempty" yaml:"signatures,omitempty"`
	// Multi-arch fields (IsIndex == true).
	Platforms []PlatformInfo `json:"platforms,omitempty" yaml:"platforms,omitempty"`
}

ImageInfo holds metadata about an image stored on S3.

func Inspect 

func Inspect(ctx context.Context, s3Ref string) (*ImageInfo, error)

Inspect fetches and returns metadata about an image on S3. Supports both v1.1.0 (manifests/ prefix) and v1.0.0 (per-tag) layouts.

func (*ImageInfo) FormatJSON 

func (i *ImageInfo) FormatJSON() (string, error)

FormatJSON returns the ImageInfo as a pretty-printed JSON string.

type InitCheck added in v1.8.0 

type InitCheck struct {
	Label string `json:"label" yaml:"label"`
	OK    bool   `json:"ok" yaml:"ok"`
	Note  string `json:"note,omitempty" yaml:"note,omitempty"`
}

InitCheck describes a single check performed during bucket initialization.

type InitResult added in v1.8.0 

type InitResult struct {
	Bucket      string      `json:"bucket" yaml:"bucket"`
	Checks      []InitCheck `json:"checks" yaml:"checks"`
	ConfigWrote bool        `json:"config_wrote" yaml:"config_wrote"`
}

InitResult holds the outcome of a bucket initialization.

func Init added in v1.8.0 

func Init(ctx context.Context, s3BucketRef string) (*InitResult, error)

Init verifies bucket access, checks Intelligent-Tiering, and writes a default s3lo.yaml. It returns an InitResult describing what was found and done. Currently only supports S3 buckets (requires S3-specific APIs like GetBucketLocation).

type LayerDetail 

type LayerDetail struct {
	Digest    string `json:"digest" yaml:"digest"`
	Size      int64  `json:"size" yaml:"size"`
	MediaType string `json:"media_type" yaml:"media_type"`
}

LayerDetail describes a single image layer.

type LifecycleImageConfig added in v1.2.0 

type LifecycleImageConfig struct {
	KeepLast int      `yaml:"keep_last,omitempty" json:"keep_last,omitempty"`
	MaxAge   string   `yaml:"max_age,omitempty" json:"max_age,omitempty"`
	KeepTags []string `yaml:"keep_tags,omitempty" json:"keep_tags,omitempty"`
}

LifecycleImageConfig holds lifecycle retention settings for an image.

type LifecycleResult added in v1.2.0 

type LifecycleResult struct {
	Evaluated int
	Deleted   int
	DryRun    bool
}

LifecycleResult summarizes a lifecycle apply run.

func ApplyLifecycle added in v1.2.0 

func ApplyLifecycle(ctx context.Context, s3BucketRef string, cfg *BucketConfig, dryRun bool) (*LifecycleResult, error)

ApplyLifecycle evaluates the lifecycle settings in cfg against all images in the bucket and deletes manifest files for tags that should be purged. If dryRun is true, no deletions are performed.

type PlatformInfo added in v1.3.0 

type PlatformInfo struct {
	Platform  string        `json:"platform" yaml:"platform"`
	Digest    string        `json:"digest" yaml:"digest"`
	Layers    []LayerDetail `json:"layers,omitempty" yaml:"layers,omitempty"`
	TotalSize int64         `json:"total_size" yaml:"total_size"`
}

PlatformInfo holds metadata for one platform in a multi-arch image.

type PolicyCheck added in v1.11.0 

type PolicyCheck string

PolicyCheck identifies the kind of check a policy performs. 

const (
	PolicyCheckScan   PolicyCheck = "scan"
	PolicyCheckAge    PolicyCheck = "age"
	PolicyCheckSigned PolicyCheck = "signed"
	PolicyCheckSize   PolicyCheck = "size"
)

type PolicyResult added in v1.11.0 

type PolicyResult struct {
	Name    string `json:"name"`
	Check   string `json:"check"`
	Passed  bool   `json:"passed"`
	Message string `json:"message,omitempty"`
}

PolicyResult holds the result of a single policy check.

type PolicyRule added in v1.11.0 

type PolicyRule struct {
	Name  string      `yaml:"name" json:"name"`
	Check PolicyCheck `yaml:"check" json:"check"`
	// MaxSeverity is used by PolicyCheckScan: fail if vulnerabilities meet or exceed this level.
	// Valid values: LOW, MEDIUM, HIGH, CRITICAL.
	MaxSeverity string `yaml:"max_severity,omitempty" json:"max_severity,omitempty"`
	// MaxDays is used by PolicyCheckAge: fail if image is older than this many days.
	MaxDays int `yaml:"max_days,omitempty" json:"max_days,omitempty"`
	// MaxBytes is used by PolicyCheckSize: fail if total image size exceeds this many bytes.
	MaxBytes int64 `yaml:"max_bytes,omitempty" json:"max_bytes,omitempty"`
	// KeyRef is used by PolicyCheckSigned: required verification key reference.
	KeyRef string `yaml:"key_ref,omitempty" json:"key_ref,omitempty"`
}

PolicyRule is a single policy check stored in s3lo.yaml under the `policies` key.

type PullOptions added in v1.2.0 

type PullOptions struct {
	// Platform selects a specific platform from a multi-arch image (e.g. "linux/amd64").
	// Empty means auto-detect the host platform.
	Platform string
	// OnStart is called once with the total blob bytes before any downloads begin.
	OnStart func(totalBytes int64)
	// OnBlob is called for each blob after it is downloaded.
	// digest is the sha256 hex digest, size in bytes.
	OnBlob func(digest string, size int64)
}

PullOptions controls pull behavior.

type PushOptions added in v1.2.0 

type PushOptions struct {
	// Force overwrites an existing tag even if the bucket has immutability enabled.
	Force bool
	// OnStart is called once with the total blob bytes before any uploads begin.
	OnStart func(totalBytes int64)
	// OnBlob is called for each blob after it is processed (uploaded or skipped).
	// digest is the sha256 digest (without "sha256:" prefix), size in bytes, skipped=true if already existed.
	OnBlob func(digest string, size int64, skipped bool)
}

PushOptions controls push behavior.

type RecommendResult added in v1.2.0 

type RecommendResult struct {
	Bucket          string
	Findings        []Finding
	Recommendations []Recommendation
}

RecommendResult holds the findings and recommendations for a bucket.

func Recommend added in v1.2.0 

func Recommend(ctx context.Context, s3BucketRef string) (*RecommendResult, error)

Recommend analyzes the actual state of a bucket and returns data-driven recommendations. Currently only supports S3 buckets (requires S3-specific APIs like GetBucketVersioning).

type Recommendation added in v1.2.0 

type Recommendation struct {
	Title       string
	Description string
}

Recommendation describes a single actionable suggestion for the bucket.

type SBOMOptions added in v1.11.0 

type SBOMOptions struct {
	// Format is the SBOM output format: "cyclonedx" (default), "spdx-json", "spdx".
	Format string
	// Platform selects a specific platform from a multi-arch image (e.g. "linux/amd64").
	Platform string
	// OutputPath writes the SBOM to a file instead of stdout. Empty means stdout.
	OutputPath string
	// TrivyPath is the absolute path to the trivy binary.
	TrivyPath string
	// OnStart is called once with the total blob bytes before downloads begin.
	OnStart func(totalBytes int64)
	// OnBlob is called after each blob is downloaded.
	OnBlob func(digest string, size int64)
}

SBOMOptions controls SBOM generation behavior.

type ScanOptions added in v1.5.0 

type ScanOptions struct {
	// Platform selects a specific platform from a multi-arch image (e.g. "linux/amd64").
	// Empty means auto-detect the host platform.
	Platform string
	// Severity filters by severity level (comma-separated: "HIGH,CRITICAL").
	// Empty means Trivy default (all severities).
	Severity string
	// Format controls Trivy output format (table, json, sarif, cyclonedx, etc.).
	// Empty means Trivy default (table).
	Format string
	// TrivyPath is the absolute path to the trivy binary.
	TrivyPath string
	// OnStart is called once with the total blob bytes before any downloads begin.
	OnStart func(totalBytes int64)
	// OnBlob is called after each blob is downloaded.
	OnBlob func(digest string, size int64)
}

ScanOptions controls scan behavior.

type SignResult added in v1.9.0 

type SignResult struct {
	Digest     string
	KeyRef     string
	KeyID      string
	StoredPath string
	SignedAt   time.Time
}

SignResult is returned by Sign.

func Sign added in v1.9.0 

func Sign(ctx context.Context, s3Ref, keyRef string) (*SignResult, error)

Sign signs the manifest digest of the image identified by s3Ref and stores the signature at manifests/<image>/<tag>/signatures/<keyid>.json.

type SignatureInfo added in v1.9.0 

type SignatureInfo struct {
	KeyRef   string `json:"key_ref" yaml:"key_ref"`
	KeyID    string `json:"key_id" yaml:"key_id"`
	SignedAt string `json:"signed_at" yaml:"signed_at"`
}

SignatureInfo describes a stored signature for an image.

type SignatureRecord added in v1.9.0 

type SignatureRecord struct {
	SchemaVersion int    `json:"schemaVersion"`
	Digest        string `json:"digest"`
	KeyRef        string `json:"keyRef"`
	KeyID         string `json:"keyID"`
	Algorithm     string `json:"algorithm"`
	Signature     string `json:"signature"`
	Payload       string `json:"payload"`
	SignedAt      string `json:"signedAt"`
}

SignatureRecord is the JSON stored at manifests/<image>/<tag>/signatures/<slug>.json.

type StatsResult added in v1.2.0 

type StatsResult struct {
	Images         int              `json:"images" yaml:"images"`
	Tags           int              `json:"tags" yaml:"tags"`
	UniqueBlobs    int              `json:"unique_blobs" yaml:"unique_blobs"`
	BlobBytes      int64            `json:"blob_bytes" yaml:"blob_bytes"`
	LogicalBytes   int64            `json:"logical_bytes" yaml:"logical_bytes"`
	StorageByClass map[string]int64 `json:"storage_by_class" yaml:"storage_by_class"`
	Cost           CostEstimate     `json:"cost" yaml:"cost"`
}

StatsResult holds storage statistics for a bucket.

func Stats added in v1.2.0 

func Stats(ctx context.Context, s3BucketRef string) (*StatsResult, error)

Stats collects storage statistics for a bucket.

func (*StatsResult) DedupPercent added in v1.2.0 

func (s *StatsResult) DedupPercent() float64

DedupPercent returns the percentage of space saved by deduplication.

func (*StatsResult) DedupSavings added in v1.2.0 

func (s *StatsResult) DedupSavings() int64

DedupSavings returns bytes saved by cross-image blob deduplication.

type TagHistoryEntry added in v1.8.0 

type TagHistoryEntry struct {
	Tag        string    `json:"tag" yaml:"tag"`
	PushedAt   time.Time `json:"pushed_at" yaml:"pushed_at"`
	Digest     string    `json:"digest" yaml:"digest"`
	SizeBytes  int64     `json:"size_bytes" yaml:"size_bytes"`
	Superseded bool      `json:"superseded,omitempty" yaml:"superseded,omitempty"`
}

TagHistoryEntry is the Mode B (repository-level) output: one row per push across all tags. Superseded is true for older pushes of the same tag that have been overwritten.

func ListTagHistory added in v1.8.0 

func ListTagHistory(ctx context.Context, rawRef, imageName string) ([]TagHistoryEntry, error)

ListTagHistory returns push history for all tags of a single image (Mode B). rawRef may include the image name (e.g. "local://./local-s3/alpine") — imageName is extracted separately by the caller via ParseConfigRef. Scans manifests/<imageName>/*/history.json, merges and sorts newest-first.

type ValidateOptions added in v1.11.0 

type ValidateOptions struct {
	// TrivyPath is the path to the trivy binary (required for scan checks).
	TrivyPath string
}

ValidateOptions controls policy validation behavior.

type ValidateResult added in v1.11.0 

type ValidateResult struct {
	Reference string         `json:"reference"`
	Results   []PolicyResult `json:"results"`
	AllPassed bool           `json:"all_passed"`
}

ValidateResult holds the aggregate result of all policy checks.

func Validate added in v1.11.0 

func Validate(ctx context.Context, s3Ref string, opts ValidateOptions) (*ValidateResult, error)

Validate runs all policies in the bucket's s3lo.yaml against the given image tag. Returns AllPassed=true only when every policy passes. Scan checks require opts.TrivyPath to be set.

type VerifyResult added in v1.9.0 

type VerifyResult struct {
	Verified bool   `json:"verified"`
	Reason   string `json:"reason,omitempty"` // set when Verified == false
	Digest   string `json:"digest"`
	KeyRef   string `json:"keyRef"`
	KeyID    string `json:"keyID"`
	SignedAt string `json:"signedAt,omitempty"`
}

VerifyResult is returned by Verify.

func Verify added in v1.9.0 

func Verify(ctx context.Context, s3Ref, keyRef string) (*VerifyResult, error)

Verify checks whether a stored signature for s3Ref is valid against keyRef.

Returns (result, nil) for all cases where infrastructure worked:

  • result.Verified == true → signature valid
  • result.Verified == false → missing or invalid (caller should exit 1)

Returns (nil, err) for infrastructure failures (caller should exit 2).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.