OpenSource CLI

The Plumber CLI allows you to analyze GitLab CI/CD pipelines from the command line for security and compliance issues like:

• Container images using mutable tags (latest, dev)
• Container images from untrusted registries
• Unprotected branches
• Hardcoded jobs not from includes/components
• Outdated includes/templates
• Forbidden version patterns (e.g., main, HEAD)
• Missing required components or templates

This is useful for local testing, CI/CD integration, or automated compliance checks.

Installation

brew tap getplumber/plumber
brew install plumber

brew install getplumber/plumber/plumber@0.1.72

mise use -g github:getplumber/plumber

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-linux-amd64
chmod +x plumber-linux-amd64
sudo mv plumber-linux-amd64 /usr/local/bin/plumber

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-linux-arm64
chmod +x plumber-linux-arm64
sudo mv plumber-linux-arm64 /usr/local/bin/plumber

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-darwin-arm64
chmod +x plumber-darwin-arm64
sudo mv plumber-darwin-arm64 /usr/local/bin/plumber

curl -LO https://github.com/getplumber/plumber/releases/latest/download/plumber-darwin-amd64
chmod +x plumber-darwin-amd64
sudo mv plumber-darwin-amd64 /usr/local/bin/plumber

Invoke-WebRequest -Uri https://github.com/getplumber/plumber/releases/latest/download/plumber-windows-amd64.exe -OutFile plumber.exe

curl -LO https://github.com/getplumber/plumber/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing

docker pull getplumber/plumber:latest

docker run --rm \
  -e GITLAB_TOKEN=glpat-xxxx \
  getplumber/plumber:latest analyze \
  --gitlab-url https://gitlab.com \
  --project mygroup/myproject

git clone https://github.com/getplumber/plumber.git
cd plumber
make build
# or: make install (builds and copies to /usr/local/bin/)

Quick Start

Command Reference

plumber analyze

The main command for analyzing GitLab CI/CD pipelines.

plumber analyze [flags]

Flags

Environment Variables

Automatic Version Check

When running locally, Plumber checks GitHub for newer releases on every invocation and prints an upgrade notice if one is available. The check runs asynchronously and has a 3-second timeout, so it never slows down the analysis.

The check is automatically skipped when:

• Running in CI environments (CI or GITLAB_CI environment variables are set)
• Using a development build (version is dev)

To disable it manually:

export PLUMBER_NO_UPDATE_CHECK=1

Exit Codes

plumber config generate

Generate a default .plumber.yaml configuration file.

plumber config generate [flags]

Examples:

# Generate default config
plumber config generate

# Custom filename
plumber config generate --output my-plumber.yaml

# Overwrite existing file
plumber config generate --force

plumber config view

Display a clean, human-readable view of the effective configuration without comments.

plumber config view [flags]

Booleans are colorized for quick scanning: true in green, false in red. Color is automatically disabled when piping output.

Examples:

# View the default .plumber.yaml
plumber config view

# View a specific config file
plumber config view --config custom-plumber.yaml

# View without colors (for piping or scripts)
plumber config view --no-color

plumber config validate

Validate a configuration file for correctness. Detects unknown control names and sub-keys with typo suggestions using fuzzy matching.

plumber config validate [flags]

Warnings are printed to stderr so they don’t interfere with scripted output. Use --fail-warnings to exit with code 2 when warnings are found (useful in CI).

Examples:

# Validate the default .plumber.yaml
plumber config validate

# Validate a specific config file
plumber config validate --config custom-plumber.yaml

# Fail on warnings (for CI pipelines)
plumber config validate --fail-warnings

Sample output with typos:

Configuration validation warnings:
  - Unknown control in .plumber.yaml: "containerImageMustNotUseForbiddenTag". Did you mean "containerImageMustNotUseForbiddenTags"?
  - Unknown key "tag" in control "containerImageMustNotUseForbiddenTags". Did you mean "tags"?
  - Unknown key "allowForcePushes" in control "branchMustBeProtected". Did you mean "allowForcePush"?

Usage Examples

Save JSON Output

docker run --rm \
  -e GITLAB_TOKEN=glpat-xxxx \
  -v $(pwd):/output \
  getplumber/plumber:latest analyze \
  --gitlab-url https://gitlab.com \
  --project mygroup/myproject \
  --branch main \
  --config /.plumber.yaml \
  --threshold 100 \
  --output /output/results.json

