Skip to content
glsecPublic

About

Static security scanner and linter for GitLab CI. Finds .gitlab-ci.yml misconfigurations, supply-chain risks, and leaked secrets. Offline, SARIF output, OWASP CICD-SEC and CWE mappings.

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

25 stars

Watchers

0 watching

Forks

Latest commit

 

History

857 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

glsec

glsec

CI/CD security: glsec GitLab CI/CD Catalog Go Reference codecov OpenSSF Scorecard OpenSSF Best Practices OpenSSF Baseline SLSA Build Level 3 agent security: cfgaudit

glsec is a security linter for .gitlab-ci.yml files. It detects misconfigurations that can lead to supply-chain attacks, secret leakage, and token exfiltration — the same class of issues that zizmor and actionlint catch in GitHub Actions, but for GitLab CI.

Website and rule reference: glsec.github.io

$ glsec .gitlab-ci.yml

error[GL001]: image "node:latest" uses mutable tag "latest" — pin to a specific version or digest
  --> .gitlab-ci.yml:7:10 (job: build)
  |
7 |   image: node:latest
  |          ^

warn[GL002]: unquoted user-controlled variable $CI_COMMIT_REF_NAME in script — value is set by commit authors and may contain shell metacharacters
  --> .gitlab-ci.yml:14:7 (job: build)
   |
14 |     - echo $CI_COMMIT_REF_NAME
   |       ^

Use --format table for a compact one-line-per-finding view when there are many findings.

Quick start

Add glsec to a GitLab pipeline with the CI/CD Catalog component:

include:
  - component: gitlab.com/glsec-io/glsec/glsec@v1.0.30

It adds a glsec job that runs in the test stage (set the stage input to change that) and fails on error findings. For findings in merge requests, Docker, binary or GitHub Actions setups, see CI integration. To run it locally, see Install.

Why glsec?

Tool Scope
zizmor GitHub Actions security
actionlint GitHub Actions syntax + some security
gitlab-ci-lint GitLab CI syntax only (requires API access)
glsec GitLab CI security — works offline, no API key needed
  • 95 rules across the OWASP Top 10 CI/CD Security Risks, each mapped to CWE: mutable images, secrets in variables, script injection, token exfiltration, unrestricted OIDC tokens, untrusted includes and more.
  • Findings where you review code: GitLab Code Quality reports in merge requests, JUnit, SARIF for GitHub Code Scanning, JSON.
  • Adoptable on existing pipelines: a baseline file and --new-only report only what a change introduces; suppressions carry a reason and an expiry date.
  • Trustworthy releases: signed, with SLSA provenance and reproducible builds (details).

Install

Package managers:

brew install glsec/tap/glsec        # Homebrew (macOS and Linux)
aqua g -i glsec/glsec && aqua i     # aqua
mise use github:glsec/glsec         # mise
pipx install glsec                  # PyPI (or: uv tool install glsec, uvx glsec)

The Homebrew tap takes each release only after its archives pass the provenance check described under Verifying a release. glsec is in the aqua standard registry from v4.578.0 on; aqua checks each download against checksums.txt and the provenance of glsec's release workflow. mise installs the release archive from GitHub. The PyPI package is a wheel per platform that carries the release binary, taken from the archive after the same checksum and provenance check; it has no Python code and downloads nothing at install time.

Go install (requires Go 1.26+):

go install github.com/glsec/glsec/cmd/glsec@latest

Binary download:

Pre-built binaries for Linux, macOS, and Windows (amd64 + arm64) are available on the Releases page.

# Example: Linux amd64. Archives are named glsec_<version>_<os>_<arch>.tar.gz (.zip on Windows).
curl -sSLO https://github.com/glsec/glsec/releases/download/v1.28.0/glsec_1.28.0_linux_amd64.tar.gz
tar xzf glsec_1.28.0_linux_amd64.tar.gz
./glsec --version

Docker:

docker run --rm -v "$PWD:/src:ro" -w /src ghcr.io/glsec/glsec:1.28.0

Without a file argument glsec scans .gitlab-ci.yml in the mounted directory.

To check the download before running it, see Verifying a release.

Usage

glsec .gitlab-ci.yml                      # scan a file: exit 1 on error findings, 0 if clean, 2 if it can't be scanned
glsec --recursive .                       # every .gitlab-ci.yml in a tree
glsec --format codeclimate .gitlab-ci.yml > gl-code-quality.json   # also json, sarif, junit, gitlab-sast, table
glsec --generate-ignore .gitlab-ci.yml    # baseline the existing findings
glsec --new-only .gitlab-ci.yml           # then fail only on new ones
glsec explain GL001                       # what a rule checks and how to fix it

Using glsec describes every flag and the rest of the command line: report formats and templates, exit codes, configuration, baselines, suppressions, scanning repositories you don't trust, the result cache, secrets in reports, and how glsec reads shell, rules: variables and anchors, !reference and includes.

Configuration file

glsec reads .glsec.yml from the working directory, or the file passed with --config. docs/glsec.example.yml shows every key, and schema/glsec.schema.json, listed in the SchemaStore catalog, gives editors completion and validation. Details: Configuration file.

Rules

95 rules across 8 OWASP CI/CD security categories:

