Find the security scanners in your CI that can never fail a build.
Rules · Install · GitHub Action · GitLab CI · Suppressions
CI pipelines run security scanners such as Trivy, Semgrep, Gitleaks, Bandit and Checkov, but to keep a build green someone adds || true, continue-on-error: true, allow_failure: true, --exit-zero, --soft-fail, exit-code: 0, or disables the job. The scanner still runs and still prints findings, so everyone believes the gate protects them, but it can never fail a build.
# Before: both scans run, neither can fail the build
- run: trivy image --exit-code 1 myapp:latest || true
- uses: anchore/scan-action@v6
with: { image: myapp:latest, fail-build: false }
# After: a finding fails the job
- run: trivy image --exit-code 1 myapp:latest
- uses: anchore/scan-action@v6
with: { image: myapp:latest }gatelint reads GitHub Actions workflows, composite actions and GitLab CI configuration, finds every scanner invocation, and reports the ones that cannot gate, with the exact file, line, the reason, and the fix. It knows each scanner's flags and actions (for example, that Trivy exits 0 unless --exit-code is set, that semgrep ci gates while semgrep scan does not, and that Grype fails with exit code 2), and it parses shell scripts into a syntax tree instead of matching text, so echo "trivy failed" || true is not a finding but trivy fs . && echo ok in the middle of a script is.
go install github.com/codewithQasimAli/gatelint/cmd/gatelint@latestTagged releases are built by GoReleaser and publish archives for Linux, macOS and Windows on amd64 and arm64, with a checksums.txt file, on the releases page.
To build and run the container image locally:
docker build -t gatelint .docker run --rm -v "$PWD:/work:ro" gatelint scan .Run it at the root of a repository:
gatelint scanIt finds .github/workflows/*.yml, action.yml files and .gitlab-ci.yml (plus its local includes) on its own, prints the findings and a gate coverage summary, and exits 1 if there are high-severity findings. To see every rule:
gatelint rulesThis is the output of a real run on testdata/example/.github/workflows/security.yml; a test keeps this block in sync with the binary.
$ gatelint scan testdata/example
SEVERITY RULE LOCATION JOB / STEP MESSAGE
HIGH GL001 testdata/example/.github/workflows/security.yml:11 scan / Dependency audit npm audit failure is swallowed by `|| true`
fix: remove the "|| true" (or equivalent) so a failing scan fails the job
MEDIUM GL007 testdata/example/.github/workflows/security.yml:14 scan / Container scan aquasecurity/trivy-action@0.28.0 exits 0 when it finds issues and no gating option is set
fix: set exit-code: '1' on the step so findings fail the build
HIGH GL004 testdata/example/.github/workflows/security.yml:20 scan / SAST Semgrep runs in a step with continue-on-error: true, so a failing scan does not fail the workflow
fix: remove continue-on-error, or move non-blocking experiments to a separate job
Gate coverage
testdata/example/.github/workflows/security.yml
npm audit scan / Dependency audit line 11 neutered (GL001)
Trivy scan / Container scan line 14 non-gating (GL007)
trivy-action exits 0 on findings unless exit-code is set to a non-zero value
Semgrep scan / SAST line 19 neutered (GL004)
Gitleaks scan / Secrets line 23 gating
Summary: 3 findings (2 high, 1 medium, 0 low, 0 info), 0 suppressed; 4 scanners in 1 file: 1 gating, 2 neutered, 1 non-gating
name: gatelint
on: [push, pull_request]
permissions:
contents: read
jobs:
gatelint:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: codewithQasimAli/gatelint@v0.1.0
with:
fail-on: high # high, medium, low or none
format: sarif # sarif, json, codequality or table
sarif-file: gatelint.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: gatelint.sarifInputs: path (default .), fail-on (default high), format (default sarif), sarif-file (default gatelint.sarif), version (default latest). The action installs gatelint with go install, writes the report, then runs a second time to fail the step according to fail-on. Pin the action to a commit SHA in your own workflows.
Include the template and the findings appear in the merge request's Code Quality widget:
include:
- remote: https://raw.githubusercontent.com/codewithQasimAli/gatelint/main/templates/gatelint.gitlab-ci.yml
gatelint:
variables:
GATELINT_FAIL_ON: highThe job publishes gl-code-quality-report.json as artifacts:reports:codequality. Variables: GATELINT_VERSION, GATELINT_PATH, GATELINT_FAIL_ON, GATELINT_REPORT.
| ID | Severity | Platforms | Title |
|---|---|---|---|
| GL001 | HIGH | GitHub, GitLab | Scanner failure swallowed by the shell (|| true, || echo, !, && mid-script, $(...), &) |
| GL002 | HIGH | GitHub, GitLab | errexit disabled before a scanner (set +e, shell without -e) |
| GL003 | MEDIUM | GitHub, GitLab | Scanner piped without pipefail |
| GL004 | HIGH | GitHub | continue-on-error on a scanner step or job (MEDIUM when it is an expression) |
| GL005 | HIGH | GitLab | Scanner job allowed to fail (allow_failure, matching exit_codes, after_script) |
| GL006 | HIGH | GitHub, GitLab | Neutering flag on the scanner command line (--exit-zero, --soft-fail, --exit-code 0, ...) |
| GL007 | MEDIUM | GitHub, GitLab | Scanner does not gate by default and no gating option is set |
| GL008 | HIGH | GitHub | Neutering input on a scanner action (exit-code: '0', fail-build: false, soft_fail: true, ...) |
| GL009 | HIGH | GitHub, GitLab | Scanner disabled (if: false, when: never, when: manual, *_DISABLED variables) |
| GL010 | LOW | GitHub, GitLab | Suppression without a reason |
Scanners in the built-in catalog: Bandit, Trivy, Grype, Semgrep, Gitleaks, Checkov, tfsec, npm/pnpm/yarn audit, pip-audit, Snyk, CodeQL, gosec, TruffleHog, gatelint itself, and the GitLab SAST, IaC, Secret Detection, Dependency Scanning, Container Scanning and DAST templates. They are recognised when run directly, through python -m, pipx run, uvx, poetry run, npx and similar runners, through docker run <image>, through wrappers such as sudo, env and timeout, and through their GitHub Actions. Add your own scanners in .gatelint.yml (see CONTRIBUTING.md).
When a neutered scanner only produces a report while something else gates (the same scanner also runs in gating mode, a later command fails on the report file, or the report is uploaded to code scanning or published as a GitLab security report), gatelint lowers the severity and says why.
Below the findings, gatelint lists every scanner it found in each file with one of these statuses:
| Status | Meaning |
|---|---|
gating |
A finding fails the build. |
neutered |
The scanner would gate, but the listed rules show why it cannot. |
non-gating |
The scanner does not fail builds by default (Trivy without --exit-code, snyk monitor, CodeQL, GitLab security templates). |
disabled |
The scanner never runs automatically. |
unknown |
Gating depends on something gatelint cannot see: a config file, an expression or an unresolved variable. |
The summary is also included in the JSON report under coverage, so you can track how many of your scanners actually gate.
Suppress a finding on the same line, or on the line directly above, with the rule IDs and a reason of at least 10 characters:
- name: Nightly report
# gatelint:ignore GL004 nightly dashboard only; the PR gate is in ci.yml
continue-on-error: true
run: semgrep ciSeparate several IDs with commas (GL001,GL003). A suppression without a reason does not suppress anything and is reported as GL010. Suppressed findings stay in JSON and SARIF output, marked as suppressed with the reason, so they remain auditable; the table and Code Quality reports leave them out.
An optional .gatelint.yml in the scanned directory (or --config FILE):
fail-on: medium # default for --fail-on
disable-rules: [GL003]
exclude: [legacy/**]
scanners: # add or override catalog entries
- id: inhouse-scanner
name: In-house scanner
commands: [inhouse-scan]
modes:
- gates-by-default: true
settings:
- names: [--report-only]
neuter-when: set
description: never exits non-zerogatelint scan [paths...] scan files and directories (default ".")
--format table|json|sarif|codequality (default table)
--output FILE write the report to a file
--fail-on high|medium|low|none (default high)
--platform auto|github|gitlab (default auto)
--config FILE configuration file
--no-color disable colours (NO_COLOR is honoured too)
--quiet table format: findings only
gatelint rules [ID] list rules, or describe one
gatelint version print version, commit and build date
| Code | Meaning |
|---|---|
| 0 | No unsuppressed findings at or above --fail-on. |
| 1 | At least one unsuppressed finding at or above --fail-on. |
| 2 | Usage error, unreadable path, or a YAML file that could not be parsed. |
| Capability | General CI security linters | gatelint |
|---|---|---|
| Knows which flags and inputs neuter each scanner, and which scanners do not gate by default | Rarely; usually a short list of patterns | Per-tool catalog with modes, environment variables and action inputs, extendable in config |
Detects || true and similar |
Text patterns, often on any command | Shell syntax tree; only when the swallowed command is a scanner |
Shell semantics: errexit, && lists, pipefail defaults, $(...), bash -c |
No | Yes, including GitHub's per-shell defaults |
| GitHub Actions and GitLab CI | Usually one platform | Both, including composite actions, reusable workflows, includes, extends: and !reference |
| Gate coverage summary per file | No | Yes |
| Report-only scans next to a real gate | Reported at full severity | Recognised and lowered, with an explanation |
| Suppressions | Often allowed without explanation | Reason required, kept visible in JSON and SARIF |
General-purpose CI linters cover many more topics (permissions, injection, pinning); gatelint does one thing in depth and works well alongside them.
- Resolve GitHub
matrix:values to evaluate conditionalcontinue-on-error. - Read scanner configuration files (
trivy.yaml,.grype.yaml,.checkov.yaml) instead of reportingunknown. - More scanners in the catalog (govulncheck, osv-scanner, zizmor, dependency-review-action, Brakeman, bundler-audit, cargo audit).
- Azure Pipelines, Bitbucket Pipelines and CircleCI.
- Follow remote GitLab includes and reusable workflows when given a token.
Apache License 2.0. See LICENSE.