plumber

CI/CD security scanner for GitHub Actions and GitLab CI

Securing the workflows of:

Lightpanda ★ 35.6k

Delve ★ 24.9k

Resty ★ 11.8k

Bunkerity ★ 11k

intuitem ★ 4.4k

📡 Plumber Radar ➡️ 20k public repos scanned

What is Plumber?

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

• GitHub Actions: scans .github/workflows/*.{yml,yaml} and repository settings.
• GitLab CI: scans .gitlab-ci.yml, resolved includes, and repository settings.

Findings are reported in the terminal, JSON, SARIF, GitLab SAST, CSV, OCSF, PBOM, and CycloneDX.

Where to run it

Quick start

brew tap getplumber/plumber
brew trust --formula getplumber/plumber/plumber
brew install plumber

plumber analyze

No config file is needed: plumber analyze runs with the built-in default configuration (defaultConfig/.plumber.yaml) and auto-detects the provider from your git remote.

Install

Other options besides Homebrew:

• mise use -g github:getplumber/plumber
• A binary from GitHub Releases
• The Docker image docker.io/getplumber/plumber on Docker Hub

Authenticate

# GitHub, using the gh CLI keyring
gh auth login
# or, for CI runners and automation
export GH_TOKEN=ghp_xxxx

# GitLab
export GITLAB_TOKEN=glpat_xxxx

Run

# current repo
plumber analyze

# a GitHub repo without a local clone
plumber analyze --provider github --github-url github.com --project owner/repo

# a GitLab project without a local clone
plumber analyze --provider gitlab --gitlab-url https://gitlab.com --project group/project

Run plumber analyze --help for the full flag list.

GitHub Action

Add the official Plumber action to .github/workflows/plumber.yml:

name: Plumber

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write
  id-token: write # required by score-push

jobs:
  plumber:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v6
      - uses: getplumber/plumber@<version>
        with:
          # Publishes your Plumber Score and repository name publicly on
          # score.getplumber.io (see Score badge below). Set to false to keep them private.
          score-push: true

Full guide: getplumber.io/docs/cli/github#run-with-github-actions

GitLab CI component

Add the official Plumber component to .gitlab-ci.yml:

include:
  - component: gitlab.com/getplumber/plumber/plumber@<version>
    inputs:
      # Publishes your Plumber Score and repository name publicly on
      # score.getplumber.io (see Score badge below). Set to false to keep them private.
      score_push: true

Add GITLAB_TOKEN in Settings -> CI/CD -> Variables: read_api + read_repository for scanning, or api if you want Plumber to post MR comments or badges.

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

Self-hosted GitLab: host or mirror the component in your instance and include that URL. Guide.

Score badge

The badge at the top of this README comes from the hosted score service. With score push on (score-push: true on the Action, score_push: true on the component, as in the snippets above), each run on the default branch keeps an A-E badge for your repo up to date:

[![Plumber Score](https://score.getplumber.io/github.com/OWNER/REPO.svg)](https://score.getplumber.io/github.com/OWNER/REPO)

For a GitLab project, use gitlab.com/GROUP/PROJECT in place of github.com/OWNER/REPO.

Score push makes your score and repository name public, works in CI only, and is off by default when the input is omitted. See the score docs.

Configuration

Plumber reads .plumber.yaml; without one, the built-in default applies.

plumber config init       # create one interactively
plumber config generate   # write the full commented default template
plumber config validate
plumber explain ISSUE-411

Example:

version: "2.0"

github:
  controls:
    actionsMustBePinnedByCommitSha:
      enabled: true
      trustedOwners:
        - actions
        - github

gitlab:
  controls:
    containerImageMustNotUseForbiddenTags:
      enabled: true

Extend the baseline with extends: plumber:default and list only what you change; new controls Plumber ships then appear automatically. Full reference: defaultConfig/.plumber.yaml and getplumber.io/docs/cli.

Controls

A few of the checks Plumber runs:

• Unpinned actions and images: a third-party action or container image referenced by a tag that can be moved to other code.
• Remote scripts piped into a shell: curl | bash and similar, running code nobody reviewed.
• Unprotected default branch: anyone with push access can change what gets built and released.
• See all controls

Outputs

Exit codes

Contributing

make build
make test

Contributing guide: CONTRIBUTING.md

Resources

• Website: getplumber.io
• Documentation: getplumber.io/docs/cli, with troubleshooting in the GitHub and GitLab guides
• Community: Discord, or tech@getplumber.io
• GitHub Action listing: Plumber Score
• GitLab component listing: CI/CD Catalog
• Security policy: SECURITY.md

License

Plumber is licensed under the Mozilla Public License 2.0.