Category OWASP Rules
Credential Hygiene CICD-SEC-6 GL004, GL005, GL006, GL010, GL014, GL018, GL021, GL027, GL029, GL032, GL033, GL035, GL036, GL037, GL038, GL040, GL052, GL059, GL062, GL066, GL068, GL070, GL073, GL088
Dependency & Image Pinning CICD-SEC-3 GL001, GL003, GL011, GL016, GL022, GL023, GL026, GL046, GL064, GL069, GL072, GL075, GL079, GL090
Component & Third-Party Integrity CICD-SEC-4, CICD-SEC-8 GL002, GL007, GL015, GL025, GL041, GL044, GL051, GL053, GL065, GL067, GL078, GL083, GL084, GL085, GL093, GL094, GL095
Supply Chain Integrity CICD-SEC-9 GL020, GL045
Pipeline Flow & Access Control CICD-SEC-1, CICD-SEC-5 GL008, GL009, GL012, GL013, GL017, GL019, GL034, GL039, GL043, GL055, GL071, GL074, GL080, GL081, GL082, GL089, GL091, GL092
Insecure Configuration CICD-SEC-7 GL024, GL028, GL030, GL031, GL042, GL047, GL048, GL049, GL050, GL054, GL056, GL057, GL058, GL060, GL061, GL063, GL076, GL077, GL086, GL087

→ Full rule reference with descriptions and examples on glsec.github.io, built from docs/rules.md at each release

Not covered: CICD-SEC-2 (Identity & Access Management) and CICD-SEC-10 (Insufficient Logging & Visibility) are not detectable from static .gitlab-ci.yml analysis — they require platform-level context such as GitLab group/project settings, audit logs, or API access.

How glsec reads YAML anchors, !reference, include: local and child pipelines: Reusable configuration.

ShellCheck integration

glsec can pass script:, before_script:, after_script:, hooks:pre_get_sources_script: and run: steps to ShellCheck for deeper shell analysis (shellcheck: {enabled: true} in .glsec.yml). See ShellCheck integration.

CI integration

include:
  - component: gitlab.com/glsec-io/glsec/glsec@v1.0.30

CI integration covers the GitLab CI/CD Catalog component, the Docker image and binary in GitLab CI, findings in merge requests through Code Quality and the vulnerability report, the pipeline inventory, what to do when someone else can push, GitHub Actions and MegaLinter. Runnable examples: gitlab.com/glsec-io/examples.

Pre-commit hook

glsec ships a pre-commit hook, as a Go build, for a binary on PATH or with Docker. See Pre-commit hook.

Claude Code plugin

glsec ships as a Claude Code plugin with a /glsec:scan command and a hook that scans .gitlab-ci.yml after each edit. See Claude Code plugin.

Verifying a release

Releases and the container image are signed through Sigstore and carry SLSA Build Level 3 provenance, and release builds are reproducible. How to check a download, the image and the checksums, and how to rebuild a release: Verifying a release.

Badge

Using glsec in your pipeline? Show it in your README:

CI/CD security: glsec

[![CI/CD security: glsec](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/glsec/glsec/main/assets/badge/v1.json)](https://github.com/glsec/glsec)

To show it on a GitLab project page, add it under Settings → General → Badges with:

  • Link: https://github.com/glsec/glsec
  • Badge image URL: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/glsec/glsec/main/assets/badge/v1.json

The badge says that a project runs glsec, not that its last pipeline passed; GitLab's own pipeline badge shows that.

Contributing

If glsec is useful to you, a GitHub star helps others find it.

See CONTRIBUTING.md. To report a bug, a false positive or a missing rule, see Reporting a bug.

How glsec works inside, what it defends against and why its design holds up, is described in ARCHITECTURE.md; who maintains it and who has access to what, in GOVERNANCE.md; how it is tested, in TESTING.md; how it works for people who use assistive technology, in ACCESSIBILITY.md; where it is heading, in ROADMAP.md; how a release is made, in RELEASING.md. Everyone taking part is expected to follow the Code of Conduct.

Repositories

glsec is developed in this repository. The GitLab integrations live on gitlab.com:

Repository Contents
github.com/glsec/glsec The scanner, its rules and documentation, releases, the container image, the pre-commit hook, the Claude Code and MegaLinter plugins
gitlab.com/glsec-io/glsec The GitLab CI/CD Catalog component (glsec and glsec-code-quality templates)
gitlab.com/glsec-io/examples/component Example: the Catalog component
gitlab.com/glsec-io/examples/component-code-quality Example: the component with Code Quality annotations in merge requests
gitlab.com/glsec-io/examples/docker Example: the container image
gitlab.com/glsec-io/examples/binary Example: the release binary

Security

To report a vulnerability in glsec, see SECURITY.md. It also documents the trust boundary, which is worth reading before filing: a missed or wrong finding is a normal bug, while glsec misbehaving on attacker-supplied input is not.

License

Apache 2.0. The repository follows the REUSE specification: every file carries or is assigned its copyright and license, and reuse lint passes.

About

Static security scanner and linter for GitLab CI. Finds .gitlab-ci.yml misconfigurations, supply-chain risks, and leaked secrets. Offline, SARIF output, OWASP CICD-SEC and CWE mappings.

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

25 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages