sdk

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2025 License: Apache-2.0 Imports: 22 Imported by: 7

Documentation

Overview

Package sdk provides the public API for Quark container image management.

Example (AuditImage)

Example_auditImage demonstrates auditing a Dockerfile and container image. 

package main

import (
	"log"

	"github.com/farcloser/quark/sdk"
)

func main() {
	// Create a plan
	plan := sdk.NewPlan("audit-plan")

	// Configure registry
	plan.AddRegistry(sdk.NewRegistry(&sdk.RegistryOpts{
		Domain:   "ghcr.io",
		Username: "user",
		Token:    "pass",
	}))

	// Create image reference
	image, err := sdk.NewImage(&sdk.ImageOpts{
		Name:    "myorg/myapp",
		Domain:  "ghcr.io",
		Version: "v1.0.0",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Audit Dockerfile and image with strict rules
	_, err = plan.Audit(&sdk.AuditArgs{
		Description:  "security-audit",
		Dockerfile:   "./Dockerfile",
		Source:       image,
		RuleSet:      sdk.RuleSetStrict,
		IgnoreChecks: []string{"DKL-DI-0005"},
	})
	if err != nil {
		log.Fatal(err)
	}
}
Example (BuildImage)

Example_buildImage demonstrates building a multi-platform container image. 

package main

import (
	"log"

	"github.com/farcloser/quark/sdk"
)

func main() {
	// Create a plan
	plan := sdk.NewPlan("my-build-plan")

	// Configure build nodes for each platform
	amd64Node, err := sdk.NewBuildNode(&sdk.BuildNodeOpts{
		Name:     "amd64-builder",
		Endpoint: "user@amd64-builder.example.com",
		Platform: sdk.PlatformAMD64,
	})
	if err != nil {
		log.Fatal(err)
	}

	plan.AddBuildNode(amd64Node)

	arm64Node, err := sdk.NewBuildNode(&sdk.BuildNodeOpts{
		Name:     "arm64-builder",
		Endpoint: "user@arm64-builder.example.com",
		Platform: sdk.PlatformARM64,
	})
	if err != nil {
		log.Fatal(err)
	}

	plan.AddBuildNode(arm64Node)

	// Build multi-platform image
	_, err = plan.Build(&sdk.BuildArgs{
		Name:       "my-app",
		Context:    "./app",
		Dockerfile: "Dockerfile",
		Tag:        "ghcr.io/myorg/myapp:v1.0.0",
		Nodes:      []*sdk.BuildNode{amd64Node, arm64Node},
	})
	if err != nil {
		log.Fatal(err)
	}
}
Example (CompleteWorkflow)

Example_completeWorkflow demonstrates a complete CI/CD workflow combining multiple operations. 

package main

import (
	"github.com/farcloser/quark/sdk"
)

func main() {
	// Create a plan that builds, audits, scans, and syncs an image
	plan := sdk.NewPlan("complete-workflow")

	// Configure registries
	plan.AddRegistry(sdk.NewRegistry(&sdk.RegistryOpts{
		Domain:   "staging.example.com",
		Username: "stg-user",
		Token:    "stg-pass",
	}))

	plan.AddRegistry(sdk.NewRegistry(&sdk.RegistryOpts{
		Domain:   "ghcr.io",
		Username: "prod-user",
		Token:    "prod-pass",
	}))

	// Configure build nodes
	amd64Node, _ := sdk.NewBuildNode(&sdk.BuildNodeOpts{
		Name:     "amd64-builder",
		Endpoint: "user@builder.example.com",
		Platform: sdk.PlatformAMD64,
	})

	plan.AddBuildNode(amd64Node)

	arm64Node, _ := sdk.NewBuildNode(&sdk.BuildNodeOpts{
		Name:     "arm64-builder",
		Endpoint: "user@arm-builder.example.com",
		Platform: sdk.PlatformARM64,
	})

	plan.AddBuildNode(arm64Node)

	// Step 1: Build image
	_, _ = plan.Build(&sdk.BuildArgs{
		Name:       "build-app",
		Context:    "./app",
		Dockerfile: "Dockerfile",
		Tag:        "staging.example.com/myapp:v1.0.0",
		Nodes:      []*sdk.BuildNode{amd64Node, arm64Node},
	})

	// Step 2: Audit Dockerfile and built image
	stagingImage, _ := sdk.NewImage(&sdk.ImageOpts{
		Name:    "myapp",
		Domain:  "staging.example.com",
		Version: "v1.0.0",
	})

	_, _ = plan.Audit(&sdk.AuditArgs{
		Description: "audit-app",
		Dockerfile:  "./app/Dockerfile",
		Source:      stagingImage,
		RuleSet:     sdk.RuleSetRecommended,
	})

	// Step 3: Scan for vulnerabilities
	_, _ = plan.Scan(&sdk.ScanArgs{
		Description: "scan-app",
		Source:      stagingImage,
		SeverityChecks: []sdk.ScanSeverityCheck{
			{Threshold: sdk.SeverityHigh, Action: sdk.ActionError},
			{Threshold: sdk.SeverityCritical, Action: sdk.ActionError},
		},
		Format: sdk.FormatJSON,
	})

	// Step 4: Sync to production if everything passes
	prodImage, _ := sdk.NewImage(&sdk.ImageOpts{
		Name:    "myorg/myapp",
		Domain:  "ghcr.io",
		Version: "v1.0.0",
	})

	_, _ = plan.Sync(&sdk.SyncArgs{
		Description: "promote-to-prod",
		Source:      stagingImage,
		Destination: prodImage,
	})
}
Example (ScanImage)

Example_scanImage demonstrates scanning an image for vulnerabilities. 

package main

import (
	"log"

	"github.com/farcloser/quark/sdk"
)

func main() {
	// Create a plan
	plan := sdk.NewPlan("scan-plan")

	// Configure registry
	plan.AddRegistry(sdk.NewRegistry(&sdk.RegistryOpts{
		Domain:   "ghcr.io",
		Username: "user",
		Token:    "pass",
	}))

	// Create image reference with digest
	image, err := sdk.NewImage(&sdk.ImageOpts{
		Name:    "myorg/myapp",
		Domain:  "ghcr.io",
		Version: "v1.0.0",
		Digest:  "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Scan for HIGH and CRITICAL vulnerabilities
	_, err = plan.Scan(&sdk.ScanArgs{
		Description: "security-scan",
		Source:      image,
		SeverityChecks: []sdk.ScanSeverityCheck{
			{Threshold: sdk.SeverityHigh, Action: sdk.ActionError},
			{Threshold: sdk.SeverityCritical, Action: sdk.ActionError},
		},
		Format: sdk.FormatTable,
	})
	if err != nil {
		log.Fatal(err)
	}
}
Example (SyncImage)

Example_syncImage demonstrates syncing an image between registries. 

package main

import (
	"log"

	"github.com/farcloser/quark/sdk"
)

func main() {
	// Create a plan
	plan := sdk.NewPlan("sync-plan")

	// Configure source registry (Docker Hub)
	plan.AddRegistry(sdk.NewRegistry(&sdk.RegistryOpts{
		Domain:   "docker.io",
		Username: "sourceuser",
		Token:    "sourcepass",
	}))

	// Configure destination registry (GitHub Container Registry)
	plan.AddRegistry(sdk.NewRegistry(&sdk.RegistryOpts{
		Domain:   "ghcr.io",
		Username: "destuser",
		Token:    "destpass",
	}))

	// Create source image reference with digest (required for security)
	sourceImage, err := sdk.NewImage(&sdk.ImageOpts{
		Name:    "library/alpine",
		Version: "3.20",
		Digest:  "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Create destination image reference
	destImage, err := sdk.NewImage(&sdk.ImageOpts{
		Name:    "myorg/alpine",
		Domain:  "ghcr.io",
		Version: "3.20",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Sync the image
	_, err = plan.Sync(&sdk.SyncArgs{
		Description: "alpine-sync",
		Source:      sourceImage,
		Destination: destImage,
	})
	if err != nil {
		log.Fatal(err)
	}
}
Example (VersionCheck)

Example_versionCheck demonstrates checking for image version updates. 

package main

import (
	"log"

	"github.com/farcloser/quark/sdk"
)

func main() {
	// Create a plan
	plan := sdk.NewPlan("version-check-plan")

	// Configure registry
	plan.AddRegistry(sdk.NewRegistry(&sdk.RegistryOpts{
		Domain:   "docker.io",
		Username: "user",
		Token:    "pass",
	}))

	// Create image reference with current digest
	image, err := sdk.NewImage(&sdk.ImageOpts{
		Name:    "library/alpine",
		Version: "3.20",
		Digest:  "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Check if tag points to a different digest (version update available)
	_, err = plan.CheckVersion("alpine-version-check", image, false)
	if err != nil {
		log.Fatal(err)
	}
}

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// RuleSetStrict represents strict audit rules.
	RuleSetStrict = AuditRuleSet{"strict"}
	// RuleSetRecommended represents recommended audit rules.
	RuleSetRecommended = AuditRuleSet{"recommended"}
	// RuleSetMinimal represents minimal audit rules.
	RuleSetMinimal = AuditRuleSet{"minimal"}
)
View Source 
var (
	// ErrDocumentEmpty indicates document resolved to empty content.
	ErrDocumentEmpty = secrets.ErrDocumentEmpty

	// ErrReferenceEmpty indicates reference is empty.
	ErrReferenceEmpty = secrets.ErrReferenceEmpty

	// ErrReferenceInvalidFormat indicates reference has invalid format.
	ErrReferenceInvalidFormat = secrets.ErrReferenceInvalidFormat

	// ErrReferenceEmptyParts indicates reference has empty required parts.
	ErrReferenceEmptyParts = secrets.ErrReferenceEmptyParts

	// ErrFieldsEmpty indicates no fields requested for retrieval.
	ErrFieldsEmpty = secrets.ErrFieldsEmpty

	// ErrFieldNotFound indicates requested field not found in secret.
	ErrFieldNotFound = secrets.ErrFieldNotFound
)

Secret reference errors (re-exported from internal/secrets for backward compatibility).

View Source 
var (
	// ErrScanMustHaveDigest indicates scan image requires digest specification.
	ErrScanMustHaveDigest = errors.New("scan image MUST have digest specified (scanning by tag alone is not allowed)")

	// ErrVulnerabilitiesFound indicates vulnerabilities were found at or above threshold.
	ErrVulnerabilitiesFound = errors.New("vulnerabilities found at or above threshold")
)

Scan errors.

View Source 
var (
	// ErrDigestMismatch indicates digest mismatch detected.
	ErrDigestMismatch = errors.New("DIGEST MISMATCH (possible tag mutation or supply chain attack)")

	// ErrVersionCheckImageRequired indicates version check requires an image.
	ErrVersionCheckImageRequired = errors.New("version check image is required")

	// ErrVersionCheckVersionRequired indicates version check image must have version specified.
	ErrVersionCheckVersionRequired = errors.New("version check image must have version specified")

	// ErrVersionCheckLatestNotSupported indicates version check does not support "latest" tag.
	ErrVersionCheckLatestNotSupported = errors.New("version check not supported for 'latest' tag")
)

Version check errors.

View Source 
var (
	// ErrImageNameRequired indicates image name is required.
	ErrImageNameRequired = errors.New("image name is required")

	// ErrImageVersionRequired indicates image version is required for tag reference.
	ErrImageVersionRequired = errors.New("cannot create tag reference without version")

	// ErrImageDigestRequired indicates image digest is required for digest reference.
	ErrImageDigestRequired = errors.New("cannot create digest reference without digest")

	// ErrInvalidImageDigest indicates image digest has invalid format.
	ErrInvalidImageDigest = errors.New("invalid image digest format")
)

Image errors.

View Source 
var (
	// ErrBuildNodeEndpointRequired indicates buildnode endpoint is required.
	ErrBuildNodeEndpointRequired = errors.New("buildnode endpoint is required")

	// ErrBuildNodePlatformRequired indicates buildnode platform is required.
	ErrBuildNodePlatformRequired = errors.New("buildnode platform is required")
)

BuildNode errors.

View Source 
var (
	// ErrSyncSourceRequired indicates sync source image is required.
	ErrSyncSourceRequired = errors.New("sync source image is required")

	// ErrSyncSourceDigestRequired indicates sync source image must have digest.
	ErrSyncSourceDigestRequired = errors.New(
		"sync source image MUST have digest specified (syncing by tag alone is not allowed)",
	)

	// ErrSyncDestinationRequired indicates sync destination image is required.
	ErrSyncDestinationRequired = errors.New("sync destination image is required")
)

Sync errors.

View Source 
var (
	// ErrBuildContextRequired indicates build context is required.
	ErrBuildContextRequired = errors.New("build context is required")

	// ErrBuildNodeRequired indicates at least one build node is required.
	ErrBuildNodeRequired = errors.New("at least one build node is required")

	// ErrBuildTagRequired indicates build tag is required.
	ErrBuildTagRequired = errors.New("build tag is required")
)

Build errors (additional).

View Source 
var (
	// ErrScanImageRequired indicates scan image is required.
	ErrScanImageRequired = errors.New("scan image is required")

	// ErrInvalidScanSeverity indicates an invalid scan severity value.
	ErrInvalidScanSeverity = errors.New("invalid scan severity")

	// ErrInvalidScanAction indicates an invalid scan action value.
	ErrInvalidScanAction = errors.New("invalid scan action")

	// ErrInvalidScanFormat indicates an invalid scan format value.
	ErrInvalidScanFormat = errors.New("invalid scan format")
)

Scan errors (additional).

View Source 
var (
	// ErrNoTrustPolicy indicates no trust policy is configured (no global signers and no per-image SignedBy).
	ErrNoTrustPolicy = errors.New("no trust policy configured: add TrustSigner to plan or SignedBy to image")

	// ErrImageNotSigned indicates no signature artifact was found for the image.
	ErrImageNotSigned = errors.New("image is not signed")

	// ErrSignatureInvalid indicates the signature failed cryptographic verification.
	ErrSignatureInvalid = errors.New("signature verification failed")

	// ErrSignerNotTrusted indicates the signer identity does not match any trusted signer.
	ErrSignerNotTrusted = errors.New("signer not trusted")

	// ErrSignatureDigestMismatch indicates the signature is over a different digest than expected.
	ErrSignatureDigestMismatch = errors.New("signature digest mismatch")

	// ErrMustSpecifyTagOrDigest indicates neither tag nor digest was provided.
	ErrMustSpecifyTagOrDigest = errors.New("must specify at least tag or digest")

	// ErrTagDrift indicates the tag resolves to a different digest than expected.
	ErrTagDrift = errors.New("tag drift detected")
)

Signature verification errors.

View Source 
var (
	// PlatformAMD64 represents linux/amd64.
	PlatformAMD64 = Platform{"linux/amd64"}
	// PlatformARM64 represents linux/arm64.
	PlatformARM64 = Platform{"linux/arm64"}
)
View Source 
var (
	// SeverityUnknown represents unknown severity.
	SeverityUnknown = ScanSeverity{"UNKNOWN"}
	// SeverityLow represents low severity.
	SeverityLow = ScanSeverity{"LOW"}
	// SeverityMedium represents medium severity.
	SeverityMedium = ScanSeverity{"MEDIUM"}
	// SeverityHigh represents high severity.
	SeverityHigh = ScanSeverity{"HIGH"}
	// SeverityCritical represents critical severity.
	SeverityCritical = ScanSeverity{"CRITICAL"}
)
View Source 
var (
	// ActionError causes scan to fail (default).
	ActionError = ScanAction{"error"}
	// ActionWarn logs vulnerabilities as warnings without failing.
	ActionWarn = ScanAction{"warn"}
	// ActionInfo logs vulnerabilities as info without failing.
	ActionInfo = ScanAction{"info"}
)
View Source 
var (
	// FormatTable represents table output.
	FormatTable = ScanFormat{"table"}
	// FormatJSON represents JSON output.
	FormatJSON = ScanFormat{"json"}
	// FormatSARIF represents SARIF output.
	FormatSARIF = ScanFormat{"sarif"}
)
View Source 
var (
	// ErrAuditFoundIssues indicates audit found issues.
	ErrAuditFoundIssues = errors.New("audit found issues")
)

Audit errors.

View Source 
var (
	// ErrAuditSourceRequired indicates audit requires either dockerfile or image.
	ErrAuditSourceRequired = errors.New("audit requires either dockerfile or image")
)

Audit errors (additional).

View Source 
var (
	// ErrEnvVarNotSet indicates required environment variable is not set.
	ErrEnvVarNotSet = errors.New("required environment variable not set")
)

Environment errors.

View Source 
var (
	// ErrInvalidAuditRuleSet indicates an invalid audit rule set value.
	ErrInvalidAuditRuleSet = errors.New("invalid audit rule set")
)

Audit errors (JSON validation).

View Source 
var (
	// ErrNoBuildNodesConfigured indicates no build nodes were added to a build operation.
	ErrNoBuildNodesConfigured = errors.New("no build nodes configured")
)

Build errors.

Functions

This section is empty.

Types

type AuditArgs added in v0.1.0 

type AuditArgs struct {
	Description  string        // Required - operation name
	Dockerfile   string        // Optional - Dockerfile path (one of Dockerfile or Source required)
	Source       *Image        // Optional - image to audit
	RuleSet      AuditRuleSet  // Optional - rule set (default: strict)
	IgnoreChecks []string      // Optional - checks to ignore
	Timeout      time.Duration // Optional - operation timeout
}

AuditArgs contains configuration options for creating an audit operation.

type AuditRuleSet 

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

AuditRuleSet represents audit rule severity.

func (*AuditRuleSet) MarshalJSON added in v0.1.0 

func (r *AuditRuleSet) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for AuditRuleSet.

func (*AuditRuleSet) String added in v0.1.0 

func (r *AuditRuleSet) String() string

String returns the string representation of the rule set.

func (*AuditRuleSet) UnmarshalJSON added in v0.1.0 

func (r *AuditRuleSet) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for AuditRuleSet.

type BuildArgs added in v0.1.0 

type BuildArgs struct {
	Name       string        // Required - operation name
	Context    string        // Required - build context directory
	Dockerfile string        // Optional - Dockerfile path (default: "Dockerfile")
	Nodes      []*BuildNode  // Required - at least one build node
	Tag        string        // Required - image tag
	Timeout    time.Duration // Optional - operation timeout
}

BuildArgs contains configuration options for creating a build operation.

type BuildNode 

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

BuildNode represents an SSH-accessible buildkit node.

func NewBuildNode added in v0.1.0 

func NewBuildNode(args *BuildNodeOpts) (*BuildNode, error)

NewBuildNode creates a new BuildNode from the provided arguments.

type BuildNodeOpts added in v0.1.0 

type BuildNodeOpts struct {
	Name     string   // Required - node name
	Endpoint string   // Required - SSH endpoint (IP, hostname, or SSH config alias)
	Platform Platform // Required - build platform (e.g., PlatformAMD64, PlatformARM64)
}

BuildNodeOpts contains configuration options for creating a build node.

type Handle added in v0.1.0 

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

Handle provides fluent chaining for all operations. Any operation can be chained after any other operation.

func (*Handle) After added in v0.1.0 

func (h *Handle) After(deps ...*Handle) *Handle

After adds dependencies on other operations. This handle's operation will not execute until all dependencies complete.

func (*Handle) Audit added in v0.1.0 

func (h *Handle) Audit(args *AuditArgs) (*Handle, error)

Audit chains an audit operation after this operation.

func (*Handle) Build added in v0.1.0 

func (h *Handle) Build(args *BuildArgs) (*Handle, error)

Build chains a build operation after this operation.

func (*Handle) CheckVersion added in v0.1.0 

func (h *Handle) CheckVersion(name string, source *Image, force bool) (*Handle, error)

CheckVersion chains a version check operation after this operation.

func (*Handle) Scan added in v0.1.0 

func (h *Handle) Scan(args *ScanArgs) (*Handle, error)

Scan chains a scan operation after this operation.

func (*Handle) Sync added in v0.1.0 

func (h *Handle) Sync(args *SyncArgs) (*Handle, error)

Sync chains a sync operation after this operation.

func (*Handle) VersionCheckResult added in v0.1.0 

func (h *Handle) VersionCheckResult() *VersionCheckResult

VersionCheckResult returns the result of a version check operation. Returns nil if this handle is not a version check operation or if not yet executed.

type Image 

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

Image represents a container image reference with optional version and digest.

func NewImage 

func NewImage(args *ImageOpts) (*Image, error)

NewImage creates a new Image from the provided arguments.

func (*Image) Digest 

func (img *Image) Digest() string

Digest returns the image digest if set.

func (*Image) Domain 

func (img *Image) Domain() string

Domain returns the image registry domain (normalized). Empty domain is normalized to "docker.io".

func (*Image) Name 

func (img *Image) Name() string

Name returns the image name in familiar form (user-facing). Returns shortened form for Docker Hub official images: "alpine" instead of "library/alpine". For the canonical repository path, use Path().

func (*Image) Path added in v0.1.0 

func (img *Image) Path() string

Path returns the canonical repository path (e.g., "library/alpine", "timberio/vector"). This is the full path as stored in the registry, which may differ from Name() for official images.

func (*Image) SetDigest added in v0.1.0 

func (img *Image) SetDigest(digestStr string) error

SetDigest sets the image digest.

func (*Image) SetVersion added in v0.1.0 

func (img *Image) SetVersion(version string)

SetVersion sets the image version/tag.

func (*Image) String added in v0.1.0 

func (img *Image) String() string

String returns the full serialized image reference. Format depends on what components are set:

  • With digest: "domain/path:version@digest" or "domain/path@digest"
  • Without digest: "domain/path:version" or "domain/path"

Examples:

  • "ghcr.io/farcloser/dns:v2025@sha256:379991..."
  • "docker.io/library/alpine:3.19"
  • "ghcr.io/org/image"

func (*Image) Version 

func (img *Image) Version() string

Version returns the image version/tag if explicitly set. Returns empty string if no version was provided.

type ImageOpts added in v0.1.0 

type ImageOpts struct {
	Name    string `json:"name"`              // Required - image name (e.g., "alpine", "org/image", "ghcr.io/foo/bar")
	Domain  string `json:"domain,omitempty"`  // Optional - registry domain (default: docker.io)
	Version string `json:"version,omitempty"` // Optional - image tag/version
	Digest  string `json:"digest,omitempty"`  // Optional - image digest for verification

	// InsecureNoSignature bypasses signature verification (dangerous).
	// Use only for legacy unsigned images that cannot be signed.
	InsecureNoSignature bool `json:"insecureNoSignature,omitempty"`

	// SignedBy specifies trusted signers for this specific image.
	// If set, signature must match one of these identities (global signers ignored).
	// If empty, global plan signers are used.
	SignedBy []SignerIdentity `json:"signedBy,omitempty"`
}

ImageOpts contains configuration options for creating an image reference.

type Plan 

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

Plan represents a declarative container image management plan. Operations are organized in a DAG for parallel execution of independent operations.

func NewPlan 

func NewPlan(name string) *Plan

NewPlan creates a new Plan with the given name.

func (*Plan) AddBuildNode added in v0.1.0 

func (plan *Plan) AddBuildNode(node *BuildNode)

AddBuildNode attaches an existing build node to the plan.

func (*Plan) AddRegistry added in v0.1.0 

func (plan *Plan) AddRegistry(reg *Registry)

AddRegistry attaches an existing registry to the plan. The registry's host is used as the key for credential lookup during operations.

func (*Plan) Audit 

func (plan *Plan) Audit(args *AuditArgs) (*Handle, error)

Audit creates an audit operation and registers it with the plan. Returns a handle for chaining additional operations.

func (*Plan) Build 

func (plan *Plan) Build(args *BuildArgs) (*Handle, error)

Build creates a build operation and registers it with the plan. Returns a handle for chaining additional operations.

func (*Plan) CheckVersion added in v0.1.0 

func (plan *Plan) CheckVersion(name string, source *Image, force bool) (*Handle, error)

CheckVersion creates a version check operation and registers it with the plan. Returns a handle for chaining additional operations.

func (*Plan) DryRun 

func (plan *Plan) DryRun() error

DryRun simulates plan execution without making changes.

func (*Plan) Execute 

func (plan *Plan) Execute(ctx context.Context) error

Execute runs the plan with the given context. Operations are executed in parallel where dependencies allow.

func (*Plan) GetDigest added in v0.1.0 

func (plan *Plan) GetDigest(ctx context.Context, image *Image) (string, error)

GetDigest returns the digest for an image from its registry. The registry credentials are automatically looked up by image domain.

func (*Plan) ListTags added in v0.1.0 

func (plan *Plan) ListTags(ctx context.Context, image *Image) ([]string, error)

ListTags returns all tags for an image repository. The registry credentials are automatically looked up by image domain.

func (*Plan) Scan 

func (plan *Plan) Scan(args *ScanArgs) (*Handle, error)

Scan creates a scan operation and registers it with the plan. Returns a handle for chaining additional operations.

func (*Plan) Sync 

func (plan *Plan) Sync(args *SyncArgs) (*Handle, error)

Sync creates a sync operation and registers it with the plan. Returns a handle for chaining additional operations.

The source image must have at least a tag or digest:

  • Tag only: Resolves to digest, verifies signature
  • Digest only: Verifies signature on digest
  • Tag + Digest: Verifies signature, detects tag drift
  • InsecureNoSignature: Skips verification (not recommended)

func (*Plan) TrustSigner added in v0.1.0 

func (plan *Plan) TrustSigner(signer SignerIdentity)

TrustSigner adds a signer identity to the global trusted signers list. Images without per-image SignedBy will be verified against these signers.

type Platform 

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

Platform represents a container platform architecture.

func (Platform) String 

func (platform Platform) String() string

String returns the string representation of the platform.

type Registry 

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

Registry represents a container registry with authentication.

func NewRegistry added in v0.1.0 

func NewRegistry(args *RegistryOpts) *Registry

NewRegistry creates a new Registry from the provided arguments. Empty domain is normalized to "docker.io" (Docker Hub default).

func (*Registry) Domain added in v0.1.0 

func (r *Registry) Domain() string

Domain returns the registry domain.

func (*Registry) Token added in v0.1.0 

func (r *Registry) Token() string

Token returns the registry token or password.

func (*Registry) Username 

func (r *Registry) Username() string

Username returns the registry username.

type RegistryOpts added in v0.1.0 

type RegistryOpts struct {
	Domain   string // Required - registry domain (e.g., "ghcr.io", "docker.io")
	Username string // Optional - registry username
	Token    string // Optional - registry token or password
}

RegistryOpts contains configuration options for creating a registry.

type ScanAction 

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

ScanAction represents how to handle vulnerabilities at a severity threshold.

func (*ScanAction) MarshalJSON added in v0.1.0 

func (a *ScanAction) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ScanAction.

func (*ScanAction) String added in v0.1.0 

func (a *ScanAction) String() string

String returns the string representation of the action.

func (*ScanAction) UnmarshalJSON added in v0.1.0 

func (a *ScanAction) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for ScanAction.

type ScanArgs added in v0.1.0 

type ScanArgs struct {
	Description    string              // Required - operation name
	Source         *Image              // Required - image to scan
	SeverityChecks []ScanSeverityCheck // Optional - severity checks (default: HIGH+CRITICAL error)
	Format         ScanFormat          // Optional - output format (default: table)
	Timeout        time.Duration       // Optional - operation timeout
}

ScanArgs contains configuration options for creating a scan operation.

type ScanFormat 

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

ScanFormat represents scan output format.

func (*ScanFormat) MarshalJSON added in v0.1.0 

func (f *ScanFormat) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ScanFormat.

func (*ScanFormat) String added in v0.1.0 

func (f *ScanFormat) String() string

String returns the string representation of the format.

func (*ScanFormat) UnmarshalJSON added in v0.1.0 

func (f *ScanFormat) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for ScanFormat.

type ScanSeverity 

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

ScanSeverity represents vulnerability severity.

func (*ScanSeverity) MarshalJSON added in v0.1.0 

func (s *ScanSeverity) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for ScanSeverity.

func (*ScanSeverity) String added in v0.1.0 

func (s *ScanSeverity) String() string

String returns the string representation of the severity.

func (*ScanSeverity) UnmarshalJSON added in v0.1.0 

func (s *ScanSeverity) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for ScanSeverity.

type ScanSeverityCheck 

type ScanSeverityCheck struct {
	Threshold ScanSeverity `json:"threshold,omitempty"`
	Action    ScanAction   `json:"action,omitempty"`
}

ScanSeverityCheck represents a threshold check with an action.

type SignerIdentity added in v0.1.0 

type SignerIdentity struct {
	// Subject is the identity subject pattern (email, OIDC subject, GitHub workflow path).
	// Supports wildcard patterns:
	//   - Exact match: "ci@mycompany.com"
	//   - Prefix match (ends with *): "https://github.com/org/repo/.github/workflows/*"
	Subject string `json:"subject"`

	// Issuer is the OIDC token issuer URL (exact match).
	// Examples: "https://accounts.google.com", "https://token.actions.githubusercontent.com"
	Issuer string `json:"issuer"`
}

SignerIdentity represents a trusted signer identity for signature verification. Used for keyless (Fulcio) signing where identity is attested via OIDC.

func (SignerIdentity) Matches added in v0.1.0 

func (s SignerIdentity) Matches(actualSubject, actualIssuer string) bool

Matches checks if an actual signer matches this trusted identity. Subject supports prefix matching when ending with *. Issuer requires exact match.

type SyncArgs added in v0.1.0 

type SyncArgs struct {
	Description string     // Required - operation name
	Source      *Image     // Required - source image (must have digest)
	Destination *Image     // Required - destination image
	Platforms   []Platform // Optional - platforms to sync (default: AMD64, ARM64)
}

SyncArgs contains configuration options for creating a sync operation.

type VersionCheckResult added in v0.1.0 

type VersionCheckResult struct {
	// CurrentVersion is the version that was checked.
	CurrentVersion string
	// LatestVersion is the latest available version.
	LatestVersion string
	// LatestDigest is the digest of the latest version.
	LatestDigest string
	// UpdateAvailable indicates whether an update is available.
	UpdateAvailable bool
}

VersionCheckResult contains the result of a version check operation.

Source Files

View all Source files

Directories

Path Synopsis
Package env provides trivial environment helpers
 Package env provides trivial environment helpers
Package filesystem provides low level primitives to ease FS manipulation
 Package filesystem provides low level primitives to ease FS manipulation
Package logger provides a way to initialize zerolog with sensible defaults.
 Package logger provides a way to initialize zerolog with sensible defaults.
Package secrets provides secrete retrieval capabilities (1password and age supported)
 Package secrets provides secrete retrieval capabilities (1password and age supported)
Package trust provides functions for configuring TLS certificate trust.
 Package trust provides functions for configuring TLS certificate trust.

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.