docs: expand Security Gates with CI/CD examples by farhanashrafdev · Pull Request #99 · OWASP/DevSecOpsGuideline

farhanashrafdev · 2026-01-13T21:40:25Z

Expand Security Gates documentation

Filled in the Security Gates stub (current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md) with practical content.

What's added

Explanation of what security gates are and why they matter
Threshold configuration examples (what to block vs warn)
Full CI/CD pipeline examples for both GitHub Actions and GitLab CI
Coverage of all gate types: secrets, SAST, SCA, container, IaC
Best practices: gradual rollout, handling false positives, emergency bypasses
Sample gate output showing what failures look like
Tools section (open-source and commercial) following the existing format

Why

The original file was just a TBD stub. Security gates are a core DevSecOps concept and the guideline needed concrete examples teams can actually use.

Checklist

Follows existing document structure
Uses - for lists (MD004)
Tools listed alphabetically with footnote
No trailing whitespace
Tested locally with markdownlint

…1-Infra-scanning directory

Ali-Yazdani · 2026-10-03T23:20:02Z

Hi @farhanashrafdev, please fix the conflict.

farhanashrafdev · 2026-10-03T23:20:58Z

Hello @Ali-Yazdani sure let me go through and fix it, thanks

…-pr-99-conflicts # Conflicts: # current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

…D040) Add blank lines around headings, lists and fences, and tag bare code fences with a language so the pre-commit CI passes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

The examples contain credential exposure, unenforced security policies, and pipeline execution failures.

Review effort: Balanced
Findings: 4 · 13

Open (17)

Enforce CodeQL findings in the security gate · New
Fail closed when evaluating malformed Checkov reports · New
Prevent raw secrets in logs and artifacts · New
Use protected approvals instead of caller-supplied identity · New
Use distinct TruffleHog base and head commits · New
Add contents and actions read permissions · New
Generate and require the Semgrep report · New
Reject high-severity dependency vulnerabilities · New
Scan project dependencies for license violations · New
Fail container scans on high vulnerabilities · New
Use the correct Checkov output filename syntax · New
Require all dependency jobs to succeed · New
Clear the TruffleHog image entrypoint · New
Build and push the image before scanning · New
Use GitLab-compatible security report schemas · New
Enforce the configured high vulnerability threshold · New
Include scanner jobs in merge request pipelines · New

What changed in this PR

Expands the DevSecOps Security Gates guidance with practical policies and CI/CD examples.

Changes:

Adds threshold policies and GitHub Actions/GitLab CI examples.
Documents rollout, exceptions, emergency bypasses, and gate results.
Expands tooling and reference resources.

File	Description
current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md	Adds security-gate policies, pipeline examples, and operational guidance.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

farhanashrafdev · 2026-10-03T23:40:25Z

@Ali-Yazdani fixed, please review :)

Address Copilot review findings in the GitHub Actions and GitLab CI examples: - remove TruffleHog base/head overrides; add contents/actions read permissions - run Semgrep explicitly, write semgrep.json and fail closed when missing - enforce zero-high policy for SCA and container gates (no silent >5 loophole) - install locked deps before pip-licenses; note CodeQL is enforced via code-scanning rulesets - fix Checkov output path, drop bogus evaluated_keys severity check, handle array/object reports - summary job fails on cancelled/skipped, not only failure - GitLab: clear TruffleHog entrypoint, use --fail instead of dumping raw secret JSON, build image before scanning, drop native-JSON reports: declarations, check HIGH threshold, apply shared rules to all gate-dependency jobs - emergency bypass now relies on protected environments instead of a caller-supplied APPROVED_BY Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

Registry authentication, license matching, and emergency-bypass execution need correction before the pipeline examples can be relied upon.

Review effort: Balanced
Findings: 3 · 1

Open (4)

Configure Kaniko registry authentication before pushing · New
Provide Trivy credentials to pull the private image · New
Allow protected bypass when security gates fail · New
Use accurate SPDX license matching to enforce policy · New

Resolved since last review (17)

Use protected approvals instead of caller-supplied identity
Prevent raw secrets in logs and artifacts
Fail closed when evaluating malformed Checkov reports
Enforce CodeQL findings in the security gate
Include scanner jobs in merge request pipelines
Enforce the configured high vulnerability threshold
Use GitLab-compatible security report schemas
Build and push the image before scanning
Clear the TruffleHog image entrypoint
Require all dependency jobs to succeed
Use the correct Checkov output filename syntax
Fail container scans on high vulnerabilities
Scan project dependencies for license violations
Reject high-severity dependency vulnerabilities
Generate and require the Semgrep report
Add contents and actions read permissions
Use distinct TruffleHog base and head commits

