Skip to main content

CLI

Controls configuration

The field-by-field reference for the gitlab.controls: and github.controls: sections of .plumber.yaml. Use the index to jump to a control. For the three ways to write the file see Configuration; for what each issue means and how to fix it, Issues.

Reading the tables

Default is the value in the plumber:default baseline: what runs with no .plumber.yaml, what an overlay inherits, and what plumber config generate writes (Plumber v0.5.10). Where the CLI behaves differently when a key is simply omitted from a full configuration, that fallback is given as unset. Long baseline lists are shown in the YAML block under each table rather than in the table itself. Every YAML block is nested the way the file is, so it pastes into .plumber.yaml as it is. The CTRL-nnn on each control is the id the Platform’s Policies page shows.

How a control block works

Where a block lives

Every control is a block under gitlab.controls.<name> or github.controls.<name> in a schema version: "2.0" file. The block name is the name you pass to --controls and --skip-controls, and the controlName of its findings in the JSON report.

Turning a control on or off

Every block accepts enabled: true | false. What a missing block means depends on the mode:

ModeMissing block
Overlay (extends: plumber:default)Inherits the baseline block
Full configuration (no extends)The control does not run

A control that is off or absent is reported as skipped, never as passed.

Overlays: lists replace, maps merge

In an overlay, nested maps merge key by key, but a list you write replaces the baseline list entirely. Writing tags: [nightly] under containerImageMustNotUseForbiddenTags drops latest, dev and the other baseline tags, so repeat the entries you want to keep.

The two curated allowlists are the exception. containerImageMustComeFromAuthorizedSources (trustedUrls) and githubActionMustComeFromAuthorizedSources (trustedGithubActions) carry an includePlumberDefaults switch: with the default true, your entries are added to Plumber’s curated list; with false, only your entries are trusted. The switch only acts in overlay mode. plumber config resolve prints the final list.

Fields you leave unset

Fields that describe the setting a project must have (allowForcePush, codeOwnerApprovalRequired, every field of the merge request settings controls) are only compared when you set them. Leaving one out asserts nothing about it, and there is no way to expect the unsafe value.

A few booleans are true when omitted from a full configuration. Every other omitted boolean is false.

FieldControl
detectInsecureDaemonpipelineMustNotUseDockerInDocker
defaultBranchIsForbiddenVersionincludesMustNotUseForbiddenVersions
includePlumberDefaultsboth allowlist controls
trustGithubOfficialActions, trustSameOrgActionsgithubActionMustComeFromAuthorizedSources
trustSameGroupComponents, trustSameInstanceComponents, trustGitlabOfficialComponentscomponentMustComeFromAuthorizedSources
trustSameGroupFunctionsfunctionMustComeFromAuthorizedSources
allowFailureMustBeFalse.enabled, rulesMustNotBeRedefined.enabled, whenMustNotBeManual.enabledsecurityJobsMustNotBeWeakened

Controls that need configuration

Some controls assert nothing until they are given something to check: a list of tags, a set of required components, a minimum number of approvals. They carry a Needs configuration badge below. In an overlay the baseline supplies that configuration; in a full configuration, enabled: true alone makes the control run and pass with nothing to check.

Required expressions

The three “must include” controls (pipelineMustIncludeComponent, pipelineMustIncludeTemplate, workflowMustIncludeRequiredActions) take their requirement in one of two equivalent forms, never both.

  • required: a boolean expression with AND, OR and parentheses. AND binds tighter than OR, so a AND b OR c reads (a AND b) OR c.
  • requiredGroups: the same logic as a list of lists. The outer list is an OR, each inner list is an AND.
# These two are equivalent
required: (templates/go/go AND templates/trivy/trivy) OR templates/full-go-pipeline
requiredGroups:
- ["templates/go/go", "templates/trivy/trivy"]
- ["templates/full-go-pipeline"]

What is fixed

  • Severity. Each issue code carries its own severity (see Issues); in a report, a finding on an attack path shows the path’s tier instead. Configuration decides whether a control runs and what it checks, not how a finding is graded.
  • GitLab plan tiers. Controls and fields that read a setting only a paid plan exposes carry a GitLab Premium or GitLab Ultimate badge. On GitLab Free, enable only what your plan exposes.
  • Validation. Unknown control names and fields produce a warning with a “did you mean” suggestion and are ignored. plumber config validate reports them without a scan; plumber analyze --fail-warnings turns them into a failure.

Controls index

Id is the control’s CTRL-nnn, as the Platform’s Policies page shows it. Baseline is the state in plumber:default. Controls listed under both providers share one block definition.

Both providers

GitLab

GitHub

Info

Eight GitLab controls also accept a block under github.controls: containerImageMustComeFromAuthorizedSources, includesMustBeUpToDate, includesMustNotUseForbiddenVersions, pipelineMustIncludeComponent, pipelineMustIncludeTemplate, pipelineMustNotIncludeHardcodedJobs, pipelineMustNotOverrideJobVariables and pipelineMustNotUseUnsafeVariableExpansion. The block is parsed and validated, but these controls are not active on GitHub yet and produce no finding there.

Controls on both providers

One block definition, under gitlab.controls and under github.controls. Where a default differs between providers, both are given.

containerImageMustNotUseForbiddenTags

CTRL-102On by defaultNeeds configuration

Flags container images referenced by a mutable tag and, when digest pinning is required, any image not pinned by digest. Raises ISSUE-102 (medium) and ISSUE-103 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
tags6 tags, see belowTags considered mutable and therefore forbidden.
containerImagesMustBePinnedByDigesttrue (unset: false)Requires every image to be referenced by an immutable @sha256: digest. Takes precedence over tags: a version tag such as alpine:3.19 is then also flagged.
exemptImagesemptyImages that neither ISSUE-102 nor ISSUE-103 checks while they use one of the tags. See Exempting an image.

Exempting an image

Some images are only published on a mutable tag, for example an internal tool released as :latest only. Rather than turning the whole control off, list them in exemptImages.

An image is exempt from both ISSUE-102 and ISSUE-103 when its registry and name match an entry and its tag is one of the tags. Its digest plays no part. Any other tag of the same image is still checked. With the configuration below:

ImageResult
ghcr.io/my-org/report-tool:latestExempt
ghcr.io/my-org/report-tool:latest@sha256:…Exempt: the digest is ignored
ghcr.io/my-org/report-tool:v1.0.2Not exempt: v1.0.2 is not a forbidden tag, so ISSUE-103 is raised
debian:latest, docker.io/library/debian:latestExempt
public.ecr.aws/docker/library/debian:latestNot exempt: another registry
github:
controls:
containerImageMustNotUseForbiddenTags:
enabled: true
tags: [latest, dev, development, staging, main, master]
containerImagesMustBePinnedByDigest: true
exemptImages:
- ghcr.io/my-org/report-tool
- debian
- "quay.io/my-org/*"
  • No tag in the entries. An entry is a registry and an image name. Which tags are accepted comes from tags.
  • Docker Hub spellings match each other. debian, library/debian, docker.io/debian and docker.io/library/debian name the same image, in the entry and in the pipeline alike. A namespace still counts, so redis does not match redis/redis-stack-server.
  • Globs. * matches any characters, slashes included: quay.io/my-org/* covers every image of that namespace, and */busybox covers busybox on any registry. Quote an entry that starts with *.
  • Variables. $REGISTRY/tool and ${REGISTRY}/tool match each other. The variable is compared by name, not expanded.
  • One block per provider. The list is read from the block of the provider being analyzed. An entry under gitlab.controls has no effect on a GitHub analysis.
  • Exempt images stay visible. The report lists them under Exempted by configuration, and they are not counted as unpinned.

branchMustBeProtected

CTRL-501On by defaultNeeds configurationNeeds an API token

Checks that the branches matching namePatterns (and the default branch) are protected, and that their protection meets the expectations you set. Raises ISSUE-501 (critical) when a branch is not protected and ISSUE-505 (high) when its settings are not compliant. Without a token the control abstains. On GitHub it reads both classic branch protection and rulesets, and evaluates the stricter of the two.

FieldDefaultDescription
enabledtrueTurns the control on.
defaultMustBeProtectedtrueAlso requires the default branch to be protected, whether or not it matches namePatterns.
namePatterns5 patterns, see belowBranch name patterns that must be protected. Wildcards are supported.
allowForcePushfalseExpectation: false requires force push to be disabled.
codeOwnerApprovalRequiredfalseExpectation: true requires code owner approval. GitLab Premium
minMergeAccessLevelGitLab 30, GitHub unsetExpectation: the minimum access level allowed to merge. GitLab only.
minPushAccessLevelGitLab 40, GitHub unsetExpectation: the minimum access level allowed to push. GitLab only.