Self-Hosted GitLab

plumber analyze \
  --gitlab-url https://gitlab.example.com \
  --project mygroup/myproject \
  --branch develop \
  --config .plumber.yaml \
  --threshold 80

Silent Mode (JSON Only)

plumber analyze \
  --gitlab-url https://gitlab.com \
  --project mygroup/myproject \
  --config .plumber.yaml \
  --threshold 100 \
  --output results.json \
  --print false

Example Output

The CLI output is color-coded in your terminal for easy scanning — green for passing controls, red for failures.

Pipeline Bill of Materials (PBOM) & CycloneDX

Plumber can generate a PBOM — a complete inventory of all dependencies in your CI/CD pipeline (container images, components, templates, includes). Two formats are available:

Native PBOM (detailed, pipeline-specific):

plumber analyze --pbom pbom.json

CycloneDX SBOM (standard format for security tool integration):

plumber analyze --pbom-cyclonedx pipeline-sbom.json

The CycloneDX output follows the CycloneDX 1.5 specification and is compatible with tools like Grype, Trivy, and Dependency-Track. When using the GitLab CI component, the CycloneDX file is automatically uploaded as a GitLab CycloneDX report.

Configuration

Plumber uses a .plumber.yaml configuration file to customize checks.

Available Controls

Plumber includes compliance controls covering CI/CD configuration, repository settings, and access management. Each can be enabled/disabled and customized. When a control detects a violation, it creates an Issue (e.g., ISSUE-101) with a direct link to its documentation page.

eval "$CI_COMMIT_BRANCH"
sh -c "$CI_MERGE_REQUEST_TITLE"
bash -c "$CI_COMMIT_MESSAGE"
source <(echo "$CI_COMMIT_REF_NAME")
echo "$CI_COMMIT_BRANCH" | xargs sh

echo $CI_COMMIT_BRANCH
curl -d "$CI_MERGE_REQUEST_TITLE" https://...
git checkout $CI_COMMIT_REF_NAME
printf '%s' "$CI_COMMIT_MESSAGE"

pipelineMustNotUseUnsafeVariableExpansion:
  enabled: true
  dangerousVariables:
    - CI_MERGE_REQUEST_TITLE
    - CI_COMMIT_MESSAGE
    - CI_COMMIT_REF_NAME
    - CI_COMMIT_REF_SLUG
    - CI_COMMIT_BRANCH
  allowedPatterns:
    - "helm.*--set.*\\$CI_"
    - "terraform workspace select.*\\$CI_"
    - "docker build.*--build-arg.*\\$CI_"
    - "aws s3 sync.*\\$CI_"
    - "make deploy.*\\$CI_"

include:
  - template: Security/SAST.gitlab-ci.yml

semgrep-sast:
  allow_failure: true       # failures silently ignored

secret_detection:
  rules:
    - when: never            # job will never run

container_scanning:
  when: manual               # requires manual trigger

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

pipelineMustNotExecuteUnverifiedScripts:
  enabled: true
  trustedUrls: []
    # - https://internal-artifacts.example.com/*

Issues

Every violation detected by Plumber is identified as an Issue following the pattern ISSUE-XXXX. Each issue links to a dedicated documentation page with:

• Description of the problem
• Impact on your security posture
• How to fix with before/after configuration examples
• Tips for best practices

Issues are displayed in the CLI output, MR comments, and the summary table. Click any issue to view its full documentation.

Example Configuration

version: "1.0"