…e examples - Kaniko: write /kaniko/.docker/config.json from CI_REGISTRY_* before pushing - Trivy: pass TRIVY_USERNAME/TRIVY_PASSWORD so the private image can be pulled - Bypass job: needs: [build-image] so it is a DAG job that can run when gates fail - License gate: match GPL/AGPL native and SPDX names, exclude LGPL, share one filter Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

The pipeline examples still expose credentials in logs and contain configuration errors that prevent execution in supported scenarios.

Review effort: Balanced
Findings: 1 · 1

Open (2)

Prevent TruffleHog results from exposing credentials in logs · New
Align bypass rules with build-image pipeline conditions · New

Resolved since last review (4)

Allow protected bypass when security gates fail
Provide Trivy credentials to pull the private image
Configure Kaniko registry authentication before pushing
Use accurate SPDX license matching to enforce policy

Previously missed (3)

In code that hasn't changed since last review

Add pull-requests read permission for private repository scans

current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md:161

The secrets job inherits only contents: read, but Gitleaks v2 calls the pull-request commits API before scanning. That endpoint requires pull-requests: read for private repositories, so private-repository PRs fail before the scan runs, even with no secrets present. Add that permission to this job while retaining checkout access.

Pin security actions to vetted commit SHAs

current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md:171

The workflow runs TruffleHog from mutable @main, both Trivy scans from @master (lines 236 and 303), and Checkov from @master (line 342). Upstream branch changes can therefore replace code running against the repository without a reviewed workflow update, creating supply-chain risk in the security gates themselves. Pin these actions to vetted full commit SHAs, using the same Trivy pin for both scans.

Provide Gitleaks license for organization-owned repositories

current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md:179

Gitleaks Action v2 requires GITLEAKS_LICENSE for organization-owned repositories and exits before scanning when it is absent. This example supplies only the token, so organization users cannot run the pipeline even on clean commits. Document and supply the license secret, or use the standalone Gitleaks CLI instead.

…fault branch - TruffleHog: capture --json output outside the workspace and print only count + detector names (plain printer also emits Raw result) - Bypass job rule now requires CI_COMMIT_BRANCH == CI_DEFAULT_BRANCH so build-image always exists in the pipeline Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

The pipeline examples can accept incomplete scans or miss blocking findings, undermining their security-gate purpose.

Review effort: Balanced
Findings: 4

Open (4)

Unpinned security tools allow unreviewed code changes · New
Semgrep scan errors are ignored without strict mode · New
High and critical Semgrep findings bypass severity gates · New
Checkov parsing errors can leave the gate green · New

Resolved since last review (2)

Prevent TruffleHog results from exposing credentials in logs
Align bypass rules with build-image pipeline conditions

Previously missed (2)

In code that hasn't changed since last review

Gitleaks fails without a required organization license

current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md:179

Gitleaks Action requires GITLEAKS_LICENSE for organization-owned repositories. Passing only GITHUB_TOKEN makes the action fail before scanning in those repositories. Document and pass the required repository or organization secret, or use the license-free Gitleaks CLI instead.

Mixed-case repository name breaks Docker image build

current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md:305

github.repository preserves capitalization, but Docker image repository names must be lowercase. A name such as org/DevSecOpsGuideline makes this build fail before scanning. Since the image is used only within this job, use the same fixed lowercase local name for the build and Trivy scan.

+      # push or pull_request event itself. Hard-coding the default branch as
+      # base makes base == HEAD on pushes to that branch, which TruffleHog rejects.
+      - name: TruffleHog Secret Scan
+        uses: trufflesecurity/trufflehog@main


+      - name: Run Semgrep
+        run: |
+          python3 -m pip install --quiet semgrep
+          semgrep scan \


+            echo "SAST Gate ERROR: semgrep.json not produced"
+            exit 1
+          fi
+          CRITICAL=$(jq '[.results[] | select(.extra.severity == "ERROR")] | length' semgrep.json)


+          FAILED=$(jq '[.. | objects | select(has("failed_checks")) | .failed_checks[]?] | length' "$REPORT") || {
+            echo "IaC Gate ERROR: malformed Checkov report"; exit 1; }


farhanashrafdev · 2026-10-04T00:17:41Z

