configuration

package
v0.3.16 Latest Latest
Warning

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

 Go to latest Published: May 22, 2026 License: MPL-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ProviderGitLab = "gitlab"
	ProviderGitHub = "github"
)

providerGitLab and providerGitHub are exported as constants so call sites can reference them by name instead of stringly-typed literals.

Variables

This section is empty.

Functions

func AllRegisteredControlNames added in v0.3.0 

func AllRegisteredControlNames() []string

AllRegisteredControlNames returns every name in the registry. Used by tests and by the configuration validator's misplacement check.

func FindClosestMatch added in v0.1.61 

func FindClosestMatch(unknownKey string, validKeys []string) string

FindClosestMatch finds the closest matching valid key using Levenshtein distance. Returns an empty string if no reasonable match is found.

func GroupsToExpression added in v0.1.34 

func GroupsToExpression(groups [][]string) string

GroupsToExpression converts DNF groups ([][]string) back to a human-readable expression string. Useful for display purposes.

Examples: 

[["a", "b"]]              → "a AND b"
[["a"], ["b"]]            → "a OR b"
[["a", "b"], ["c"]]       → "(a AND b) OR c"
[["a", "b"], ["c", "d"]]  → "(a AND b) OR (c AND d)"
[]                        → ""

func IsBenched added in v0.3.0 

func IsBenched(provider, controlName string) bool

IsBenched reports whether the given (provider, control) pair is currently on the dev-side bench. Findings matching are dropped before reaching any user-visible consumer, regardless of YAML state.

func IsControlApplicableTo added in v0.3.0 

func IsControlApplicableTo(controlName, provider string) bool

IsControlApplicableTo reports whether the named control applies to the given provider. Returns false for unknown control names.

func ParseRequiredExpression added in v0.1.34 

func ParseRequiredExpression(expr string) ([][]string, error)

ParseRequiredExpression parses a human-readable requirement expression and returns the equivalent DNF groups ([][]string).

Examples: 

"a AND b"             → [["a", "b"]]
"a OR b"              → [["a"], ["b"]]
"(a AND b) OR c"      → [["a", "b"], ["c"]]
"a AND (b OR c)"      → [["a", "b"], ["a", "c"]]
""                    → [] (empty — no requirements)

func ProviderNeedsActionMetadata added in v0.3.0 

func ProviderNeedsActionMetadata(provider string) bool

ProviderNeedsActionMetadata reports whether at least one control that depends on action-ref API metadata is currently shipping for the given provider. Returns false when every consumer is benched, letting the collector skip the GitHub API enrichment loop.

func ValidControlNames added in v0.1.44 

func ValidControlNames() []string

ValidControlNames returns all known control names from the configuration schema.

func ValidFlatKeys added in v0.1.61 

func ValidFlatKeys() map[string]struct{}

ValidFlatKeys returns every valid flattened key path recognized by the schema, e.g. "controls.branchMustBeProtected.enabled". This includes keys that may be commented out in the default config file.

func ValidateExpression added in v0.1.34 

func ValidateExpression(expr string) error

ValidateExpression checks whether an expression string is syntactically valid. Returns nil if valid, or a descriptive error if not.

func ValidateKnownKeys added in v0.1.43 

func ValidateKnownKeys(data []byte) []string

ValidateKnownKeys checks for unknown configuration keys in .plumber.yaml at both the control level and the sub-key level. It accepts both the legacy v1 schema (top-level `controls:`) and the v2 schema (provider- nested `gitlab.controls:` / `github.controls:`). Returns a list of warning messages for unknown keys, with suggestions where a close known key exists.

Types

type ActionsPinnedByShaControlConfig added in v0.3.0 

type ActionsPinnedByShaControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// TrustedOwners lists action-owner prefixes that are exempt from the
	// pin-by-SHA requirement. Only owners inside the workflow's existing
	// trust boundary should be listed here — "actions" and "github"
	// cover the first-party GitHub-owned actions the runtime trusts
	// implicitly. Adding a third-party owner here re-opens the exact
	// supply-chain risk the check exists to close.
	TrustedOwners []string `yaml:"trustedOwners,omitempty"`
}

ActionsPinnedByShaControlConfig configures the GitHub Actions supply- chain pinning check (ISSUE-701). Only meaningful on GitHub workflows.

func (*ActionsPinnedByShaControlConfig) IsEnabled added in v0.3.0 

func (c *ActionsPinnedByShaControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled

type AuthConfig added in v0.3.0 

type AuthConfig struct {
	// RequireAuth, when true, makes the analyze command exit non-zero
	// if no provider credentials are available. Default false on GitHub
	// (soft-degrade with visible banner, matching `gh` CLI ergonomics).
	// Has no effect on GitLab today (GitLab already hard-fails without
	// a token via CLI flag / env).
	RequireAuth *bool `yaml:"requireAuth,omitempty"`
}

AuthConfig holds per-provider authentication knobs. Currently only GitHub uses this; the type is provider-agnostic so GitLab can adopt it later without a schema change.

func (*AuthConfig) IsRequireAuth added in v0.3.0 

func (a *AuthConfig) IsRequireAuth() bool

IsRequireAuth returns whether requireAuth is set to true. Defaults to false when the section, the field, or the auth block is nil.

type BranchProtectionControlConfig 

type BranchProtectionControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// NamePatterns is a list of branch name patterns that must be protected (supports wildcards)
	NamePatterns []string `yaml:"namePatterns,omitempty"`

	// DefaultMustBeProtected requires the default branch to be protected
	DefaultMustBeProtected *bool `yaml:"defaultMustBeProtected,omitempty"`

	// AllowForcePush when false, force push must be disabled on protected branches
	AllowForcePush *bool `yaml:"allowForcePush,omitempty"`

	// CodeOwnerApprovalRequired when true, code owner approval is required
	CodeOwnerApprovalRequired *bool `yaml:"codeOwnerApprovalRequired,omitempty"`

	// MinMergeAccessLevel minimum access level required to merge (0=No one, 30=Developer, 40=Maintainer)
	MinMergeAccessLevel *int `yaml:"minMergeAccessLevel,omitempty"`

	// MinPushAccessLevel minimum access level required to push (0=No one, 30=Developer, 40=Maintainer)
	MinPushAccessLevel *int `yaml:"minPushAccessLevel,omitempty"`
}

BranchProtectionControlConfig configuration for the branch protection control

func (*BranchProtectionControlConfig) IsEnabled 

