config

package
v0.1.21 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package config provides configuration parsing for epack.yaml files.

This package handles the job configuration file format which declares:

  • Collectors: evidence gathering binaries
  • Tools: pack processing binaries (e.g., epack-tool-ai)
  • Signing: pack signing configuration
  • Registry: component resolution settings

Configuration files are validated for:

  • YAML alias bomb attacks (pre-parse)
  • Size limits (DoS prevention)
  • Structural validity (mutual exclusivity, required fields)
  • Security (secret name validation)

Index

Constants

This section is empty.

Variables

View Source 
var ErrAlreadyExists = errors.E(errors.AlreadyExists, "component already exists in config", nil)

ErrAlreadyExists is returned when a component already exists in the config.

Functions

func AddCollector 

func AddCollector(configPath, name string, cfg CollectorConfig) error

AddCollector adds a collector entry to the config file. Returns ErrAlreadyExists if the collector is already defined. Preserves existing file formatting and comments.

func AddRemote added in v0.1.11 

func AddRemote(configPath, name string, cfg RemoteConfig) error

AddRemote adds a remote entry to the config file. Returns ErrAlreadyExists if the remote is already defined. Preserves existing file formatting and comments.

func AddTool 

func AddTool(configPath, name string, cfg ToolConfig) error

AddTool adds a tool entry to the config file. Returns ErrAlreadyExists if the tool is already defined. Preserves existing file formatting and comments.

func HasCollector 

func HasCollector(configPath, name string) (bool, error)

HasCollector checks if a collector exists in the config file.

func HasRemote added in v0.1.11 

func HasRemote(configPath, name string) (bool, error)

HasRemote checks if a remote exists in the config file.

func HasTool 

func HasTool(configPath, name string) (bool, error)

HasTool checks if a tool exists in the config file.

func ValidateCollectorName 

func ValidateCollectorName(name string) error

ValidateCollectorName checks if a collector name is safe for use in paths.

func ValidateEnvironmentName 

func ValidateEnvironmentName(name string) error

ValidateEnvironmentName checks if an environment name is safe for use in paths.

func ValidatePlatform 

func ValidatePlatform(platform string) error

ValidatePlatform checks if a platform string is valid (e.g., "linux/amd64").

func ValidateRemoteName 

func ValidateRemoteName(name string) error

ValidateRemoteName checks if a remote name is safe for use in paths and URLs.

func ValidateToolName 

func ValidateToolName(name string) error

ValidateToolName checks if a tool name is safe for use in paths.

func ValidateUtilityName 

func ValidateUtilityName(name string) error

ValidateUtilityName checks if a utility name is safe for use in paths.

func ValidateVersion 

func ValidateVersion(version string) error

ValidateVersion checks if a version string is safe for use in filesystem paths. This prevents path traversal attacks via malicious lockfile version fields. Accepts semver-like versions: v1.2.3, v1.2.3-alpha.1, 1.2.3, etc. Rejects path separators, dot segments (..), and absolute paths.

Types

type CollectorConfig 

type CollectorConfig struct {
	Source  string         `yaml:"source,omitempty"`
	Binary  string         `yaml:"binary,omitempty"`
	Config  map[string]any `yaml:"config,omitempty"`
	Secrets []string       `yaml:"secrets,omitempty"` // Env var names to pass through to collector
}

CollectorConfig declares either a source-based collector or an external binary.

type EnvironmentConfig 

type EnvironmentConfig struct {
	// Remotes overrides remote configurations for this environment.
	Remotes map[string]RemoteConfig `yaml:"remotes,omitempty"`
}

EnvironmentConfig provides per-environment config overrides.

type JobConfig 

type JobConfig struct {
	Stream     string                     `yaml:"stream"`
	Output     string                     `yaml:"output,omitempty"`
	Platforms  []string                   `yaml:"platforms,omitempty"`
	Signing    SigningConfig              `yaml:"signing"`
	Collectors map[string]CollectorConfig `yaml:"collectors"`
	Tools      map[string]ToolConfig      `yaml:"tools,omitempty"`

	// Remotes configures remote registries for push/pull operations.
	// Each remote maps a name to its configuration.
	Remotes map[string]RemoteConfig `yaml:"remotes,omitempty"`

	// Environments provides per-environment config overrides.
	// Used with --env flag to override remote targets, labels, etc.
	Environments map[string]EnvironmentConfig `yaml:"environments,omitempty"`

	// Registry specifies an alternative registry for resolving collector/tool sources.
	// If empty, sources are resolved from GitHub releases. Not yet implemented.
	Registry string `yaml:"registry,omitempty"`

	// Registries specifies multiple registries for resolution with priority order.
	// First registry to resolve a component wins. Not yet implemented.
	Registries []RegistryConfig `yaml:"registries,omitempty"`

	// ToolPolicy configures tool access restrictions.
	// Not yet implemented - reserved for future use.
	ToolPolicy *ToolPolicy `yaml:"tool_policy,omitempty"`
}

JobConfig is the top-level epack.yaml model for collector and tool configuration. Note: The file may be named collectors.yaml (legacy) or epack.yaml (preferred).

func Load 

func Load(path string) (*JobConfig, error)

Load reads and validates an epack config file (collectors and tools).

func LoadUnvalidated added in v0.1.17 

func LoadUnvalidated(path string) (*JobConfig, error)

LoadUnvalidated reads an epack config file without running semantic validation. This is useful for status/introspection commands that should still work while the user is incrementally editing a new config.

func Parse 

func Parse(data []byte) (*JobConfig, error)

Parse validates raw epack config YAML and enforces size/structure limits before returning a JobConfig for collectors and tools.

func (*JobConfig) EffectiveRegistry 

func (c *JobConfig) EffectiveRegistry(globalRegistry string) string

EffectiveRegistry returns the registry to use for component resolution. Precedence: EPACK_REGISTRY env > project config > global config > "github" default. globalRegistry is loaded from ~/.config/epack/config.yaml (not yet implemented).

func (*JobConfig) HasSourceCollectors 

func (c *JobConfig) HasSourceCollectors() bool

HasSourceCollectors returns true if any collectors use source (not external binary).

func (*JobConfig) HasSourceComponents 

func (c *JobConfig) HasSourceComponents() bool

HasSourceComponents returns true if any collectors, tools, or remotes use source.

func (*JobConfig) HasSourceRemotes 

func (c *JobConfig) HasSourceRemotes() bool

HasSourceRemotes returns true if any remotes use source (not external binary).

func (*JobConfig) HasSourceTools 

func (c *JobConfig) HasSourceTools() bool

HasSourceTools returns true if any tools use source (not external binary).

func (*JobConfig) Validate 

func (c *JobConfig) Validate() error

Validate checks required fields and source/binary exclusivity.

type RegistryConfig 

type RegistryConfig struct {
	// Name is the registry identifier (e.g., "locktivity", "github").
	Name string `yaml:"name"`

	// URL is the registry endpoint URL.
	URL string `yaml:"url,omitempty"`

	// Priority determines resolution order (lower = higher priority).
	// If not specified, order in the registries array is used.
	Priority int `yaml:"priority,omitempty"`

	// Auth specifies authentication method.
	// Options: "none", "token", "oidc". Not yet implemented.
	Auth string `yaml:"auth,omitempty"`
}

RegistryConfig configures a component registry. Reserved for future multi-registry support.

type RemoteAuth 

type RemoteAuth struct {
	// Mode is the authentication mode.
	// Values: "device_code", "oidc", "api_key"
	Mode string `yaml:"mode,omitempty"`

	// Profile is an optional named credential profile (adapter-specific).
	Profile string `yaml:"profile,omitempty"`

	// OIDC contains OIDC-specific settings.
	OIDC *RemoteAuthOIDC `yaml:"oidc,omitempty"`

	// APIKey contains API key settings.
	APIKey *RemoteAuthAPIKey `yaml:"api_key,omitempty"`
}

RemoteAuth configures authentication preferences.

type RemoteAuthAPIKey 

type RemoteAuthAPIKey struct {
	// Env is the environment variable containing the API key.
	// epack never stores the key; the adapter reads the env var.
	Env string `yaml:"env,omitempty"`
}

RemoteAuthAPIKey contains API key authentication settings.

type RemoteAuthOIDC 

type RemoteAuthOIDC struct {
	// Provider is the OIDC provider name.
	// Values: "github_actions", "circleci", "generic"
	Provider string `yaml:"provider,omitempty"`

	// Audience is the expected audience claim.
	Audience string `yaml:"audience,omitempty"`
}

RemoteAuthOIDC contains OIDC authentication settings.

type RemoteConfig 

type RemoteConfig struct {
	// Source is the component source reference (e.g., "locktivity/epack-remote-locktivity@v1").
	// When set, the adapter binary is managed through the lockfile and sync system.
	// Mutually exclusive with Binary.
	Source string `yaml:"source,omitempty"`

	// Binary is the path to an external adapter binary.
	// Use this for locally-built or unmanaged adapters.
	// Mutually exclusive with Source.
	Binary string `yaml:"binary,omitempty"`

	// Adapter is the adapter name (e.g., "locktivity", "s3", "filesystem").
	// Maps to binary epack-remote-<adapter>.
	// If Source is set and Adapter is empty, it's inferred from the source.
	Adapter string `yaml:"adapter,omitempty"`

	// Target specifies the default target workspace/environment.
	Target RemoteTarget `yaml:"target,omitempty"`

	// Endpoint is an optional endpoint URL override.
	// Useful for enterprise deployments or regional control planes.
	Endpoint string `yaml:"endpoint,omitempty"`

	// Auth configures authentication preferences.
	Auth RemoteAuth `yaml:"auth,omitempty"`

	// Verify configures pre-push verification.
	Verify RemoteVerify `yaml:"verify,omitempty"`

	// Release configures default release metadata.
	Release RemoteRelease `yaml:"release,omitempty"`

	// Runs configures run syncing behavior.
	Runs RemoteRuns `yaml:"runs,omitempty"`

	// Extensions contains adapter-specific configuration.
	Extensions map[string]any `yaml:"extensions,omitempty"`

	// Transport configures transport-level security for adapter URLs.
	// SECURITY: Controls file:// URL confinement and loopback HTTP permissions.
	Transport RemoteTransport `yaml:"transport,omitempty"`

	// Secrets is a list of env var names to pass through to the remote adapter.
	// These are passed as-is (not renamed) to allow adapter-specific auth.
	Secrets []string `yaml:"secrets,omitempty"`
}

RemoteConfig configures a remote registry for push/pull operations.

func (*RemoteConfig) EffectiveAdapter 

func (r *RemoteConfig) EffectiveAdapter() string

EffectiveAdapter returns the adapter name for this remote. If Adapter is explicitly set, it's returned. If Source is set, the adapter name is inferred from the source repo name (e.g., "locktivity/epack-remote-locktivity@v1" -> "locktivity"). Returns empty string if neither Source nor Adapter is set.

type RemoteRelease 

type RemoteRelease struct {
	// Labels are default labels to apply to releases.
	Labels []string `yaml:"labels,omitempty"`

	// Notes are default release notes.
	Notes string `yaml:"notes,omitempty"`

	// Source configures source control metadata.
	Source *RemoteReleaseSource `yaml:"source,omitempty"`
}

RemoteRelease configures default release metadata.

type RemoteReleaseSource 

type RemoteReleaseSource struct {
	// Git contains Git source settings.
	Git *RemoteSourceGit `yaml:"git,omitempty"`

	// CI contains CI source settings.
	CI *RemoteSourceCI `yaml:"ci,omitempty"`
}

RemoteReleaseSource configures source control metadata for releases.

type RemoteRuns 

type RemoteRuns struct {
	// Sync enables automatic run syncing after push.
	// Defaults to true.
	Sync *bool `yaml:"sync,omitempty"`

	// Paths specifies glob patterns for finding result.json files.
	// Defaults to [".epack/runs/**/result.json"]
	Paths []string `yaml:"paths,omitempty"`

	// RequireSuccess fails push if run sync fails.
	RequireSuccess bool `yaml:"require_success,omitempty"`
}

RemoteRuns configures run syncing behavior.

func (*RemoteRuns) SyncEnabled 

func (r *RemoteRuns) SyncEnabled() bool

SyncEnabled returns true if run syncing is enabled (default true).

type RemoteSourceCI 

type RemoteSourceCI struct {
	// RunURLEnv is the env var containing the CI run URL.
	RunURLEnv string `yaml:"run_url_env,omitempty"`
}

RemoteSourceCI configures CI source metadata.

type RemoteSourceGit 

type RemoteSourceGit struct {
	// SHAEnv is the env var containing the Git SHA.
	SHAEnv string `yaml:"sha_env,omitempty"`

	// RepoEnv is the env var containing the repository name.
	RepoEnv string `yaml:"repo_env,omitempty"`
}

RemoteSourceGit configures Git source metadata.

type RemoteTarget 

type RemoteTarget struct {
	// Workspace is the target workspace (e.g., "acme").
	Workspace string `yaml:"workspace,omitempty"`

	// Environment is the target environment (e.g., "prod", "staging").
	Environment string `yaml:"environment,omitempty"`
}

RemoteTarget specifies the target workspace/environment.

type RemoteTransport 

type RemoteTransport struct {
	// FileRoot constrains file:// URLs from this adapter to this directory.
	// If set, any file:// URL path must be under this root directory.
	// SECURITY: Prevents adapters from directing reads/writes outside expected areas.
	FileRoot string `yaml:"file_root,omitempty"`

	// AllowLoopbackHTTP permits http:// URLs to localhost/127.0.0.1/::1.
	// SECURITY WARNING: Only enable for local development remotes.
	// Default: false (loopback HTTP is rejected).
	AllowLoopbackHTTP bool `yaml:"allow_loopback_http,omitempty"`
}

RemoteTransport configures transport-level security for adapter URLs.

type RemoteVerify 

type RemoteVerify struct {
	// Pack enables pack verification before upload.
	Pack bool `yaml:"pack,omitempty"`

	// Strict fails on warnings (not just errors).
	Strict bool `yaml:"strict,omitempty"`
}

RemoteVerify configures pre-push verification.

type SigningConfig 

type SigningConfig struct {
	Enabled bool   `yaml:"enabled"`
	Method  string `yaml:"method"`
}

SigningConfig configures pack signing.

type ToolConfig 

type ToolConfig struct {
	Source  string         `yaml:"source,omitempty"`
	Binary  string         `yaml:"binary,omitempty"`
	Config  map[string]any `yaml:"config,omitempty"`  // Config values passed as EPACK_CFG_* env vars
	Secrets []string       `yaml:"secrets,omitempty"` // Env var names to pass as EPACK_SECRET_* vars
}

ToolConfig declares a source-based tool. Tools are binaries that operate on packs (e.g., epack-tool-ai, epack-tool-policy).

type ToolPolicy 

type ToolPolicy struct {
	// Mode specifies the policy enforcement mode.
	// Options: "permissive" (allow unknown, warn), "strict" (deny unknown).
	// Not yet implemented.
	Mode string `yaml:"mode,omitempty"`

	// Allow specifies tools that are always allowed.
	// Supports glob patterns (e.g., "locktivity/*").
	// Not yet implemented.
	Allow []string `yaml:"allow,omitempty"`

	// Deny specifies tools that are always denied.
	// Takes precedence over Allow. Supports glob patterns.
	// Not yet implemented.
	Deny []string `yaml:"deny,omitempty"`
}

ToolPolicy configures tool access restrictions. Reserved for future tool policy support.

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.