CI/CD security scanner for GitHub Actions and GitLab CI

Securing the workflows of:

Lightpanda ★ 35.6k

Delve ★ 24.9k

Resty ★ 11.8k

nginx-ui ★ 11.5k

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.

Where to run it

| | Use it for | |---|---| | 💻 Run locally | Trying Plumber, or auditing repos from a script | | 🐙 Run in GitHub Actions | Checks on every PR and push, findings in Code Scanning | | 🦊 Run in GitLab CI | Checks on every pipeline, findings in the MR widget |

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 github.com/owner/repo
a GitLab project without a local clone (self-hosted instances work too)
plumber analyze gitlab.com/group/project

The target can also be a full URL pasted from the browser (https://github.com/owner/repo/tree/main selects the branch). 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:

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

| Output | Flag | Use it for | |---|---|---| | Terminal | default | Human review during local or CI runs | | JSON | --output results.json | Automation and dashboards | | SARIF | --sarif results.sarif | GitHub Code Scanning and SARIF tools | | GitLab SAST | --glsast gl-sast-report.json | GitLab Security Dashboard / MR widget | | CSV | --csv results.csv | Spreadsheets, ad-hoc analysis | | OCSF | --ocsf plumber.ocsf.json | OCSF consumers and GRC platforms | | PBOM | --pbom pbom.json | Pipeline inventory | | CycloneDX | --pbom-cyclonedx cdx.json | SBOM tooling |

Exit codes

| Code | Meaning | |---|---| | 0 | Score meets the gate (--min-points / --min-score), or --no-controls was used and collection succeeded | | 1 | Score is below the gate | | 2 | Invalid usage or configuration, or a runtime / provider / auth / network failure | | 3 | Data collection was incomplete, so the score is withheld; or a check could not be verified and --fail-warnings is set (e.g. an action version that could not be resolved) |

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 [email protected]
• 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.