func (c *BranchProtectionControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type Configuration 

type Configuration struct {
	// GitLab connection settings
	GitlabURL   string // URL of the GitLab instance (e.g., https://gitlab.com)
	GitlabToken string // GitLab API token

	// GitHub connection settings
	// GithubAPIHost is the GitHub API host. Empty means default
	// (api.github.com). Set to a GitHub Enterprise Server host
	// (e.g. "ghes.example.com" or "ghes.example.com/api/v3") to
	// target a self-hosted instance. Auth is provided via the same
	// resolution chain as default github.com (GH_TOKEN /
	// GH_ENTERPRISE_TOKEN / GITHUB_TOKEN / gh auth).
	GithubAPIHost string

	// Project settings
	ProjectPath string // Full path of the project (e.g., group/project)
	ProjectID   int    // Project ID on GitLab
	Branch      string // Branch to analyze (from --branch flag, defaults to project's default branch)

	// HTTP client settings
	HTTPClientTimeout time.Duration // Timeout for HTTP clients (REST and GraphQL)

	// GitLab API retry configuration
	GitlabRetryMaxRetries     int           // Maximum number of retries for GitLab API requests
	GitlabRetryInitialBackoff time.Duration // Initial backoff time for GitLab API retries
	GitlabRetryMaxBackoff     time.Duration // Maximum backoff time for GitLab API retries
	GitlabRetryBackoffFactor  float64       // Backoff multiplication factor for exponential backoff

	// CI configuration path override (from --ci-config-path flag)
	CIConfigPathOverride string // When set, overrides the project's CI config file path (e.g., "my-custom-ci.yml")

	// Local CI configuration (from local filesystem)
	LocalCIConfigContent []byte // Content of local .gitlab-ci.yml (nil if using remote)
	UsingLocalCIConfig   bool   // True when using local CI config file
	GitRepoRoot          string // Root of the git repository (empty if not in a git repo)
	IsLocalProject       bool   // True when the local git repo matches the project being analyzed

	// Logging
	LogLevel logrus.Level

	// Version info
	Version string

	// Plumber Configuration (from .plumber.yaml file)
	PlumberConfig *PlumberConfig

	// Values must match .plumber.yaml control keys
	// ControlsFilter runs only the listed controls when set;
	ControlsFilter []string
	// SkipControlsFilter skips the listed controls when set;
	SkipControlsFilter []string

	// ProgressFunc is an optional callback invoked during analysis to report progress.
	// step: current step number (1-based), total: total number of steps, message: description.
	ProgressFunc func(step int, total int, message string)
}

Configuration represents the simplified CLI configuration options

func NewDefaultConfiguration 

func NewDefaultConfiguration() *Configuration

NewDefaultConfiguration creates a Configuration with sensible defaults

type ControlMeta added in v0.3.0 

type ControlMeta struct {
	// Providers lists the providers this control is applicable to.
	// "gitlab", "github", or both. Used by ValidateKnownKeys to warn
	// when a control is placed under the wrong provider section.
	Providers []string
}

ControlMeta describes a control's static properties: which providers it applies to and whether it is currently considered production- ready (i.e. NOT benched). Toggle semantics for individual users live in .plumber.yaml — this registry only describes the universe of controls the engine knows about.

func ControlMetaFor added in v0.3.0 

func ControlMetaFor(controlName string) ControlMeta

ControlMetaFor returns the registered metadata for a control name, or the zero value (empty Providers slice) if the name is unknown.

type ControlsConfig 

type ControlsConfig struct {
	// ContainerImageMustNotUseForbiddenTags control configuration
	ContainerImageMustNotUseForbiddenTags *ImageForbiddenTagsControlConfig `yaml:"containerImageMustNotUseForbiddenTags,omitempty"`

	// ContainerImageMustComeFromAuthorizedSources control configuration
	ContainerImageMustComeFromAuthorizedSources *ImageAuthorizedSourcesControlConfig `yaml:"containerImageMustComeFromAuthorizedSources,omitempty"`

	// BranchMustBeProtected control configuration
	BranchMustBeProtected *BranchProtectionControlConfig `yaml:"branchMustBeProtected,omitempty"`

	// PipelineMustNotIncludeHardcodedJobs control configuration
	PipelineMustNotIncludeHardcodedJobs *HardcodedJobsControlConfig `yaml:"pipelineMustNotIncludeHardcodedJobs,omitempty"`

	// IncludesMustBeUpToDate control configuration
	IncludesMustBeUpToDate *IncludesUpToDateControlConfig `yaml:"includesMustBeUpToDate,omitempty"`

	// IncludesMustNotUseForbiddenVersions control configuration
	IncludesMustNotUseForbiddenVersions *IncludesForbiddenVersionsControlConfig `yaml:"includesMustNotUseForbiddenVersions,omitempty"`

	// PipelineMustIncludeComponent control configuration
	PipelineMustIncludeComponent *RequiredComponentsControlConfig `yaml:"pipelineMustIncludeComponent,omitempty"`

	// PipelineMustIncludeTemplate control configuration
	PipelineMustIncludeTemplate *RequiredTemplatesControlConfig `yaml:"pipelineMustIncludeTemplate,omitempty"`

	// PipelineMustNotEnableDebugTrace control configuration
	PipelineMustNotEnableDebugTrace *DebugTraceControlConfig `yaml:"pipelineMustNotEnableDebugTrace,omitempty"`

	// PipelineMustNotUseUnsafeVariableExpansion control configuration
	PipelineMustNotUseUnsafeVariableExpansion *VariableInjectionControlConfig `yaml:"pipelineMustNotUseUnsafeVariableExpansion,omitempty"`

	// SecurityJobsMustNotBeWeakened control configuration
	SecurityJobsMustNotBeWeakened *SecurityJobsWeakenedControlConfig `yaml:"securityJobsMustNotBeWeakened,omitempty"`

	// PipelineMustNotExecuteUnverifiedScripts control configuration
	PipelineMustNotExecuteUnverifiedScripts *UnverifiedScriptsControlConfig `yaml:"pipelineMustNotExecuteUnverifiedScripts,omitempty"`

	// PipelineMustNotOverrideJobVariables control configuration
	PipelineMustNotOverrideJobVariables *JobVariablesOverrideControlConfig `yaml:"pipelineMustNotOverrideJobVariables,omitempty"`

	// PipelineMustNotUseDockerInDocker control configuration
	PipelineMustNotUseDockerInDocker *DockerInDockerControlConfig `yaml:"pipelineMustNotUseDockerInDocker,omitempty"`

	// ActionsMustBePinnedByCommitSha control configuration (GitHub Actions only)
	ActionsMustBePinnedByCommitSha *ActionsPinnedByShaControlConfig `yaml:"actionsMustBePinnedByCommitSha,omitempty"`

	// WorkflowMustNotInjectUserInputInScripts control configuration (GitHub Actions only).
	// Config-free; toggle via `enabled`.
	WorkflowMustNotInjectUserInputInScripts *EnabledOnlyControlConfig `yaml:"workflowMustNotInjectUserInputInScripts,omitempty"`

	// WorkflowMustNotUseDangerousTriggers control configuration (GitHub Actions only).
	// Config-free; toggle via `enabled`.
	WorkflowMustNotUseDangerousTriggers *EnabledOnlyControlConfig `yaml:"workflowMustNotUseDangerousTriggers,omitempty"`

	// WorkflowsMustDeclarePermissions control configuration (GitHub Actions only).
	// Config-free; toggle via `enabled`.
	WorkflowsMustDeclarePermissions *EnabledOnlyControlConfig `yaml:"workflowsMustDeclarePermissions,omitempty"`

	// ReusableWorkflowsMustNotInheritSecrets control configuration (GitHub Actions only).
	// Config-free; toggle via `enabled`.
	ReusableWorkflowsMustNotInheritSecrets *EnabledOnlyControlConfig `yaml:"reusableWorkflowsMustNotInheritSecrets,omitempty"`

	// WorkflowMustNotGrantPermissionsWriteAll control configuration (GitHub
	// Actions only). Flags workflows or jobs whose effective `permissions:`
	// block is the literal `write-all` shortcut, which grants every scope
	// (contents, packages, deployments, …) write access on GITHUB_TOKEN.
	// Stricter scope-level audits (per-scope write grants) are out of scope
	// here; they get their own rule later. Config-free; toggle via `enabled`.
	WorkflowMustNotGrantPermissionsWriteAll *EnabledOnlyControlConfig `yaml:"workflowMustNotGrantPermissionsWriteAll,omitempty"`

	// ActionsMustNotBeArchived control configuration (GitHub Actions only).
	// Flags `uses: owner/repo@ref` references whose upstream repository is
	// archived on GitHub. Driven by per-action API metadata enriched at
	// collect time. Config-free; toggle via `enabled`.
	ActionsMustNotBeArchived *EnabledOnlyControlConfig `yaml:"actionsMustNotBeArchived,omitempty"`

	// ActionsMustNotCarryKnownCVEs control configuration (GitHub Actions
	// only). Flags `uses: owner/repo@ref` references whose upstream
	// repository carries at least one published advisory in GitHub's
	// Advisory Database under the `actions` ecosystem. Driven by per-
	// action API metadata enriched at collect time. Config-free; toggle
	// via `enabled`.
	ActionsMustNotCarryKnownCVEs *EnabledOnlyControlConfig `yaml:"actionsMustNotCarryKnownCVEs,omitempty"`

	// WorkflowMustIncludeRequiredActions control configuration (GitHub
	// Actions only). The GitHub counterpart of
	// PipelineMustIncludeComponent / PipelineMustIncludeTemplate on
	// the GitLab side: assert that workflows reference a configured
	// set of required actions or reusable workflows. Matching is by
	// `owner/repo[/path]` prefix and ref-agnostic, so
	// `org/sast-scan` matches `uses: org/sast-scan@v2`,
	// `uses: org/sast-scan@abc123`, and `uses: org/sast-scan/sub@v1`.
	WorkflowMustIncludeRequiredActions *RequiredActionsControlConfig `yaml:"workflowMustIncludeRequiredActions,omitempty"`
}

ControlsConfig holds configuration for all controls

type DebugTraceControlConfig added in v0.1.51 

type DebugTraceControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// ForbiddenVariables is a list of CI/CD variable names that must not be set to "true"
	// Defaults: CI_DEBUG_TRACE, CI_DEBUG_SERVICES
	ForbiddenVariables []string `yaml:"forbiddenVariables,omitempty"`
}

DebugTraceControlConfig configuration for the debug trace detection control

func (*DebugTraceControlConfig) IsEnabled added in v0.1.51 

func (c *DebugTraceControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type DockerInDockerControlConfig added in v0.1.77 

type DockerInDockerControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// DetectInsecureDaemon when true, also flags insecure daemon configuration
	// (DOCKER_TLS_CERTDIR="" or DOCKER_HOST pointing to non-TLS port 2375)
	// in jobs that use a DinD service.
	DetectInsecureDaemon *bool `yaml:"detectInsecureDaemon,omitempty"`
}

DockerInDockerControlConfig configuration for the Docker-in-Docker detection control

func (*DockerInDockerControlConfig) IsDetectInsecureDaemonEnabled added in v0.1.77 

func (c *DockerInDockerControlConfig) IsDetectInsecureDaemonEnabled() bool

IsDetectInsecureDaemonEnabled returns whether insecure daemon detection is enabled. Defaults to true when the field is nil.

func (*DockerInDockerControlConfig) IsEnabled added in v0.1.77 

func (c *DockerInDockerControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type EnabledOnlyControlConfig added in v0.3.0 

type EnabledOnlyControlConfig struct {
	Enabled *bool `yaml:"enabled,omitempty"`
}

EnabledOnlyControlConfig is the shape used for controls that have no configurable behaviour beyond on/off. The Rego rule for these controls reads no `input.config.<name>` keys; toggling enabled to false simply drops their findings via FilterFindingsByEnabledControls.

func (*EnabledOnlyControlConfig) IsEnabled added in v0.3.0 

func (c *EnabledOnlyControlConfig) IsEnabled() bool

IsEnabled reports whether the control is enabled. Returns false when the wrapper or the field is nil — same convention as every other IsEnabled() in this package.

type HardcodedJobsControlConfig added in v0.1.31 

type HardcodedJobsControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`
}

HardcodedJobsControlConfig configuration for the hardcoded jobs control

func (*HardcodedJobsControlConfig) IsEnabled added in v0.1.31 

func (c *HardcodedJobsControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type ImageAuthorizedSourcesControlConfig 

type ImageAuthorizedSourcesControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// TrustedUrls is a list of trusted registry URLs/patterns (supports wildcards)
	TrustedUrls []string `yaml:"trustedUrls,omitempty"`

	// TrustDockerHubOfficialImages trusts official Docker Hub images (e.g., nginx, alpine)
	TrustDockerHubOfficialImages *bool `yaml:"trustDockerHubOfficialImages,omitempty"`
}

ImageAuthorizedSourcesControlConfig configuration for the authorized image sources control

func (*ImageAuthorizedSourcesControlConfig) IsEnabled 

func (c *ImageAuthorizedSourcesControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type ImageForbiddenTagsControlConfig 

type ImageForbiddenTagsControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// Tags is a list of forbidden tags (e.g., latest, dev)
	Tags []string `yaml:"tags,omitempty"`

	// ContainerImagesMustBePinnedByDigest when true, ALL images must use immutable digest references.
	// Takes precedence over the forbidden tags list — any image not pinned by digest is flagged.
	ContainerImagesMustBePinnedByDigest *bool `yaml:"containerImagesMustBePinnedByDigest,omitempty"`
}

ImageForbiddenTagsControlConfig configuration for the forbidden image tags control

func (*ImageForbiddenTagsControlConfig) IsEnabled 

func (c *ImageForbiddenTagsControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

func (*ImageForbiddenTagsControlConfig) IsPinnedByDigestRequired added in v0.1.40 

func (c *ImageForbiddenTagsControlConfig) IsPinnedByDigestRequired() bool

IsPinnedByDigestRequired returns whether all images must be pinned by digest

type IncludesForbiddenVersionsControlConfig added in v0.1.31 

type IncludesForbiddenVersionsControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// ForbiddenVersions is a list of version patterns considered forbidden (e.g., latest, main, HEAD)
	ForbiddenVersions []string `yaml:"forbiddenVersions,omitempty"`

	// DefaultBranchIsForbiddenVersion when true, adds the project's default branch to forbidden versions
	DefaultBranchIsForbiddenVersion *bool `yaml:"defaultBranchIsForbiddenVersion,omitempty"`
}

IncludesForbiddenVersionsControlConfig configuration for the forbidden versions control

func (*IncludesForbiddenVersionsControlConfig) IsEnabled added in v0.1.31 

func (c *IncludesForbiddenVersionsControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type IncludesUpToDateControlConfig added in v0.1.31 

type IncludesUpToDateControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`
}