GitLab access levels: 0 No one (the strictest), 30 Developer, 40 Maintainer.

tagMustBeProtected

CTRL-510On by defaultNeeds an API token

Checks that tags are protected: tag updates and deletions blocked, and tag creation restricted. By default every tag must be covered by one rule on all tags: a GitLab protected tag *, or GitHub tag rulesets targeting All tags with no exclude pattern. List namePatterns to check specific patterns instead. Raises ISSUE-510 (critical, or high when no pipeline or workflow runs on a tag). Nothing is checked until the repository has a tag or a pipeline or workflow runs on tags. Workflow tag triggers never add a pattern to check, they only raise the severity. On GitLab it reads protected tags; on GitHub, active tag rulesets, the repository’s own and the organization’s. Without access the control reports “not evaluated” and raises no finding. On GitLab it is not evaluated in Platform mode yet.

FieldDefaultDescription
enabledtrueTurns the control on.
namePatterns[]Tag name patterns that must be protected, each checked on its own. Wildcards are supported. Empty means all tags: a GitLab protected tag *, or GitHub rulesets on All tags (~ALL), with no exclusion.
requireCreationRestrictedtrueExpectation: true also requires tag creation to be restricted (GitLab: left to Maintainers or narrower; GitHub: Restrict creations). false checks updates and deletions only.

pipelineMustNotEnableDebugTrace

CTRL-203On by defaultNeeds configuration

Flags a pipeline that sets a debug variable to a truthy value, which dumps every variable, masked secrets included, into the job log. Raises ISSUE-203 (critical). There is no built-in list: the control checks only the variables you list.

FieldDefaultDescription
enabledtrueTurns the control on.
forbiddenVariablesper provider, see belowVariable names that must not be set to true (1 and yes also count on GitHub).

securityJobsMustNotBeWeakened

CTRL-410On by defaultNeeds configuration

Flags security scanning jobs that are allowed to fail, whose rules were overridden to skip them, or that were made manual. Raises ISSUE-410 (critical). Only jobs matching securityJobPatterns are checked, and the control counts as skipped when all three sub-checks are off.

FieldDefaultDescription
enabledtrueTurns the control on.
securityJobPatternsper provider, see belowJob name patterns treated as security jobs. Wildcards are supported. On GitHub the pattern is matched against <workflow file>/<job id>, for example codeql/analyze.
allowFailureMustBeFalse.enabledGitLab false, GitHub trueThe job must not carry allow_failure: true (GitLab) or continue-on-error: true (GitHub). Off on GitLab because GitLab’s own security templates ship with allow_failure: true.
rulesMustNotBeRedefined.enabledtrueThe job’s rules: must not be overridden to when: never or when: manual.
whenMustNotBeManual.enabledtrueThe job must not be when: manual (GitLab) or reachable only through a manual dispatch trigger (GitHub).

pipelineMustNotExecuteUnverifiedScripts

CTRL-411On by default

Flags scripts downloaded and executed in one go (curl | bash, wget | sh) from a URL that is not trusted. Raises ISSUE-411 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
trustedUrlsemptyURL patterns that do not trigger a finding. Wildcards are supported; matching is host-precise, so https://example.com/* does not cover a subdomain.

pipelineMustNotUseDockerInDocker

CTRL-412On by default

Flags jobs that run a Docker-in-Docker service and, optionally, an insecure daemon configuration in those jobs. Raises ISSUE-412 (high) and ISSUE-413 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
detectInsecureDaemontrueAlso flags an empty DOCKER_TLS_CERTDIR or a plaintext DOCKER_HOST such as tcp://docker:2375 in a DinD job (ISSUE-413).

externalRefsMustNotCollide

CTRL-402On by defaultNeeds an API token

Flags an include (GitLab) or an action reference (GitHub) whose ref exists both as a tag and as a branch upstream, so what runs is ambiguous. Raises ISSUE-402 (medium). Without a token the control abstains. No field beyond enabled.

GitLab controls

Blocks under gitlab.controls.

containerImageMustComeFromAuthorizedSources

CTRL-101On by default

Flags a job image that does not come from a trusted registry or publisher. Raises ISSUE-101 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
trustDockerHubOfficialImagestrue (unset: false)Trusts Docker Hub official images such as nginx or alpine.
trustedUrlscurated list, about 90 entriesTrusted registry URLs or image patterns, wildcards supported. The baseline covers the project registry ($CI_REGISTRY_IMAGE:*, $CI_REGISTRY/*), registry.gitlab.com/security-products/*, common Docker Hub publishers and selected namespaces on ghcr.io, quay.io, gcr.io and mcr.microsoft.com. Print it with plumber config view.
includePlumberDefaultstrueOverlay mode: true adds your trustedUrls to the curated list, false trusts only your entries.

Prefer namespace patterns such as ghcr.io/myorg/* over host-wide wildcards such as ghcr.io/*, which trust every publisher on that host.

gitlab:
controls:
containerImageMustComeFromAuthorizedSources:
enabled: true
trustDockerHubOfficialImages: true
includePlumberDefaults: true
trustedUrls:
- $CI_REGISTRY_IMAGE:*
- registry.example.com/platform/*

componentMustComeFromAuthorizedSources

CTRL-414On by default

Flags an include: component: whose source is not trusted by any of the rules below. Components run with the job’s full context, secrets and CI_JOB_TOKEN included. Raises ISSUE-414 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
trustSameGroupComponentstrueTrusts components under the scanned project’s root namespace (top-level group) on the same GitLab instance.
trustSameInstanceComponentstrueTrusts any component hosted on the scanned GitLab instance. Always off on gitlab.com, even when set to true, because every gitlab.com user shares that instance.
trustGitlabOfficialComponentstrueTrusts GitLab’s curated namespaces on gitlab.com, gitlab.com/components/* and gitlab.com/gitlab-org/*. A same-named namespace on a self-hosted instance is not covered.
trustedComponentsgitlab.com/getplumber/*Trusted component sources, wildcards and $VAR / ${VAR} notation supported. The baseline trusts Plumber’s own component.

Hosts and namespaces compare case-insensitively, as GitLab resolves them. A source with a . or .. path segment is never trusted. Plumber’s own component (gitlab.com/getplumber/*) is trusted by the baseline, the way its container image is.com/getplumber/*totrustedComponents` if you include it.

componentMustComeFromAuthorizedSources:
enabled: true
trustSameGroupComponents: true
trustSameInstanceComponents: true
trustGitlabOfficialComponents: true
trustedComponents:
- gitlab.com/getplumber/*
- gitlab.com/to-be-continuous/*

functionMustComeFromAuthorizedSources

CTRL-415On by default

Flags a GitLab Function referenced by a run: step (func:, or the deprecated step:) whose source is not trusted. Functions run with the job’s full context, the same exposure as components. Raises ISSUE-415 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
trustSameGroupFunctionstrueTrusts functions under the scanned project’s root namespace, hosted on the instance’s container registry (OCI form, the registry host the GitLab API reports for the project) or its web host (deprecated git form). CI/CD variables such as CI_REGISTRY never move this anchor.
trustedFunctionsemptyTrusted function references, wildcards supported. The runner does not expand $VAR in func:, so list literal hosts and paths. A pattern that references a $CI_* variable is rejected when the pipeline redefines that variable.

The structured forms are checked like their string equivalents: func: {git: {url, rev, dir, file}} as url/-/dir/file@rev, func: {oci: {registry, repository, tag}} as registry/repository:tag. A func: value Plumber cannot read is reported, never skipped. Local paths and GitLab built-in functions (builtin://...) are out of scope. Hosts and namespaces compare case-insensitively, and a reference with a . or .. path segment is never trusted.

The deprecated forms (step:, git references) are counted in the Deprecated stat of the report. Being deprecated does not raise a finding on its own, and does not exempt a reference from the trust check.

functionMustComeFromAuthorizedSources:
enabled: true
trustSameGroupFunctions: true
trustedFunctions:
- registry.example.com/platform-team/*

includesMustBeUpToDate

CTRL-403On by default

Flags an included template or component pinned to a version older than the latest available. Raises ISSUE-403 (low). No field beyond enabled.

includesMustNotUseForbiddenVersions

CTRL-404On by defaultNeeds configuration

Flags an include pinned to a mutable ref. Raises ISSUE-404 (medium).

FieldDefaultDescription
enabledtrueTurns the control on.
forbiddenVersions5 patterns, see belowVersion patterns considered forbidden.
defaultBranchIsForbiddenVersiontrueAlso forbids the included project’s default branch, whatever its name.
gitlab:
controls:
includesMustNotUseForbiddenVersions:
enabled: true
forbiddenVersions: [latest, "~latest", main, master, HEAD]
defaultBranchIsForbiddenVersion: true

pipelineMustNotUseUnsafeVariableExpansion

CTRL-204On by defaultNeeds configuration

Flags a user-controlled variable (merge request title, commit message, branch name) used where the shell re-interprets it: eval, sh -c, bash -c, source <(...), envsubst | sh, xargs sh. Plain uses such as echo $CI_COMMIT_BRANCH are not flagged. Raises ISSUE-204 (medium).

FieldDefaultDescription
enabledtrueTurns the control on.
dangerousVariables10 variables, see belowVariables whose value comes from user input.
allowedPatternsemptyA list of regular expressions; a matching script line is not flagged. Escape $ as \\$ and braces as \\{, \\}.
gitlab:
controls:
pipelineMustNotUseUnsafeVariableExpansion:
enabled: true
dangerousVariables:
- CI_MERGE_REQUEST_TITLE
- CI_MERGE_REQUEST_DESCRIPTION
- CI_COMMIT_MESSAGE
- CI_COMMIT_TITLE
- CI_COMMIT_TAG_MESSAGE
- CI_COMMIT_REF_NAME
- CI_COMMIT_REF_SLUG
- CI_COMMIT_BRANCH
- CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
- CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME
allowedPatterns:
- "helm.*--set.*\\$CI_"
- "docker build.*--build-arg.*\\$CI_"

pipelineMustNotOverrideJobVariables

CTRL-205On by defaultNeeds configuration

Flags a controlled variable defined in the pipeline file, where it can silently disable or redirect a security scanner. Such variables belong in the project’s CI/CD settings. Raises ISSUE-205 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
variables10 variables, see belowVariable names that must not be defined in .gitlab-ci.yml, at the top level or in a job.
gitlab:
controls:
pipelineMustNotOverrideJobVariables:
enabled: true
variables:
- SECURE_ANALYZERS_PREFIX
- SAST_DISABLED
- SAST_EXCLUDED_PATHS
- SAST_EXCLUDED_ANALYZERS
- SECRET_DETECTION_DISABLED
- SECRET_DETECTION_EXCLUDED_PATHS
- CONTAINER_SCANNING_DISABLED
- DAST_DISABLED
- DEPENDENCY_SCANNING_DISABLED
- LICENSE_SCANNING_DISABLED

cicdVariablesMustBeProtected

CTRL-201Off by defaultNeeds an API token

Flags a CI/CD variable in the project settings that is not marked protected. Raises ISSUE-201 (medium). Needs read access to the project variables; a 401 or 403 is reported as not evaluable, never as a pass. No field beyond enabled.

cicdVariablesMustBeMasked

CTRL-202Off by defaultNeeds an API token

Flags a CI/CD variable in the project settings that is not masked. Raises ISSUE-202 (medium). GitLab cannot mask values shorter than 8 characters; those are still flagged. No field beyond enabled.

mergeRequestApprovalRulesMustRequireMinimumApprovals

CTRL-502Off by defaultNeeds configurationGitLab Premium

Flags an approval rule covering all protected branches that requires fewer approvals than the minimum. Raises ISSUE-502 (high).

FieldDefaultDescription
enabledfalseTurns the control on.
minimumRequiredApprovals1The fewest approvals a rule covering all protected branches must require. Unset asserts nothing.
gitlab:
controls:
mergeRequestApprovalRulesMustRequireMinimumApprovals:
enabled: true
minimumRequiredApprovals: 2

mergeRequestApprovalRulesMustCoverAllProtectedBranches

CTRL-504Off by defaultGitLab Premium

Flags a project where no approval rule targets all protected branches. Raises ISSUE-504 (high). On GitLab Free the approvals API returns no rule, so the control would fire on every project. No field beyond enabled.

mergeRequestApprovalSettingsMustBeCompliant

CTRL-503Off by defaultNeeds configurationGitLab Premium

Compares the project’s merge request approval settings with the expectations you set. Raises ISSUE-503 (high). A field you leave out (or set to false) is not checked.

FieldDefaultExpects
enabledfalseTurns the control on.
preventApprovalByAuthorunsetAuthors cannot approve their own merge requests.
preventApprovalsByCommittersunsetUsers who committed to a merge request cannot approve it.
preventEditingApprovalRulesInMRunsetApproval rules cannot be edited in a merge request.
requireReAuthToApproveunsetApproving requires re-authentication (password or SAML).
behaviorWhenCommitIsAddedunsetThe minimum strictness when a commit is added to an open merge request: keep_approvals, remove_approvals_by_code_owners or remove_all_approvals, from least to most strict. A stricter project setting passes.
gitlab:
controls:
mergeRequestApprovalSettingsMustBeCompliant:
enabled: true
preventApprovalByAuthor: true
preventApprovalsByCommitters: true
preventEditingApprovalRulesInMR: true
requireReAuthToApprove: true
behaviorWhenCommitIsAdded: remove_all_approvals

mergeRequestSettingsMustBeCompliant

CTRL-506Off by defaultNeeds configuration

Compares the project’s merge request settings with the expectations you set, for exact equality. Raises ISSUE-506 (medium). A field you leave out is not checked.

FieldDefaultExpects
enabledfalseTurns the control on.
mergeMethodunsetThe merge method: merge, ff or rebase_merge.
squashOptionunsetThe squash setting: never, always, default_on or default_off.
mergePipelinesEnabledunsetThe “merged results pipelines” setting. GitLab Premium
mergeTrainsEnabledunsetThe “merge trains” setting. GitLab Premium
allowMergeOnSkippedPipelineunsetThe “allow merge when the pipeline is skipped” setting.
resolveOutdatedDiffDiscussionsunsetThe “automatically resolve outdated diff discussions” setting.
printingMergeRequestLinkEnabledunsetThe “show the merge request link when pushing” setting.
removeSourceBranchAfterMergeunsetThe “delete source branch after merge” default.
gitlab:
controls:
mergeRequestSettingsMustBeCompliant:
enabled: true
mergeMethod: ff
squashOption: default_on
allowMergeOnSkippedPipeline: false
removeSourceBranchAfterMerge: true

projectMustHaveSecurityPolicySource

CTRL-601Off by defaultGitLab Ultimate

Checks that the project is linked to a security policy project, optionally a specific one. Raises ISSUE-601 (critical).

FieldDefaultDescription
enabledfalseTurns the control on.
expectedProjectIdunsetThe numeric ID the linked policy project must have. Unset only requires that some policy project is linked.
expectedProjectPathunsetThe namespace/project path the linked policy project must have, compared case-insensitively. Ignored when expectedProjectId is set.
gitlab:
controls:
projectMustHaveSecurityPolicySource:
enabled: true
expectedProjectPath: my-group/security-policy-project

pipelineMustNotIncludeHardcodedJobs

CTRL-401Off by default

Flags jobs defined directly in .gitlab-ci.yml instead of coming from an included template or component. Raises ISSUE-401 (medium). Off by default because without a components strategy it flags most jobs. No field beyond enabled.

pipelineMustIncludeComponent

CTRL-408Off by defaultNeeds configuration

Checks that the pipeline includes the required CI/CD components and does not override their jobs. Raises ISSUE-408 (high) when a component is missing and ISSUE-409 (medium) when a required component’s job is overridden.

FieldDefaultDescription
enabledfalseTurns the control on.
requiredunsetThe requirement as a boolean expression of component paths (group/project/component). See Required expressions. Exclusive with requiredGroups.
requiredGroupsemptyThe same requirement as a list of lists (an OR of ANDs). Exclusive with required.
gitlab:
controls:
pipelineMustIncludeComponent:
enabled: true
required: components/sast/sast AND components/secret-detection/secret-detection AND getplumber/plumber/plumber

pipelineMustIncludeTemplate

CTRL-405Off by defaultNeeds configuration

Checks that the pipeline includes the required templates and does not override their jobs. Raises ISSUE-405 (high) and ISSUE-406 (medium).

FieldDefaultDescription
enabledfalseTurns the control on.
requiredunsetThe requirement as a boolean expression of template paths. Exclusive with requiredGroups.
requiredGroupsemptyThe same requirement as a list of lists (an OR of ANDs). Exclusive with required.
gitlab:
controls:
pipelineMustIncludeTemplate:
enabled: true
requiredGroups:
- ["templates/go/go", "templates/trivy/trivy"]
- ["templates/full-go-pipeline"]

GitHub controls

Blocks under github.controls.

actionsMustBePinnedByCommitSha

CTRL-701On by default

Flags a third-party action referenced by a tag or branch instead of a full commit SHA. Raises ISSUE-701 (high).

A tag backed by an immutable GitHub release counts as pinned: such a tag can never be moved or deleted. Only the exact released tag qualifies (@v4.2.1, not the floating @v4). Plumber reads the release through the GitHub API, so the exemption needs a token (gh auth login, GH_TOKEN or PLUMBER_METADATA_TOKEN). Without one, or when the release cannot be read, the reference is reported.

FieldDefaultDescription
enabledtrueTurns the control on.
trustedOwnersactions, githubAction owners exempt from the requirement. List only owners inside your trust boundary.
github:
controls:
actionsMustBePinnedByCommitSha:
enabled: true
trustedOwners: [actions, github, myorg]

githubActionMustComeFromAuthorizedSources

CTRL-713On by default

Flags an action whose owner is not trusted by any of the four rules below. Raises ISSUE-713 (high).

FieldDefaultDescription
enabledtrueTurns the control on.
trustGithubOfficialActionstrueTrusts GitHub’s own actions, actions/* and github/*.
trustSameOrgActionstrueTrusts actions owned by the same organization or user as the scanned repository.
minimumStars20000 (unset: 0, off)Trusts any action whose repository has at least this many stars. Needs API access; an unresolvable star count falls back to the allowlist instead of a finding.
trustedGithubActionscurated list, about 150 entriesTrusted actions as owner/repo or owner/*. Owner matching is literal and case-sensitive. The baseline covers the major cloud vendors, build and release tooling, language ecosystems, security vendors and developer platforms. Print it with plumber config view.
includePlumberDefaultstrueOverlay mode: true adds your trustedGithubActions to the curated list, false trusts only your entries.
github:
controls:
githubActionMustComeFromAuthorizedSources:
enabled: true
trustGithubOfficialActions: true
trustSameOrgActions: true
minimumStars: 20000
includePlumberDefaults: true
trustedGithubActions:
- myorg/*
- partner-org/deploy-action

actionsMustNotBeArchived

CTRL-702On by defaultNeeds an API token

Flags an action hosted in an archived repository, which no longer receives fixes. Raises ISSUE-702 (high). Without API access the control abstains. No field beyond enabled.

actionRefsMustExistUpstream

CTRL-707On by defaultNeeds an API token

Flags a pinned commit SHA that does not belong to the action’s repository. Raises ISSUE-707 (critical). Fires only on a definitive not-found answer from a readable repository. No field beyond enabled.

actionsMustNotCarryKnownCVEs

CTRL-703On by defaultNeeds an API token

Flags an action version that has a published advisory in the GitHub Advisory Database. Raises ISSUE-703 (critical). Without API access the control abstains; PLUMBER_METADATA_TOKEN can carry the version lookup, see the CLI reference. No field beyond enabled.

actionsMustNotExecuteMutableRemoteCode

CTRL-714On by defaultNeeds an API token

Inspects the source of each third-party action and flags one that downloads and runs code from a mutable location. Raises ISSUE-714 (high) for a fetch in the open, ISSUE-715 (critical) for an obfuscated one, and ISSUE-716 (low) when the action source could not be read. No field beyond enabled.

untrustedTriggersMustNotWriteCache

CTRL-705On by default

Flags a job whose triggers include an event GitHub restricts to read-only cache access (pull_request_target, issue_comment, workflow_run, discussion…) and whose cache-mode is write or write-only, set on the job or inherited from its workflow. Code running in such a job can write caches every default-branch run restores. Raises ISSUE-705 (high). push, workflow_dispatch, repository_dispatch, delete, registry_package, page_build, schedule, pull_request and its review events, release and merge_group are safe triggers, and a job without cache-mode is silent.

FieldDefaultDescription
enabledtrueTurns the control on.
exemptWorkflowsemptyA list of globs on the workflow file name, such as triage.yml; every job of a matching workflow is exempt.
exemptJobsemptyA list of globs on <workflow>/<job id>, such as triage/label; a matching job is exempt.

An exemption accepts the risk: the check skips the job, and the output lists every exempted job it would have flagged under Exempted by configuration, so the exemption stays visible.

github:
controls:
untrustedTriggersMustNotWriteCache:
enabled: true
exemptWorkflows: []
exemptJobs: []
# - 'bot/warm-cache'

Info

This control replaces releaseWorkflowsMustNotRestoreUntrustedCache, which flagged release jobs restoring a cache not scoped to the release ref. A configuration that still uses the old key is ignored with a warning: run plumber config migrate to rename it. publishActions, cacheActions, publishScriptPatterns, publishScriptExcludePatterns and allowedJobs are gone; list the jobs you accept under exemptJobs.

reusableWorkflowsMustNotInheritSecrets

CTRL-302On by default

Flags a reusable workflow call with secrets: inherit, which passes every repository secret to the callee. Raises ISSUE-302 (high). No field beyond enabled.

checkoutMustNotPersistCredentials

CTRL-307On by default

Flags an actions/checkout step that does not set persist-credentials: false, leaving the token in the clone’s .git/config. Raises ISSUE-307 (low) when the credential merely persists and ISSUE-310 (high) when a later upload-artifact step packs it into a downloadable artifact. No field beyond enabled.

workflowMustNotExportEntireSecretsContext

CTRL-309On by default

Flags toJSON(secrets) and other expressions that expose the whole secrets context at once. Raises ISSUE-309 (critical). No field beyond enabled.

workflowMustNotInjectUserInputInScripts

CTRL-207On by default

Flags a run: script that inlines a user-controlled expression such as ${{ github.event.pull_request.title }}, a template injection. Raises ISSUE-207 (critical). No field beyond enabled.

workflowMustNotWriteUntrustedContentToGitHubEnv

CTRL-209On by default

Flags a step that writes user-controlled content to $GITHUB_ENV or $GITHUB_PATH. Raises ISSUE-209 (high). No field beyond enabled.

workflowMustNotUseDangerousTriggers

CTRL-802On by default

Flags the pull_request_target and workflow_run triggers, which run with write access on untrusted input. Raises ISSUE-802 (critical). No field beyond enabled.

pullRequestTargetMustNotCheckoutHead

CTRL-804On by default

Flags a pull_request_target workflow that checks out the pull request head, running untrusted code with the repository’s secrets. Raises ISSUE-804 (critical). No field beyond enabled.

workflowsMustDeclarePermissions

CTRL-801On by default

Flags a workflow with no explicit permissions: block, which runs with the repository’s default token permissions. Raises ISSUE-801 (medium). No field beyond enabled.

workflowMustNotGrantPermissionsWriteAll

CTRL-803On by default

Flags the permissions: write-all shortcut at the workflow or job level. Per-scope permissions are not audited. Raises ISSUE-803 (high). No field beyond enabled.

workflowsMustBeValid

CTRL-423On by default

Flags a file under .github/workflows that cannot be parsed as a workflow (an undefined YAML anchor, a duplicate key, a tab-indented block, a syntax error), which GitHub shows as an invalid workflow and never runs. The other workflow files are analyzed and scored as usual; when every file is invalid, the controls that read the workflows show as not evaluated. Only YAML parse failures are reported: a well-formed file GitHub still rejects (a job without runs-on, say) is left to the Actions tab or actionlint. Duplicate keys are compared ignoring case, as GitHub does. Raises ISSUE-423 (low). No field beyond enabled. When the control is off, or absent from a full configuration without extends, the control shows as skipped, but an invalid file is not dropped silently: it degrades the run and the score is withheld.

workflowMustIncludeRequiredActions

CTRL-417Off by defaultNeeds configuration

Checks that the workflows of the repository, taken together, reference the required actions or reusable workflows. Raises ISSUE-417 (high).

FieldDefaultDescription
enabledfalseTurns the control on.
requiredunsetThe requirement as a boolean expression of owner/repo or owner/repo/path entries, matched without regard to the @ref: myorg/sast-scan matches myorg/sast-scan@v2 and myorg/sast-scan/sub@abc123. Exclusive with requiredGroups.
requiredGroupsemptyThe same requirement as a list of lists (an OR of ANDs). Exclusive with required.
github:
controls:
workflowMustIncludeRequiredActions:
enabled: true
required: myorg/sast-scan AND myorg/policy/.github/workflows/scan.yml