.plumber.yaml

# Plumber Configuration - Trust Policy Manager for GitLab CI/CD
# This file is required for 'plumber analyze' to work.
# Default file name: .plumber.yaml
# Reference: https://github.com/getplumber/plumber/blob/main/.plumber.yaml
# Can be generated with: plumber config generate

version: "1.0"

# Controls configuration
# Each control can be enabled/disabled and customized
controls:

  # ===========================================
  # Container images must not use forbidden tags
  # ===========================================
  # Detects CI/CD jobs using Docker images with forbidden tags.
  # Forbidden tags (like 'latest') can point to different images over time,
  # making builds non-reproducible and potentially introducing security risks.
  #
  # Best practice: Use immutable tags (e.g., specific versions or SHA digests) and not forbidden tags
  containerImageMustNotUseForbiddenTags:
    # Set to false to disable this control
    enabled: true

    # Tags considered "forbidden" - images using these will be flagged
    tags:
      - latest
      - dev
      - development
      - staging
      - main
      - master
      # v8.15.0
      # Add your organization's custom mutable tags below:
      # - nightly
      # - edge
      # - canary
      # - unstable

    # When true, ALL images must be pinned by digest (e.g., alpine@sha256:...).
    # This takes precedence over the forbidden tags list — any image not using
    # an immutable digest reference will be flagged, including standard version
    # tags like alpine:3.19 or node:20.
    containerImagesMustBePinnedByDigest: true

  # ===========================================
  # Container images must come from authorized sources
  # ===========================================
  # Detects CI/CD jobs using Docker images from untrusted registries.
  # Only images from explicitly trusted sources should be used in pipelines
  # to prevent supply chain attacks.
  #
  # Best practice: Maintain a list of approved registries and image patterns
  containerImageMustComeFromAuthorizedSources:
    # Set to false to disable this control
    enabled: true

    # Trust official Docker Hub images (e.g., nginx, alpine, python)
    # These are images without a username prefix on Docker Hub
    trustDockerHubOfficialImages: true

    # Trusted registry URLs and patterns (supports wildcards)
    # Images matching these patterns will be considered trusted
    trustedUrls:
      # Docker Hub official images (if trustDockerHubOfficialImages is false)
      # - docker.io/library/*

      # Common CI/CD tool images
      - docker.io/docker:*
      - docker.io/getplumber/plumber:*
      - getplumber/plumber:*
      - docker.io/getplumber/plumber@sha256:*

      # GitLab registry patterns
      - $CI_REGISTRY_IMAGE:*
      - $CI_REGISTRY_IMAGE/*
      - $CI_REGISTRY/*
      - ${CI_REGISTRY}/*
      - ${CI_REGISTRY_IMAGE}:*
      - ${CI_REGISTRY_IMAGE}/*

      # GitLab Dependency Proxy
      - ${CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX}/*

      # GitLab official registries
      - registry.gitlab.com/security-products/*
      - registry.gitlab.com/gitlab-org/*
      - registry.gitlab.com/pipeline-components/*

      # Do NOT use host-wide patterns such as ghcr.io/*, gcr.io/*, quay.io/*, mcr.microsoft.com/*,
      # nvcr.io/* — anyone can publish images on those registries; wildcards would trust all of them.
      # Prefer org-scoped patterns instead, e.g. ghcr.io/my-org/*, quay.io/prometheus/*

      # Docker Hub — well-known publishers (DevOps / CI tooling)
      # Each entry below corresponds to a Docker Hub Verified Publisher,
      # the upstream project's own namespace, or an officially recognised
      # community publisher for that tool. See docs/trusted-registries.md
      # for verification notes.
      - docker.io/curlimages/*       # curl docker team (curl/curl-container)
      - docker.io/alpine/*           # Alpine Linux maintainers (alpinelinux org)
      - docker.io/golangci/*         # golangci-lint upstream
      - docker.io/koalaman/*         # ShellCheck author (Vidar Holen)
      - docker.io/hadolint/*         # hadolint upstream
      - docker.io/semgrep/*          # Semgrep, Inc.
      - docker.io/sonarsource/*      # SonarSource verified publisher
      - docker.io/cypress/*          # Cypress.io verified publisher
      - docker.io/gittools/*         # GitTools (GitVersion) upstream
      - docker.io/renovate/*         # Renovate Bot (Mend.io) verified publisher
      - docker.io/gitlab/*           # GitLab verified publisher
      - docker.io/lycheeverse/*      # lychee link checker upstream
      - docker.io/hugomods/*         # HugoMods Hugo container project
      - docker.io/fsfe/*             # Free Software Foundation Europe (REUSE)
      - docker.io/hashicorp/*        # HashiCorp (IBM) verified publisher
      - docker.io/cimg/*             # CircleCI convenience images
      - docker.io/circleci/*         # CircleCI legacy convenience images

      # Docker Hub — cloud vendor official images
      - docker.io/amazon/*           # Amazon Web Services
      - docker.io/google/*           # Google
      - docker.io/nvidia/*           # NVIDIA verified publisher
      - docker.io/bitnami/*          # Bitnami / VMware (Broadcom) verified publisher

      # Docker Hub — OS / distro official images
      - docker.io/redhat/*           # Red Hat
      - docker.io/opensuse/*         # openSUSE Project
      - docker.io/gentoo/*           # Gentoo Linux maintainers
      - docker.io/nixos/*            # NixOS Foundation
      - docker.io/rustlang/*         # Rust Programming Language official

      # Microsoft Container Registry — official Microsoft products
      - mcr.microsoft.com/dotnet/*       # .NET official images
      - mcr.microsoft.com/playwright/*   # Playwright (Microsoft) browser images
      - mcr.microsoft.com/playwright     # tag-only ref form (no path suffix)

      # Quay.io — well-known projects with their own organisation
      - quay.io/buildah/*                       # Containers project (Buildah)
      - quay.io/podman/*                        # Containers project (Podman)
      - quay.io/containers/*                    # Containers project umbrella org
      - quay.io/centos/*                        # CentOS Project (CentOS Stream)
      - quay.io/pypa/*                          # Python Packaging Authority (manylinux)
      - quay.io/gnome_infrastructure/*          # GNOME Infrastructure team

      # GitHub Container Registry — well-known upstream organisations
      # ghcr.io/<org>/* is scoped to a single GitHub organisation, so each
      # entry must be the actual org that publishes the upstream tool.
      - ghcr.io/astral-sh/*          # Astral (uv, ruff)
      - ghcr.io/renovatebot/*        # Renovate Bot upstream
      - ghcr.io/containerbase/*      # containerbase (Renovate base images)
      - ghcr.io/canonical/*          # Canonical (snapcraft-rocks etc.)
      - ghcr.io/graalvm/*            # Oracle GraalVM team
      - ghcr.io/terraform-linters/*  # tflint upstream organisation
      - ghcr.io/prefix-dev/*         # prefix.dev (pixi)

      # Google Container Registry — Google-owned projects
      - gcr.io/kaniko-project/*                 # Kaniko (Google Cloud Build)
      - gcr.io/go-containerregistry/*           # google/go-containerregistry (crane, gcrane)
      - gcr.io/google.com/cloudsdktool/*        # Google Cloud SDK (gcloud) official



  # ===========================================
  # Branch must be protected
  # ===========================================
  # Checks that repository branches have proper protection settings.
  # Ensures critical branches (like main/master) are protected
  # from force pushes and require code reviews.
  #
  # Best practice: Protect default branch and release branches
  branchMustBeProtected:
    # Set to false to disable this control
    enabled: true

    # Require the default branch to be protected
    defaultMustBeProtected: true

    # Branch name patterns that must be protected (supports wildcards)
    namePatterns:
      - main
      - master
      - release/*
      - production
      - dev
      # Add your organization's protected branch patterns below:
      # - develop
      # - staging

    # When false, force push must be disabled on protected branches
    allowForcePush: false

    # Require code owner approval for changes
    codeOwnerApprovalRequired: false

    # Minimum access level required to merge (0=No one, 30=Developer, 40=Maintainer)
    minMergeAccessLevel: 30

    # Minimum access level required to push (0=No one, 30=Developer, 40=Maintainer)
    minPushAccessLevel: 40

  # ===========================================
  # Pipeline must not include hardcoded jobs
  # ===========================================
  # Detects CI/CD jobs that are defined directly in the .gitlab-ci.yml file
  # instead of being included from reusable components or templates.
  #
  # Hardcoded jobs make pipelines harder to maintain and don't benefit from
  # centralized updates when best practices change.
  #
  # Best practice: Use CI/CD components, templates, or includes for job definitions
  pipelineMustNotIncludeHardcodedJobs:
    # Set to false to disable this control
    enabled: true

  # ===========================================
  # Includes must be up to date
  # ===========================================
  # Detects CI/CD includes (components, templates, project files) from the
  # GitLab CI Catalog that are not using the latest available version.
  #
  # Outdated includes may miss important bug fixes, security patches,
  # or new features.
  #
  # Best practice: Regularly update includes to their latest versions
  includesMustBeUpToDate:
    # Set to false to disable this control
    enabled: true

  # ===========================================
  # Includes must not use forbidden versions
  # ===========================================
  # Detects CI/CD includes (components, templates, project files) using
  # mutable/forbidden version references like 'latest', 'main', 'master', or 'HEAD'.
  #
  # Mutable versions can change unexpectedly, making builds non-reproducible
  # and potentially introducing breaking changes without warning.
  #
  # Best practice: Use specific version tags (e.g., v1.2.3, ~1.0) for includes
  includesMustNotUseForbiddenVersions:
    # Set to false to disable this control
    enabled: true

    # Version patterns considered forbidden: includes using these will be flagged
    forbiddenVersions:
      - latest
      - "~latest"
      - main
      - master
      - HEAD
      # Add your organization's custom forbidden versions below:
      # - dev
      # - develop
      # - staging

    # When true, adds the project's default branch to forbidden versions
    defaultBranchIsForbiddenVersion: false

  # ============================================================================
  # Pipeline must include component
  # ============================================================================
  # Ensures pipelines include required GitLab CI/CD components.
  # Useful for enforcing security scanning, compliance, or utility components.
  #
  # Override detection: components that are imported but have their jobs
  # overridden with forbidden CI/CD keywords (script, image, rules, etc.)
  # are flagged as overridden. They still count as imported but produce
  # separate issues and reduce compliance to 50% for that component.
  #
  # Two ways to define requirements (use one, not both):
  #
  # Option 1 — Expression syntax ('required'):
  #   A natural boolean expression using AND, OR, and parentheses.
  #   AND binds tighter than OR, so "a AND b OR c" means "(a AND b) OR c".
  #
  #   required: components/sast/sast AND components/secret-detection/secret-detection
  #   required: (components/sast/sast AND components/secret-detection/secret-detection) OR your-org/full-security/full-security
  #
  # Option 2 — Array syntax ('requiredGroups'):
  #   A list of groups using "OR of ANDs" logic:
  #     - Each inner array = components that must ALL be present (AND)
  #     - Outer array = only ONE group needs to be satisfied (OR)
  #
  #   requiredGroups:
  #     - ["components/sast/sast", "components/secret-detection/secret-detection"]
  #     - ["your-org/full-security-pipeline/full-security"]
  #
  # For more expression examples, see https://github.com/getplumber/plumber/blob/main/configuration/expression_test.go
  #
  pipelineMustIncludeComponent:
    enabled: false
    # required: components/sast/sast AND components/secret-detection/secret-detection AND getplumber/plumber/plumber
    requiredGroups: []

  # ============================================================================
  # Pipeline must include template
  # ============================================================================
  # Ensures pipelines include required templates (project file includes).
  # Useful for enforcing organization-specific CI templates.
  #
  # Override detection: templates that are imported but have their jobs
  # overridden with forbidden CI/CD keywords (script, image, rules, etc.)
  # are flagged as overridden. They still count as imported but produce
  # separate issues and reduce compliance to 50% for that template.
  #
  # Two ways to define requirements (use one, not both):
  #
  # Option 1 — Expression syntax ('required'):
  #   required: templates/go/go AND templates/trivy/trivy
  #   required: (templates/go/go AND templates/trivy/trivy) OR templates/full-go-pipeline
  #
  # Option 2 — Array syntax ('requiredGroups'):
  #   requiredGroups:
  #     - ["templates/go/go", "templates/trivy/trivy"]
  #     - ["templates/full-go-pipeline"]
  #
  # For more expression examples, see https://github.com/getplumber/plumber/blob/main/configuration/expression_test.go
  #
  pipelineMustIncludeTemplate:
    enabled: false
    # required: templates/go/go AND templates/trivy/trivy AND templates/iso27001/iso27001
    requiredGroups: []

  # ===========================================
  # Pipeline must not enable debug trace
  # ===========================================
  # Detects CI/CD pipelines that set CI_DEBUG_TRACE or CI_DEBUG_SERVICES
  # to "true" in global or job-level variables.
  #
  # When CI_DEBUG_TRACE is enabled, GitLab prints ALL environment variables
  # in the job logs, including masked secrets like CI_JOB_TOKEN and any
  # custom CI/CD variables. This is a critical security risk.
  #
  # Best practice: Never enable CI_DEBUG_TRACE in committed CI configuration
  pipelineMustNotEnableDebugTrace:
    # Set to false to disable this control
    enabled: true

    # CI/CD variable names that must not be set to "true"
    forbiddenVariables:
      - CI_DEBUG_TRACE
      - CI_DEBUG_SERVICES

  # ===========================================
  # Pipeline must not use unsafe variable expansion
  # ===========================================
  # Detects user-controlled CI variables passed to commands that
  # re-interpret their input as shell code. This is OWASP CICD-SEC-1.
  #
  # GitLab sets CI variables as environment variables. The shell does
  # NOT re-parse expanded values for command substitution, so normal
  # usage is safe. Only commands that re-interpret arguments as code
  # create an injection surface.
  #
  # Flagged (re-interpretation contexts):
  #   - eval "$CI_COMMIT_BRANCH"
  #   - sh -c "$CI_MERGE_REQUEST_TITLE"
  #   - bash -c "$CI_COMMIT_MESSAGE"
  #   - dash -c / zsh -c / ksh -c
  #   - source <(echo "$CI_COMMIT_REF_NAME")
  #   - envsubst '$CI_COMMIT_MESSAGE' < tpl.sh | sh
  #   - echo "$CI_COMMIT_BRANCH" | xargs sh
  #
  # Not flagged (safe — shell doesn't re-parse env var values):
  #   - echo $CI_COMMIT_BRANCH
  #   - echo "$CI_COMMIT_MESSAGE"
  #   - curl -d "$CI_MERGE_REQUEST_TITLE" https://...
  #   - git checkout $CI_COMMIT_REF_NAME
  #   - printf '%s' "$CI_COMMIT_MESSAGE"
  #
  # Not caught (known limitation):
  #   - sh -c $BRANCH  (where BRANCH: $CI_COMMIT_BRANCH in variables:)
  #   Indirect aliasing is not tracked; only direct variable names.
  pipelineMustNotUseUnsafeVariableExpansion:
    # Set to false to disable this control
    enabled: true

    # CI/CD variables whose values come from user input and must not
    # appear in shell re-interpretation contexts (eval, sh -c, bash -c, etc.)
    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

    # Script lines
    #   sh -c "terraform workspace select $CI_COMMIT_REF_SLUG"
    #   sh -c "docker build --build-arg BRANCH=$CI_COMMIT_BRANCH ."
    #   sh -c "aws s3 sync dist/ s3://my-bucket/$CI_COMMIT_REF_SLUG/"
    #   bash -c "make deploy BRANCH=$CI_COMMIT_BRANCH"
    #
    # Allow with patterns:
    # (Escape $ as \\$, {} as \\{ \\} in patterns.)
    # allowedPatterns:
    #   - "helm.*--set.*\\$CI_"
    #   - "terraform workspace select.*\\$CI_"
    #   - "docker build.*--build-arg.*\\$CI_"
    #   - "aws s3 sync.*\\$CI_"
    #   - "make deploy.*\\$CI_"
    allowedPatterns: []

  # ===========================================
  # Security jobs must not be weakened
  # ===========================================
  # Detects GitLab CI security scanning jobs (SAST, Secret Detection,
  # Container Scanning, Dependency Scanning, DAST, License Scanning)
  # that have been weakened through overrides in .gitlab-ci.yml.
  #
  # Even when security templates are properly included, a developer
  # (or attacker) can silently neutralize them by:
  #   - Setting allow_failure: true (failures become invisible)
  #   - Overriding rules: with when: never or when: manual
  #   - Setting when: manual at job level (job never runs automatically)
  #
  # The pipeline still "includes" the security template, giving a false
  # sense of compliance while the actual scanning is disabled.
  #
  # Maps to OWASP CICD-SEC-4 (Poisoned Pipeline Execution).
  #
  # Best practice: Security jobs should run automatically and block the
  # pipeline on failure.
  securityJobsMustNotBeWeakened:
    # Set to false to disable this control
    enabled: true

    # Job name patterns considered "security jobs" (supports wildcards).
    # or any other jobs you want to be considered security jobs.
    securityJobPatterns:
      - "*-sast"
      - "secret_detection"
      - "container_scanning"
      - "*_dependency_scanning"
      - "gemnasium-*"
      - "dast"
      - "dast_*"
      - "license_scanning"

    # Detects security jobs with allow_failure: true.
    # Example:
    #   semgrep-sast:
    #     allow_failure: true
    # Off by default because GitLab templates ship with allow_failure: true.
    # Opt-in for orgs that want security checks to block the pipeline.
    allowFailureMustBeFalse:
      enabled: false

    # Detects security jobs whose rules: block is overridden with
    # when: never (job will never run) or when: manual (requires manual click).
    # Example:
    #   semgrep-sast:
    #     rules:
    #       - when: never
    # Example:
    #   secret_detection:
    #     rules:
    #       - when: manual
    rulesMustNotBeRedefined:
      enabled: true

    # Detects security jobs with when: manual set at job level.
    # Same effect as a rules override, but written differently.
    # Example:
    #   semgrep-sast:
    #     when: manual
    whenMustNotBeManual:
      enabled: true

  # ===========================================
  # Pipeline must not override job variables
  # ===========================================
  # Detects CI/CD variables that are redefined in the pipeline configuration
  # file (.gitlab-ci.yml) when they should only be set in GitLab CI/CD
  # Settings > Variables.
  #
  # An attacker who can modify .gitlab-ci.yml could override variables like
  # SECURE_ANALYZERS_PREFIX to point to a fake registry, or set
  # SAST_DISABLED: "true" to silently disable security scanners. The pipeline
  # still appears green, but no actual scanning occurs.
  #
  # This control is generic: add any variable name you want to protect,
  # not just security-related ones.
  #
  # Best practice: Set controlled variables in GitLab CI/CD Settings as
  # protected/masked variables, never in the YAML file.
  pipelineMustNotOverrideJobVariables:
    # Set to false to disable this control
    enabled: true

    # CI/CD variable names that must not be defined in the pipeline config.
    # They should only be set in GitLab CI/CD Settings > Variables or defined in the imported templates or components.
    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_DISABLED
      # Add your organization's controlled variables below:
      # - MY_CUSTOM_PROTECTED_VAR

  # ── Pipeline must not execute unverified scripts ─────────────────
  #
  # Detects jobs that download and immediately execute scripts from the
  # internet without integrity verification (e.g., curl | bash, wget | sh).
  #
  # This is a well-documented supply chain attack vector: an attacker who
  # compromises the remote URL can serve a modified script that exfiltrates
  # CI/CD secrets ($CI_JOB_TOKEN, deploy keys, custom variables).
  #
  # Maps to OWASP CICD-SEC-3 (Dependency Chain Abuse) and CICD-SEC-8
  # (Ungoverned Usage of 3rd Party Services).
  #
  # Best practice: download scripts to a file, verify a checksum against a
  # known-good value, then execute. Or vendor the script into your repo.
  pipelineMustNotExecuteUnverifiedScripts:
    # Set to false to disable this control
    enabled: true

    # URLs that are trusted and should not trigger findings.
    # Supports wildcards (e.g., https://internal-artifacts.example.com/*).
    trustedUrls: []
      # - https://internal-artifacts.example.com/*

  # ── Pipeline must not use Docker-in-Docker ──────────────────────
  #
  # Detects CI/CD jobs that use Docker-in-Docker (dind) services.
  # Running a Docker daemon inside a CI container on shared runners
  # in privileged mode enables container escape, lateral movement,
  # and access to secrets from other jobs on the same runner.
  #
  # This is a well-known attack vector documented in GitLab CI
  # security best practices.
  #
  # Best practice: Use Kaniko or Buildah for container image builds
  # instead of Docker-in-Docker.
  pipelineMustNotUseDockerInDocker:
    # Set to false to disable this control
    enabled: true

    # When true, also flags insecure daemon configuration
    # (DOCKER_TLS_CERTDIR="" or DOCKER_HOST tcp://...:2375)
    # in jobs that use a DinD service.
    detectInsecureDaemon: true