IncludesUpToDateControlConfig configuration for the includes up-to-date control

func (*IncludesUpToDateControlConfig) IsEnabled added in v0.1.31 

func (c *IncludesUpToDateControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type JobVariablesOverrideControlConfig added in v0.1.76 

type JobVariablesOverrideControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// Variables is a list of CI/CD variable names that must not be defined
	// in the pipeline configuration file. They should only be set via
	// GitLab CI/CD Settings > Variables.
	Variables []string `yaml:"variables,omitempty"`
}

JobVariablesOverrideControlConfig configuration for the job variable override control

func (*JobVariablesOverrideControlConfig) IsEnabled added in v0.1.76 

func (c *JobVariablesOverrideControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type PlumberConfig 

type PlumberConfig struct {
	// Version of the config file format.
	// "2.0" = current per-provider schema. "1.0" = legacy flat schema.
	// Missing version is tolerated and treated as legacy.
	Version string `yaml:"version,omitempty"`

	// GitLab provider section (v2 schema). Holds GitLab-specific auth,
	// the enabledControls allowlist, and the per-control configuration map.
	GitLab *ProviderConfig `yaml:"gitlab,omitempty"`

	// GitHub provider section (v2 schema). Same shape as GitLab.
	GitHub *ProviderConfig `yaml:"github,omitempty"`

	// Controls configuration (legacy v1 schema, top-level).
	// After a v2 load this is the zero value; after a v1 load convertV1ToV2
	// moves these into GitLab.Controls and clears this field.
	Controls ControlsConfig `yaml:"controls,omitempty"`
}

PlumberConfig represents the .plumber.yaml configuration file structure.

Schema versions:

  • "2.0" — current per-provider schema (gitlab.controls, github.controls).
  • "1.0" — legacy flat schema (top-level controls). Auto-converted in memory at load time with a deprecation warning. Run `plumber config migrate` to upgrade the file on disk.

The legacy v1 fields (Controls) remain on the struct so the loader can detect a v1 file, parse it, and convert it via convertV1ToV2. After a v2 load — or after conversion — Controls is the zero value and downstream code reads from GitLab.Controls / GitHub.Controls.

func LoadPlumberConfig 

func LoadPlumberConfig(configPath string) (*PlumberConfig, string, []string, error)

LoadPlumberConfig loads configuration from a file path. It reads the file once, validates for unknown keys, parses the YAML into the config struct, detects whether the file uses the legacy v1 schema (top-level `controls:`/`engine:`) or the current v2 schema (per-provider `gitlab.controls:` / `github.controls:`), and converts v1 in-memory to v2. Returns the parsed config, the resolved path, any warnings (unknown-key + deprecation), and an error if loading or validation failed.

func (*PlumberConfig) ControlsFor added in v0.3.0 

func (c *PlumberConfig) ControlsFor(provider string) *ControlsConfig

ControlsFor returns a non-nil pointer to the named provider's ControlsConfig. If the provider is absent, returns a pointer to a zero-value ControlsConfig so callers can dereference fields without nil-checking. The returned pointer is read-only — mutations are discarded if the provider was absent.

func (*PlumberConfig) GetBranchMustBeProtectedConfig 

func (c *PlumberConfig) GetBranchMustBeProtectedConfig() *BranchProtectionControlConfig

GetBranchMustBeProtectedConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetContainerImageMustComeFromAuthorizedSourcesConfig 

func (c *PlumberConfig) GetContainerImageMustComeFromAuthorizedSourcesConfig() *ImageAuthorizedSourcesControlConfig

GetContainerImageMustComeFromAuthorizedSourcesConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetContainerImageMustNotUseForbiddenTagsConfig 

func (c *PlumberConfig) GetContainerImageMustNotUseForbiddenTagsConfig() *ImageForbiddenTagsControlConfig

GetContainerImageMustNotUseForbiddenTagsConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetIncludesMustBeUpToDateConfig added in v0.1.31 

func (c *PlumberConfig) GetIncludesMustBeUpToDateConfig() *IncludesUpToDateControlConfig

GetIncludesMustBeUpToDateConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetIncludesMustNotUseForbiddenVersionsConfig added in v0.1.31 

func (c *PlumberConfig) GetIncludesMustNotUseForbiddenVersionsConfig() *IncludesForbiddenVersionsControlConfig

GetIncludesMustNotUseForbiddenVersionsConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustIncludeComponentConfig added in v0.1.31 

func (c *PlumberConfig) GetPipelineMustIncludeComponentConfig() *RequiredComponentsControlConfig

GetPipelineMustIncludeComponentConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustIncludeTemplateConfig added in v0.1.31 

func (c *PlumberConfig) GetPipelineMustIncludeTemplateConfig() *RequiredTemplatesControlConfig

GetPipelineMustIncludeTemplateConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustNotEnableDebugTraceConfig added in v0.1.51 

func (c *PlumberConfig) GetPipelineMustNotEnableDebugTraceConfig() *DebugTraceControlConfig

GetPipelineMustNotEnableDebugTraceConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustNotExecuteUnverifiedScriptsConfig added in v0.1.69 

func (c *PlumberConfig) GetPipelineMustNotExecuteUnverifiedScriptsConfig() *UnverifiedScriptsControlConfig

GetPipelineMustNotExecuteUnverifiedScriptsConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustNotIncludeHardcodedJobsConfig added in v0.1.31 

func (c *PlumberConfig) GetPipelineMustNotIncludeHardcodedJobsConfig() *HardcodedJobsControlConfig

GetPipelineMustNotIncludeHardcodedJobsConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustNotOverrideJobVariablesConfig added in v0.1.76 

func (c *PlumberConfig) GetPipelineMustNotOverrideJobVariablesConfig() *JobVariablesOverrideControlConfig

GetPipelineMustNotOverrideJobVariablesConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustNotUseDockerInDockerConfig added in v0.1.77 

func (c *PlumberConfig) GetPipelineMustNotUseDockerInDockerConfig() *DockerInDockerControlConfig

GetPipelineMustNotUseDockerInDockerConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetPipelineMustNotUseUnsafeVariableExpansionConfig added in v0.1.52 

func (c *PlumberConfig) GetPipelineMustNotUseUnsafeVariableExpansionConfig() *VariableInjectionControlConfig

GetPipelineMustNotUseUnsafeVariableExpansionConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) GetSecurityJobsMustNotBeWeakenedConfig added in v0.1.64 