Its like a never ending cycle, each time its finding new bugs

Ali-Yazdani · 2026-10-04T08:51:55Z

Hi @farhanashrafdev , my suggestion is to close this and open a new one based on the head.

farhanashrafdev · 2026-10-04T09:00:32Z

Thanks @Ali-Yazdani, done - closing this in favour of #111, which is a single clean commit on top of current master with the same content (plus the #110 edits folded in and scanner actions pinned).

Supersedes #99, rebased onto current master as a single commit. Adds to 2-3-5-Security-Gates.md: - Pipeline placement diagram and severity-threshold table - Policy-as-code example (.security-gates.yaml) and gradual rollout guidance - End-to-end GitHub Actions and GitLab CI gate pipelines (secrets, SAST, SCA, container, IaC) with a single fail-closed summary gate - Sample gate output, exceptions-as-code, and an auditable emergency bypass - License gate with SPDX-aware matching - Additional tools, KPIs and references Keeps all V0.4 content and the edits from #110 (semgrep ci example, VEX link, scanner-pinning pitfall, updated references). Third-party actions in the examples are pinned to release tags. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

farhanashrafdev added 7 commits January 1, 2026 19:13

Rename 6-5-VDP|Bug-bounty.md to 6-5-VDP-Bug-bounty.md

b6571ba

RuntimeContinuous-test

41f9cff

Fix file path for image scanning documentation

71c95ae

Delete old-versions/V0.2/6-Operation/6-1-Runtime|Continuous-test/6-1-…

2fdf38d

…1-Infra-scanning directory

Merge branch 'OWASP:master' into master

b74a7c8

Add Security Gates documentation with CI/CD examples

7853329

expand security gates doc with CI/CD examples

4491c62

Merge remote-tracking branch 'origin/master' into farhanashrafdev-fix…

f42c956

…-pr-99-conflicts # Conflicts: # current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md

Copilot AI balanced review requested due to automatic review settings October 3, 2026 23:31

Copilot started reviewing on behalf of farhanashrafdev October 3, 2026 23:31 View session

farhanashrafdev and others added 2 commits October 4, 2026 04:33

docs: strip trailing whitespace in Security Gates

ff525c9

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

docs: fix markdownlint errors in current-version (MD022/MD031/MD032/M…

c8cc86e

…D040) Add blank lines around headings, lists and fences, and tag bare code fences with a language so the pre-commit CI passes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed Oct 3, 2026

View reviewed changes

farhanashrafdev requested a balanced review from Copilot October 3, 2026 23:49

Copilot started reviewing on behalf of farhanashrafdev October 3, 2026 23:49 View session

Copilot AI reviewed Oct 3, 2026

View reviewed changes

farhanashrafdev requested a balanced review from Copilot October 3, 2026 23:59

Copilot started reviewing on behalf of farhanashrafdev October 4, 2026 00:00 View session

Copilot AI reviewed Oct 4, 2026

View reviewed changes

Comment thread current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md Outdated

Comment thread current-version/2-Process/2-3-Build/2-3-5-Security-Gates.md Outdated

farhanashrafdev requested a balanced review from Copilot October 4, 2026 00:09

Copilot started reviewing on behalf of farhanashrafdev October 4, 2026 00:10 View session

Copilot AI reviewed Oct 4, 2026

View reviewed changes

farhanashrafdev mentioned this pull request Oct 4, 2026

docs: expand Security Gates with end-to-end CI/CD examples #111

Merged

farhanashrafdev closed this Oct 4, 2026

This was referenced Oct 4, 2026

CI: pre-commit runs on all files and fails fast, so unrelated lint debt blocks contributor PRs #112

Closed

ci: run pre-commit on changed files for PRs, drop fail_fast, document local setup #113

Merged

		FAILED=$(jq '[.. \| objects \| select(has("failed_checks")) \| .failed_checks[]?] \| length' "$REPORT") \|\| {
		echo "IaC Gate ERROR: malformed Checkov report"; exit 1; }

Conversation

farhanashrafdev commented Jan 13, 2026

Expand Security Gates documentation

What's added

Why

Checklist

Uh oh!

Ali-Yazdani commented Oct 3, 2026

Uh oh!

farhanashrafdev commented Oct 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

farhanashrafdev commented Oct 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

farhanashrafdev commented Oct 4, 2026

Uh oh!

Ali-Yazdani commented Oct 4, 2026

Uh oh!

farhanashrafdev commented Oct 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants