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:
| Mode | Missing 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.
| Field | Control |
|---|---|
detectInsecureDaemon | pipelineMustNotUseDockerInDocker |
defaultBranchIsForbiddenVersion | includesMustNotUseForbiddenVersions |
includePlumberDefaults | both allowlist controls |
trustGithubOfficialActions, trustSameOrgActions | githubActionMustComeFromAuthorizedSources |
trustSameGroupComponents, trustSameInstanceComponents, trustGitlabOfficialComponents | componentMustComeFromAuthorizedSources |
trustSameGroupFunctions | functionMustComeFromAuthorizedSources |
allowFailureMustBeFalse.enabled, rulesMustNotBeRedefined.enabled, whenMustNotBeManual.enabled | securityJobsMustNotBeWeakened |
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 withAND,ORand parentheses.ANDbinds tighter thanOR, soa AND b OR creads(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 equivalentrequired: (templates/go/go AND templates/trivy/trivy) OR templates/full-go-pipelinerequiredGroups: - ["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 validatereports them without a scan;plumber analyze --fail-warningsturns 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
| Id | Control | Baseline | Issues |
|---|---|---|---|
CTRL-102 | containerImageMustNotUseForbiddenTags | on | 102, 103 |
CTRL-501 | branchMustBeProtected | on | 501, 505 |
CTRL-510 | tagMustBeProtected | on | 510 |
CTRL-203 | pipelineMustNotEnableDebugTrace | on | 203 |
CTRL-410 | securityJobsMustNotBeWeakened | on | 410 |
CTRL-411 | pipelineMustNotExecuteUnverifiedScripts | on | 411 |
CTRL-412 | pipelineMustNotUseDockerInDocker | on | 412, 413 |
CTRL-402 | externalRefsMustNotCollide | on | 402 |
GitLab
| Id | Control | Baseline | Issues |
|---|---|---|---|
CTRL-101 | containerImageMustComeFromAuthorizedSources | on | 101 |
CTRL-414 | componentMustComeFromAuthorizedSources | on | 414 |
CTRL-415 | functionMustComeFromAuthorizedSources | on | 415 |
CTRL-403 | includesMustBeUpToDate | on | 403 |
CTRL-404 | includesMustNotUseForbiddenVersions | on | 404 |
CTRL-204 | pipelineMustNotUseUnsafeVariableExpansion | on | 204 |
CTRL-205 | pipelineMustNotOverrideJobVariables | on | 205 |
CTRL-201 | cicdVariablesMustBeProtected | off | 201 |
CTRL-202 | cicdVariablesMustBeMasked | off | 202 |
CTRL-502 | mergeRequestApprovalRulesMustRequireMinimumApprovals | off | 502 |
CTRL-504 | mergeRequestApprovalRulesMustCoverAllProtectedBranches | off | 504 |
CTRL-503 | mergeRequestApprovalSettingsMustBeCompliant | off | 503 |
CTRL-506 | mergeRequestSettingsMustBeCompliant | off | 506 |
CTRL-601 | projectMustHaveSecurityPolicySource | off | 601 |
CTRL-401 | pipelineMustNotIncludeHardcodedJobs | off | 401 |
CTRL-408 | pipelineMustIncludeComponent | off | 408, 409 |
CTRL-405 | pipelineMustIncludeTemplate | off | 405, 406 |
GitHub
| Id | Control | Baseline | Issues |
|---|---|---|---|
CTRL-701 | actionsMustBePinnedByCommitSha | on | 701 |
CTRL-713 | githubActionMustComeFromAuthorizedSources | on | 713 |
CTRL-702 | actionsMustNotBeArchived | on | 702 |
CTRL-707 | actionRefsMustExistUpstream | on | 707 |
CTRL-703 | actionsMustNotCarryKnownCVEs | on | 703 |
CTRL-714 | actionsMustNotExecuteMutableRemoteCode | on | 714, 715, 716 |
CTRL-705 | untrustedTriggersMustNotWriteCache | on | 705 |
CTRL-302 | reusableWorkflowsMustNotInheritSecrets | on | 302 |
CTRL-307 | checkoutMustNotPersistCredentials | on | 307, 310 |
CTRL-309 | workflowMustNotExportEntireSecretsContext | on | 309 |
CTRL-207 | workflowMustNotInjectUserInputInScripts | on | 207 |
CTRL-209 | workflowMustNotWriteUntrustedContentToGitHubEnv | on | 209 |
CTRL-802 | workflowMustNotUseDangerousTriggers | on | 802 |
CTRL-804 | pullRequestTargetMustNotCheckoutHead | on | 804 |
CTRL-801 | workflowsMustDeclarePermissions | on | 801 |
CTRL-803 | workflowMustNotGrantPermissionsWriteAll | on | 803 |
CTRL-423 | workflowsMustBeValid | on | 423 |
CTRL-417 | workflowMustIncludeRequiredActions | off | 417 |
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
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).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
tags | 6 tags, see below | Tags considered mutable and therefore forbidden. |
containerImagesMustBePinnedByDigest | true (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. |
exemptImages | empty | Images that neither ISSUE-102 nor ISSUE-103 checks while they use one of the tags. See Exempting an image. |
gitlab: controls: containerImageMustNotUseForbiddenTags: enabled: true tags: [latest, dev, development, staging, main, master] containerImagesMustBePinnedByDigest: truegithub: controls: containerImageMustNotUseForbiddenTags: enabled: true tags: [latest, dev, development, staging, main, master] containerImagesMustBePinnedByDigest: trueExempting 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:
| Image | Result |
|---|---|
ghcr.io/my-org/report-tool:latest | Exempt |
ghcr.io/my-org/report-tool:latest@sha256:… | Exempt: the digest is ignored |
ghcr.io/my-org/report-tool:v1.0.2 | Not exempt: v1.0.2 is not a forbidden tag, so ISSUE-103 is raised |
debian:latest, docker.io/library/debian:latest | Exempt |
public.ecr.aws/docker/library/debian:latest | Not 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/debiananddocker.io/library/debianname the same image, in the entry and in the pipeline alike. A namespace still counts, soredisdoes not matchredis/redis-stack-server. - Globs.
*matches any characters, slashes included:quay.io/my-org/*covers every image of that namespace, and*/busyboxcoversbusyboxon any registry. Quote an entry that starts with*. - Variables.
$REGISTRY/tooland${REGISTRY}/toolmatch 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.controlshas 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
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.
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
defaultMustBeProtected | true | Also requires the default branch to be protected, whether or not it matches namePatterns. |
namePatterns | 5 patterns, see below | Branch name patterns that must be protected. Wildcards are supported. |
allowForcePush | false | Expectation: false requires force push to be disabled. |
codeOwnerApprovalRequired | false | Expectation: true requires code owner approval. GitLab Premium |
minMergeAccessLevel | GitLab 30, GitHub unset | Expectation: the minimum access level allowed to merge. GitLab only. |
minPushAccessLevel | GitLab 40, GitHub unset | Expectation: the minimum access level allowed to push. GitLab only. |
GitLab access levels: 0 No one (the strictest), 30 Developer, 40 Maintainer.
gitlab: controls: branchMustBeProtected: enabled: true defaultMustBeProtected: true namePatterns: [main, master, release/*, production, dev] allowForcePush: false codeOwnerApprovalRequired: false minMergeAccessLevel: 30 minPushAccessLevel: 40github: controls: branchMustBeProtected: enabled: true defaultMustBeProtected: true namePatterns: [main, master, release/*, production, dev] allowForcePush: false codeOwnerApprovalRequired: falsetagMustBeProtected
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.
| Field | Default | Description |
|---|---|---|
enabled | true | Turns 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. |
requireCreationRestricted | true | Expectation: true also requires tag creation to be restricted (GitLab: left to Maintainers or narrower; GitHub: Restrict creations). false checks updates and deletions only. |
gitlab: controls: tagMustBeProtected: enabled: true namePatterns: [] # all tags; or [v*] to check specific patterns requireCreationRestricted: truegithub: controls: tagMustBeProtected: enabled: true namePatterns: [] # all tags; or [v*] to check specific patterns requireCreationRestricted: truepipelineMustNotEnableDebugTrace
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.
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
forbiddenVariables | per provider, see below | Variable names that must not be set to true (1 and yes also count on GitHub). |
gitlab: controls: pipelineMustNotEnableDebugTrace: enabled: true forbiddenVariables: [CI_DEBUG_TRACE, CI_DEBUG_SERVICES]github: controls: pipelineMustNotEnableDebugTrace: enabled: true forbiddenVariables: [ACTIONS_STEP_DEBUG, ACTIONS_RUNNER_DEBUG]securityJobsMustNotBeWeakened
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.
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
securityJobPatterns | per provider, see below | Job 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.enabled | GitLab false, GitHub true | The 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.enabled | true | The job’s rules: must not be overridden to when: never or when: manual. |
whenMustNotBeManual.enabled | true | The job must not be when: manual (GitLab) or reachable only through a manual dispatch trigger (GitHub). |
gitlab: controls: securityJobsMustNotBeWeakened: enabled: true securityJobPatterns: - "*-sast" - "secret_detection" - "container_scanning" - "*_dependency_scanning" - "gemnasium-*" - "dast" - "dast_*" - "license_scanning" allowFailureMustBeFalse: { enabled: false } rulesMustNotBeRedefined: { enabled: true } whenMustNotBeManual: { enabled: true }github: controls: securityJobsMustNotBeWeakened: enabled: true securityJobPatterns: - "*codeql*" - "*dependency-review*" - "*trufflehog*" - "*gitleaks*" - "*osv-scanner*" - "*semgrep*" - "*trivy*" - "*snyk*" - "*-sast" - "*-sast-*" - "*-scan" - "*scan*" - "*-security" - "*-security-*" - "*-audit" - "*-audit-*" - "*secret*detect*" - "*detect*secret*" allowFailureMustBeFalse: { enabled: true } rulesMustNotBeRedefined: { enabled: true } whenMustNotBeManual: { enabled: true }pipelineMustNotExecuteUnverifiedScripts
Flags scripts downloaded and executed in one go (curl | bash, wget | sh) from a URL that is not trusted. Raises ISSUE-411 (high).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
trustedUrls | empty | URL patterns that do not trigger a finding. Wildcards are supported; matching is host-precise, so https://example.com/* does not cover a subdomain. |
gitlab: controls: pipelineMustNotExecuteUnverifiedScripts: enabled: true trustedUrls: - https://internal-artifacts.example.com/*github: controls: pipelineMustNotExecuteUnverifiedScripts: enabled: true trustedUrls: - https://internal-artifacts.example.com/*pipelineMustNotUseDockerInDocker
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).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
detectInsecureDaemon | true | Also flags an empty DOCKER_TLS_CERTDIR or a plaintext DOCKER_HOST such as tcp://docker:2375 in a DinD job (ISSUE-413). |
gitlab: controls: pipelineMustNotUseDockerInDocker: enabled: true detectInsecureDaemon: truegithub: controls: pipelineMustNotUseDockerInDocker: enabled: true detectInsecureDaemon: trueexternalRefsMustNotCollide
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
Flags a job image that does not come from a trusted registry or publisher. Raises ISSUE-101 (high).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
trustDockerHubOfficialImages | true (unset: false) | Trusts Docker Hub official images such as nginx or alpine. |
trustedUrls | curated list, about 90 entries | Trusted 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. |
includePlumberDefaults | true | Overlay 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
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).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
trustSameGroupComponents | true | Trusts components under the scanned project’s root namespace (top-level group) on the same GitLab instance. |
trustSameInstanceComponents | true | Trusts 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. |
trustGitlabOfficialComponents | true | Trusts 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. |
trustedComponents | gitlab.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
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).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
trustSameGroupFunctions | true | Trusts 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. |
trustedFunctions | empty | Trusted 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
Flags an included template or component pinned to a version older than the latest available. Raises ISSUE-403 (low). No field beyond enabled.
includesMustNotUseForbiddenVersions
Flags an include pinned to a mutable ref. Raises ISSUE-404 (medium).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
forbiddenVersions | 5 patterns, see below | Version patterns considered forbidden. |
defaultBranchIsForbiddenVersion | true | Also forbids the included project’s default branch, whatever its name. |
gitlab: controls: includesMustNotUseForbiddenVersions: enabled: true forbiddenVersions: [latest, "~latest", main, master, HEAD] defaultBranchIsForbiddenVersion: truepipelineMustNotUseUnsafeVariableExpansion
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).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
dangerousVariables | 10 variables, see below | Variables whose value comes from user input. |
allowedPatterns | empty | A 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
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).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
variables | 10 variables, see below | Variable 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_DISABLEDcicdVariablesMustBeProtected
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
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
Flags an approval rule covering all protected branches that requires fewer approvals than the minimum. Raises ISSUE-502 (high).
| Field | Default | Description |
|---|---|---|
enabled | false | Turns the control on. |
minimumRequiredApprovals | 1 | The fewest approvals a rule covering all protected branches must require. Unset asserts nothing. |
gitlab: controls: mergeRequestApprovalRulesMustRequireMinimumApprovals: enabled: true minimumRequiredApprovals: 2mergeRequestApprovalRulesMustCoverAllProtectedBranches
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
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.
| Field | Default | Expects |
|---|---|---|
enabled | false | Turns the control on. |
preventApprovalByAuthor | unset | Authors cannot approve their own merge requests. |
preventApprovalsByCommitters | unset | Users who committed to a merge request cannot approve it. |
preventEditingApprovalRulesInMR | unset | Approval rules cannot be edited in a merge request. |
requireReAuthToApprove | unset | Approving requires re-authentication (password or SAML). |
behaviorWhenCommitIsAdded | unset | The 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_approvalsmergeRequestSettingsMustBeCompliant
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.
| Field | Default | Expects |
|---|---|---|
enabled | false | Turns the control on. |
mergeMethod | unset | The merge method: merge, ff or rebase_merge. |
squashOption | unset | The squash setting: never, always, default_on or default_off. |
mergePipelinesEnabled | unset | The “merged results pipelines” setting. GitLab Premium |
mergeTrainsEnabled | unset | The “merge trains” setting. GitLab Premium |
allowMergeOnSkippedPipeline | unset | The “allow merge when the pipeline is skipped” setting. |
resolveOutdatedDiffDiscussions | unset | The “automatically resolve outdated diff discussions” setting. |
printingMergeRequestLinkEnabled | unset | The “show the merge request link when pushing” setting. |
removeSourceBranchAfterMerge | unset | The “delete source branch after merge” default. |
gitlab: controls: mergeRequestSettingsMustBeCompliant: enabled: true mergeMethod: ff squashOption: default_on allowMergeOnSkippedPipeline: false removeSourceBranchAfterMerge: trueprojectMustHaveSecurityPolicySource
Checks that the project is linked to a security policy project, optionally a specific one. Raises ISSUE-601 (critical).
| Field | Default | Description |
|---|---|---|
enabled | false | Turns the control on. |
expectedProjectId | unset | The numeric ID the linked policy project must have. Unset only requires that some policy project is linked. |
expectedProjectPath | unset | The 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-projectpipelineMustNotIncludeHardcodedJobs
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
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.
| Field | Default | Description |
|---|---|---|
enabled | false | Turns the control on. |
required | unset | The requirement as a boolean expression of component paths (group/project/component). See Required expressions. Exclusive with requiredGroups. |
requiredGroups | empty | The 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/plumberpipelineMustIncludeTemplate
Checks that the pipeline includes the required templates and does not override their jobs. Raises ISSUE-405 (high) and ISSUE-406 (medium).
| Field | Default | Description |
|---|---|---|
enabled | false | Turns the control on. |
required | unset | The requirement as a boolean expression of template paths. Exclusive with requiredGroups. |
requiredGroups | empty | The 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
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.
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
trustedOwners | actions, github | Action owners exempt from the requirement. List only owners inside your trust boundary. |
github: controls: actionsMustBePinnedByCommitSha: enabled: true trustedOwners: [actions, github, myorg]githubActionMustComeFromAuthorizedSources
Flags an action whose owner is not trusted by any of the four rules below. Raises ISSUE-713 (high).
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
trustGithubOfficialActions | true | Trusts GitHub’s own actions, actions/* and github/*. |
trustSameOrgActions | true | Trusts actions owned by the same organization or user as the scanned repository. |
minimumStars | 20000 (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. |
trustedGithubActions | curated list, about 150 entries | Trusted 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. |
includePlumberDefaults | true | Overlay 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-actionactionsMustNotBeArchived
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
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
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
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
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.
| Field | Default | Description |
|---|---|---|
enabled | true | Turns the control on. |
exemptWorkflows | empty | A list of globs on the workflow file name, such as triage.yml; every job of a matching workflow is exempt. |
exemptJobs | empty | A 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
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
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
Flags toJSON(secrets) and other expressions that expose the whole secrets context at once. Raises ISSUE-309 (critical). No field beyond enabled.
workflowMustNotInjectUserInputInScripts
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
Flags a step that writes user-controlled content to $GITHUB_ENV or $GITHUB_PATH. Raises ISSUE-209 (high). No field beyond enabled.
workflowMustNotUseDangerousTriggers
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
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
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
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
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
Checks that the workflows of the repository, taken together, reference the required actions or reusable workflows. Raises ISSUE-417 (high).
| Field | Default | Description |
|---|---|---|
enabled | false | Turns the control on. |
required | unset | The 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. |
requiredGroups | empty | The 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