func (c *PlumberConfig) GetSecurityJobsMustNotBeWeakenedConfig() *SecurityJobsWeakenedControlConfig

GetSecurityJobsMustNotBeWeakenedConfig returns the control configuration Returns nil if not configured

func (*PlumberConfig) ProviderConfig added in v0.3.0 

func (c *PlumberConfig) ProviderConfig(name string) *ProviderConfig

ProviderConfig returns the named provider's config, or nil if absent. Accepted names: "gitlab", "github" (case-sensitive). Any other name returns nil. Safe to call on a nil receiver.

func (*PlumberConfig) Validate added in v0.1.82 

func (c *PlumberConfig) Validate() error

Validate checks structural consistency (required component/template expressions, etc.).

type ProviderConfig added in v0.3.0 

type ProviderConfig struct {
	// Auth holds provider-specific authentication knobs. Optional.
	// Today only GitHub uses this (RequireAuth). Reserved for future
	// per-provider auth options on GitLab if needed.
	Auth *AuthConfig `yaml:"auth,omitempty"`

	// Controls holds per-control configuration. Same struct types as
	// the legacy top-level ControlsConfig — only the YAML location and
	// the values differ between providers.
	Controls ControlsConfig `yaml:"controls,omitempty"`
}

ProviderConfig is the per-provider configuration block introduced in schema v2. One instance per provider section in .plumber.yaml.

