Plumber

CI/CD compliance scanner for GitLab CI and GitHub Actions
_{One CLI, one .plumber.yaml, one Rego policy engine.}

OpenSSF Scorecard SLSA 3

Build Status Latest Release Go Version GitHub Downloads Docker Pulls License

Website • Docs • Discord • Issues

Plumber scans CI/CD pipelines for risky patterns and compliance gaps.

• GitLab CI: reads .gitlab-ci.yml, resolved includes, and repository settings.
• GitHub Actions: reads .github/workflows/*.{yml,yaml} locally or through the GitHub API.
• One config: .plumber.yaml contains provider-specific policy sections for GitLab and GitHub.

Plumber reports findings in the terminal, JSON, SARIF, GitLab SAST, PBOM, and CycloneDX formats.

Plumber GitLab CI component running

Run your first scan before reading the full docs.

brew tap getplumber/plumber
brew install plumber
plumber config generate # generates default configuration yaml file
plumber analyze

See the generated default config in this repo: .plumber.yaml.

Plumber auto-detects the provider from your git remote. Use explicit flags when scanning a repo that is not the current checkout.

brew tap getplumber/plumber
brew install plumber

Other options:

• mise use -g github:getplumber/plumber
• Download a binary from GitHub Releases
• Run the Docker image: getplumber/plumber

Full install docs:

• GitLab: getplumber.io/docs/cli/gitlab#installation
• GitHub: getplumber.io/docs/cli/github#installation

GitLab:

export GITLAB_TOKEN=glpat_xxxx

GitHub (preferred — uses the gh CLI's keyring):

gh auth login

Alternative (CI runners, automation):

export GH_TOKEN=ghp_xxxx

GitHub local scans can run without a token for workflow-content checks. A token enables repo-level and action-metadata checks.

If a workflow uses an action hosted in an org with an IP allow list (which blocks the runner's GITHUB_TOKEN), set PLUMBER_METADATA_TOKEN to a token with public-repository read so Plumber can still resolve that action's version for the known-CVE check. Without it, Plumber falls back to an anonymous read and, if that is rate-limited too, skips the version check rather than guessing.

Current repo:

plumber analyze

Specific GitLab project:

plumber analyze \
 --provider gitlab \
 --gitlab-url https://gitlab.com \
 --project group/project

Specific GitHub repo without a local clone:

plumber analyze \
 --provider github \
 --github-url github.com \
 --project owner/repo

Add Plumber to .gitlab-ci.yml:

include:
 - component: gitlab.com/getplumber/plumber/plumber@<version>

Find the latest published version on the GitLab CI/CD Catalog.

Then add GITLAB_TOKEN in Settings -> CI/CD -> Variables.

Use read_api + read_repository for scanning. Use api if you want Plumber to create MR comments or badges.

Full guide: getplumber.io/docs/cli/gitlab#gitlab-ci-component

Add Plumber to .github/workflows/plumber.yml:

name: Plumber
on:
 pull_request:
 push:
 branches: [main]
permissions:
 contents: read
 security-events: write
jobs:
 plumber:
 runs-on: ubuntu-24.04
 steps:
 - uses: actions/checkout@v6
 - uses: getplumber/plumber@9a74a6e0eccc2dad90f89ae8441c58fc97a35196 # v0.3.58

To resolve action versions hosted in an org with an IP allow list, pass a public-repo-read token via the metadata-token input (kept in a secret):

 with:
 metadata-token: ${{ secrets.PLUMBER_METADATA_TOKEN }}

Full guide (SARIF upload, Code Scanning, action inputs): getplumber.io/docs/cli/github#github-action

Plumber reads .plumber.yaml.

Create a config interactively:

plumber config init

Generate the full commented default template:

plumber config generate

Example:

version: "2.0"
gitlab:
 controls:
 containerImageMustNotUseForbiddenTags:
 enabled: true
github:
 controls:
 actionsMustBePinnedByCommitSha:
 enabled: true
 trustedOwners:
 - actions
 - github

Useful commands:

plumber config validate
plumber config view
plumber config diff
plumber explain ISSUE-411

Full config reference:

• Default config: .plumber.yaml
• CLI docs: getplumber.io/docs/cli
• Issue reference: getplumber.io/docs/cli/issues

Plumber ships controls for:

• container image pinning and authorized sources
• branch protection
• unverified script execution (curl | bash, base64 -d | bash, etc.)
• Docker-in-Docker
• weakened security jobs
• unsafe variable expansion
• GitHub action pinning, archived actions, and known CVEs
• dangerous GitHub triggers and overbroad permissions
• hardcoded secrets in pipeline YAML (opt-in; shells out to gitleaks)

Full catalogs:

• GitLab controls: getplumber.io/docs/cli/gitlab#available-controls
• GitHub controls: getplumber.io/docs/cli/github#available-controls

Plumber terminal output

Example:

plumber analyze \
 --output results.json \
 --sarif results.sarif \
 --pbom pbom.json \
 --pbom-cyclonedx cdx.json

More details:

• PBOM docs: docs/PBOM.md
• Scoring docs: docs/scoring.md
• CLI reference: getplumber.io/docs/cli

If you run a self-hosted GitLab instance, host or mirror the Plumber component inside your instance, publish a release, and include that component URL from your pipelines.

Guide: getplumber.io/docs/cli/gitlab#hosting-on-self-hosted-gitlab

More help:

• GitLab guide: getplumber.io/docs/cli/gitlab
• GitHub guide: getplumber.io/docs/cli/github
• Discord: discord.gg/932xkSU24f

Build locally:

make build

Run tests:

make test

Contributing guide: CONTRIBUTING.md

• Website: getplumber.io
• Documentation: getplumber.io/docs/cli
• GitHub Action listing: Plumber Compliance Scanner
• GitLab component docs: COMPONENT_README.md
• Security policy: SECURITY.md

Plumber is licensed under the Mozilla Public License 2.0.