controls:
  containerImageMustNotUseForbiddenTags:
    enabled: true
    tags:
      - latest
      - dev
      - main
    # When true, ALL images must be pinned by digest (e.g., alpine@sha256:...)
    # Takes precedence over tags list — even version tags like alpine:3.19 will be flagged
    containerImagesMustBePinnedByDigest: false

  containerImageMustComeFromAuthorizedSources:
    enabled: true
    trustDockerHubOfficialImages: true
    trustedUrls:
      - $CI_REGISTRY_IMAGE:*
      - registry.gitlab.com/security-products/*

  branchMustBeProtected:
    enabled: true
    defaultMustBeProtected: true
    namePatterns:
      - main
      - release/*
    allowForcePush: false
    minMergeAccessLevel: 30   # Developer
    minPushAccessLevel: 40    # Maintainer

  pipelineMustNotIncludeHardcodedJobs:
    enabled: true

  includesMustBeUpToDate:
    enabled: true

  includesMustNotUseForbiddenVersions:
    enabled: true
    forbiddenVersions:
      - latest
      - "~latest"
      - main
      - master
      - HEAD
    defaultBranchIsForbiddenVersion: false

  pipelineMustIncludeComponent:
    enabled: false  # Disabled by default - enable and configure for your org
    # Expression syntax (use one, not both):
    # required: components/sast/sast AND components/secret-detection/secret-detection
    # Array syntax (OR of ANDs):
    # requiredGroups:
    #   - ["components/sast/sast", "components/secret-detection/secret-detection"]
    #   - ["your-org/full-security/full-security"]

  pipelineMustIncludeTemplate:
    enabled: false  # Disabled by default - enable and configure for your org
    # Expression syntax (use one, not both):
    # required: templates/go/go AND templates/trivy/trivy
    # Array syntax (OR of ANDs):
    # requiredGroups:
    #   - ["templates/go/go", "templates/trivy/trivy"]
    #   - ["templates/full-go-pipeline"]

  # Detect debug trace variables that leak secrets in job logs
  pipelineMustNotEnableDebugTrace:
    enabled: true
    forbiddenVariables:
      - CI_DEBUG_TRACE
      - CI_DEBUG_SERVICES

  # Detect user-controlled variables in shell re-interpretation contexts (eval, sh -c, etc.)
  # Safe: echo $CI_COMMIT_BRANCH. Dangerous: eval "deploy $CI_COMMIT_BRANCH"
  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
    # Regex patterns to allow specific script lines (escape $ as \\$)
    allowedPatterns:
      - "helm.*--set.*\\$CI_"
      - "terraform workspace select.*\\$CI_"
      - "docker build.*--build-arg.*\\$CI_"

  # Detect security scanning jobs that have been silently weakened
  securityJobsMustNotBeWeakened:
    enabled: true
    securityJobPatterns:
      - "*-sast"
      - "secret_detection"
      - "container_scanning"
      - "*_dependency_scanning"
      - "gemnasium-*"
      - "dast"
      - "dast_*"
      - "license_scanning"
    allowFailureMustBeFalse:
      enabled: false   # opt-in (GitLab templates ship with allow_failure: true)
    rulesMustNotBeRedefined:
      enabled: true
    whenMustNotBeManual:
      enabled: true

  # Detect unverified script downloads and execution (curl|bash, wget|sh)
  pipelineMustNotExecuteUnverifiedScripts:
    enabled: true
    trustedUrls: []
      # - https://internal-artifacts.example.com/*

Selective Control Execution

You can run or skip specific controls using their YAML key names from .plumber.yaml. This is useful for iterative debugging or targeted CI checks.

Run only specific controls:

# Only check image tags and branch protection
plumber analyze --controls containerImageMustNotUseForbiddenTags,branchMustBeProtected

Skip specific controls:

# Run everything except branch protection
plumber analyze --skip-controls branchMustBeProtected

Controls not selected are reported as skipped in the output. The --controls and --skip-controls flags are mutually exclusive.

GitLab Integration

Plumber integrates directly with GitLab to provide visual compliance feedback where your team works.

Merge Request Comments

Automatically post compliance summaries on merge requests to catch issues before they’re merged.

plumber analyze --mr-comment

Or via the GitLab CI component:

include:
  - component: gitlab.com/getplumber/plumber/plumber@v0.1.29
    inputs:
      mr_comment: true  # Requires api scope on token

Features:

• Shows compliance badge with pass/fail status
• Lists all controls with individual compliance percentages
• Details specific issues found with job names and image references
• Automatically updates on each pipeline run (no duplicate comments)

Project Badges

Display a live compliance badge on your project’s overview page.

plumber analyze --badge

Or via the GitLab CI component:

include:
  - component: gitlab.com/getplumber/plumber/plumber@v0.1.29
    inputs:
      badge: true  # Requires api scope on token

Features:

• Shows current compliance percentage
• Green when compliance meets threshold, red when below
• Only updates on default branch pipelines (not on MRs or feature branches)
• Badge appears in GitLab’s “Project information” section

Troubleshooting