Toggle semantics mirror the GitLab side: a control absent from `controls:` is treated as enabled at the filter level; a control present with `enabled: false` is dropped. The dev-side `bench` set in control/registry.go suppresses non-production controls regardless of YAML state — see that file for how to promote a benched control out of bench.

type RequiredActionsControlConfig added in v0.3.0 

type RequiredActionsControlConfig struct {
	Enabled        *bool      `yaml:"enabled,omitempty"`
	Required       string     `yaml:"required,omitempty"`
	RequiredGroups [][]string `yaml:"requiredGroups,omitempty"`
}

RequiredActionsControlConfig configures the GitHub workflowMustIncludeRequiredActions control. Mirrors RequiredComponentsControlConfig's DNF (Disjunctive Normal Form) shape so users running both providers have one mental model:

  • Required is a boolean expression ("a AND b OR c"), parsed via ParseRequiredExpression into the same OR-of-ANDs groups.
  • RequiredGroups is the same DNF written directly.
  • The two fields are mutually exclusive at validate-time.

Each required entry is an owner/repo prefix (or owner/repo/path for sub-actions and reusable-workflow paths). Matching is ref-agnostic so users can bump pinned SHAs without rewriting the policy.

func (*RequiredActionsControlConfig) GetResolvedRequiredGroups added in v0.3.0 

func (c *RequiredActionsControlConfig) GetResolvedRequiredGroups() ([][]string, error)

GetResolvedRequiredGroups returns the effective required groups by resolving either the 'required' expression or the 'requiredGroups' field. Errors when both are set or when the expression is invalid.

func (*RequiredActionsControlConfig) IsEnabled added in v0.3.0 

func (c *RequiredActionsControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled. Returns false when the config block is absent or when `enabled:` is not set.

type RequiredComponentsControlConfig added in v0.1.31 

type RequiredComponentsControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// Required is a human-readable boolean expression defining required components.
	// Supports AND, OR operators and parentheses for grouping.
	// AND has higher precedence than OR.
	//
	// Examples:
	//   "components/sast/sast AND components/secret-detection/secret-detection"
	//   "(components/sast/sast AND components/secret-detection/secret-detection) OR your-org/full-security/full-security"
	Required string `yaml:"required,omitempty"`

	// RequiredGroups uses DNF (Disjunctive Normal Form) format:
	// Outer array = OR (at least one group must be satisfied)
	// Inner array = AND (all components in group must be present)
	// Example: [["comp-a", "comp-b"], ["comp-c"]] means:
	//   "must have (comp-a AND comp-b) OR (comp-c)"
	//
	// Cannot be used together with 'required'.
	RequiredGroups [][]string `yaml:"requiredGroups,omitempty"`
}

RequiredComponentsControlConfig configuration for the required components control

func (*RequiredComponentsControlConfig) GetResolvedRequiredGroups added in v0.1.34 

func (c *RequiredComponentsControlConfig) GetResolvedRequiredGroups() ([][]string, error)

GetResolvedRequiredGroups returns the effective required groups by resolving either the 'required' expression or the 'requiredGroups' field. Returns an error if both are set or if the expression is invalid.

