Enforce policies in CI/CD

Use policy enforcement in your CI/CD pipeline to automatically block deployments when components violate your security standards. This guide walks through setting up build-breaking policies.

Before You Start

You have Observer CLI installed
You have policies created in SBOM Observer
Your pipeline is integrated with Observer CLI

Policy enforcement works by running observer analyze before uploading. This command exits with status code 1 if violations are found, automatically breaking your build.

Basic Enforcement

The simplest way to enforce policies is to add the analysis step to your pipeline.

Generate SBOM

Scan your code or container to create an SBOM:

observer fs -o sbom.cdx.json .

This generates a local SBOM file without uploading anything yet.

Analyze Against Policies

Run analysis to check your SBOM against all active policies:

observer analyze sbom.cdx.json

If violations are found, the command exits with status code 1, breaking your build. If no violations, it exits with status code 0.

Verify integrity (optional)

Optionally validate that the SBOM is well-formed and matches your artifacts before publishing:

observer verify sbom.cdx.json --artifacts ./dist

Use --artifacts when you want to confirm file hashes for built outputs; omit it to only validate CycloneDX structure. If verification fails, exit non-zero and stop the pipeline.

Upload on Success

Only upload to SBOM Observer if analysis passes:

observer upload sbom.cdx.json --project my-app --environment production

This keeps your workspace clean—only successful, compliant SBOMs are tracked for monitoring.

Example: Build-failing JavaScript policy

Define a JavaScript policy in SBOM Observer that fails builds when high-risk vulnerabilities are present and not covered by VEX:

// consider these VEX states as not "exploitable" and therefore not a violation
const nonExploitableVexStates = new Set([
  "not_affected",
  "false_positive",
  "resolved",
  "resolved_with_pedigree",
]);

function Policy({ component, vulnerabilities }) {
  if (vulnerabilities && vulnerabilities.length > 0) {
    return vulnerabilities
      .filter((vulnerability) => vulnerability.severity > 5)
      .filter((vulnerability) => vulnerability.epss > 0.5)
      .filter(
        (vulnerability) =>
          !vulnerability.vex ||
          !nonExploitableVexStates.has(vulnerability.vex.state),
      )
      .map((vulnerability) => ({
        severity: vulnerability.severity,
        message: `${vulnerability.vendorId} with severity > 5 (${vulnerability.severity}) and EPSS > 0.5 (${vulnerability.epss}) is not tolerated for a library`,
        action: "fail-build",
      }));
  }

  return null;
}

Platform-Specific Setup

GitHub Actions

The analyze command automatically fails the step if violations are found:

.github/workflows/sbom-observer.yml

name: SBOM Observer Policy Enforcement

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  sbom:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Download Observer CLI
        run: |
          curl -fsSL https://github.com/sbom-observer/observer-cli/releases/download/v0.1.0/observer-linux-x64 -o observer
          chmod +x observer

      - name: Generate SBOM
        run: ./observer fs -o sbom.cdx.json .

      - name: Verify SBOM
        run: ./observer verify sbom.cdx.json

      - name: Analyze SBOM against policies
        env:
          OBSERVER_TOKEN: ${{ secrets.OBSERVER_TOKEN }}
        run: ./observer analyze sbom.cdx.json

      - name: Upload SBOM to Observer
        if: success()
        env:
          OBSERVER_TOKEN: ${{ secrets.OBSERVER_TOKEN }}
        run: ./observer upload sbom.cdx.json

Result: If violations are found, the "Enforce policies" step fails, and the workflow stops. The upload only happens if enforcement passes.

Handle Policy Violations

To turn violations into failing builds, make sure all three pieces are in place:

Policy action – In SBOM Observer, set action: "fail-build" on the policy (just like the example above). Without that action, violations only warn.
Analyze flag – Run observer analyze --fail in your pipeline so the CLI exits non-zero whenever a fail-build violation is returned.
Authentication – Provide an OBSERVER_TOKEN (or equivalent auth) so the CLI can load your workspace policies during analysis.

When any step is missing, your build will continue even if violations are detected.

Best Practices for Enforcement

Fail Fast

Enforce policies early in your pipeline. The sooner you catch violations, the faster developers can fix them.

Make policies realistic - Too strict = constant broken builds. Too loose = no protection. Start permissive and tighten over time
Communicate changes - When you update policies, notify your team so they can prepare for breaking builds
Document violations - Keep a changelog of policy violations and how they were resolved
Review regularly - Audit your policies monthly to ensure they still match your security posture

Test policy changes - Before enforcing new policies, run analysis in warning mode to see what would break

Next Steps

Write policies tailored to your security requirements
Analyze impact to understand what violations mean
CI/CD Integration for platform-specific setup
Policy concepts to deepen your understanding

Enforce policies in CI/CD

On this page