func (*RequiredComponentsControlConfig) IsEnabled added in v0.1.31 

func (c *RequiredComponentsControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type RequiredTemplatesControlConfig added in v0.1.31 

type RequiredTemplatesControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// Required is a human-readable boolean expression defining required templates.
	// Supports AND, OR operators and parentheses for grouping.
	// AND has higher precedence than OR.
	//
	// Examples:
	//   "templates/go/go AND templates/trivy/trivy"
	//   "(templates/go/go AND templates/trivy/trivy) OR templates/full-go-pipeline"
	Required string `yaml:"required,omitempty"`

	// RequiredGroups uses DNF (Disjunctive Normal Form) format:
	// Outer array = OR (at least one group must be satisfied)
	// Inner array = AND (all templates in group must be present)
	// Example: [["go", "helm"], ["go_helm_unified"]] means:
	//   "must have (go AND helm) OR (go_helm_unified)"
	//
	// Cannot be used together with 'required'.
	RequiredGroups [][]string `yaml:"requiredGroups,omitempty"`
}

RequiredTemplatesControlConfig configuration for the required templates control

func (*RequiredTemplatesControlConfig) GetResolvedRequiredGroups added in v0.1.34 

func (c *RequiredTemplatesControlConfig) GetResolvedRequiredGroups() ([][]string, error)

GetResolvedRequiredGroups returns the effective required groups by resolving either the 'required' expression or the 'requiredGroups' field. Returns an error if both are set or if the expression is invalid.

func (*RequiredTemplatesControlConfig) IsEnabled added in v0.1.31 

func (c *RequiredTemplatesControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type SecurityJobsSubControlToggle added in v0.1.64 

type SecurityJobsSubControlToggle struct {
	Enabled *bool `yaml:"enabled,omitempty"`
}

SecurityJobsSubControlToggle is a simple enabled/disabled toggle for a sub-control

func (*SecurityJobsSubControlToggle) IsEnabled added in v0.1.64 

func (t *SecurityJobsSubControlToggle) IsEnabled(defaultVal bool) bool

IsEnabled returns whether the sub-control toggle is enabled. Returns the provided default if the toggle or its Enabled field is nil.

type SecurityJobsWeakenedControlConfig added in v0.1.64 

type SecurityJobsWeakenedControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// SecurityJobPatterns is a list of job name patterns considered "security jobs" (supports wildcards)
	SecurityJobPatterns []string `yaml:"securityJobPatterns,omitempty"`

	// Sub-control toggles (sit directly under the control, no wrapper)
	AllowFailureMustBeFalse *SecurityJobsSubControlToggle `yaml:"allowFailureMustBeFalse,omitempty"`
	RulesMustNotBeRedefined *SecurityJobsSubControlToggle `yaml:"rulesMustNotBeRedefined,omitempty"`
	WhenMustNotBeManual     *SecurityJobsSubControlToggle `yaml:"whenMustNotBeManual,omitempty"`
}

SecurityJobsWeakenedControlConfig configuration for the security jobs weakening control

func (*SecurityJobsWeakenedControlConfig) IsEnabled added in v0.1.64 

func (c *SecurityJobsWeakenedControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type UnverifiedScriptsControlConfig added in v0.1.69 

type UnverifiedScriptsControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// TrustedUrls is a list of URL patterns that should not trigger findings.
	// Supports wildcards (e.g., "https://internal-artifacts.example.com/*").
	TrustedUrls []string `yaml:"trustedUrls,omitempty"`
}

UnverifiedScriptsControlConfig configuration for the unverified script execution control

func (*UnverifiedScriptsControlConfig) IsEnabled added in v0.1.69 

func (c *UnverifiedScriptsControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

type VariableInjectionControlConfig added in v0.1.52 

type VariableInjectionControlConfig struct {
	// Enabled controls whether this check runs
	Enabled *bool `yaml:"enabled,omitempty"`

	// DangerousVariables is a list of CI/CD variable names whose values come from user input
	// and should not appear in script blocks where shell injection is possible
	DangerousVariables []string `yaml:"dangerousVariables,omitempty"`

	// AllowedPatterns is a list of regex patterns. Script lines matching any of these
	// patterns will not be flagged even if they contain a dangerous variable.
	AllowedPatterns []string `yaml:"allowedPatterns,omitempty"`
}

VariableInjectionControlConfig configuration for the unsafe variable expansion control

func (*VariableInjectionControlConfig) IsEnabled added in v0.1.52 

func (c *VariableInjectionControlConfig) IsEnabled() bool

IsEnabled returns whether the control is enabled Returns false if not properly configured

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.