Guardrails (Pull Request Enforcement)

Overview

Guardrails let security teams define and enforce dependency-specific policies that guide developers toward approved security and hygiene choices. By harnessing Heeler’s runtime context, such as where a service is deployed, guardrail rules can be scoped to incorporate how the software is used at runtime.

Guardrails run automatically when pull or merge requests are created. By default, guardrails evaluate pull requests across all branches, though rules can also be scoped to specific branches.

Guardrails surface clear, actionable feedback directly in existing developer workflows (for example GitHub pull requests), allowing developers to catch and fix policy violations before code reaches production. Guardrail execution data, such as success rate, is available within Heeler so security teams can assess guardrail effectiveness.

Key Benefits

• Rule Chaining: AND multiple security and hygiene rules together to create meaningful security checks.

• Runtime Aware: Tailor enforcement based on runtime attributes such as network exposure, application, or tier.

• Branch-Aware Enforcement: Create different guardrail behaviors depending on the branch. For example, teams can warn developers on feature branches but block merges to the main branch.

• Developer Friendly: Clear, tightly scoped guardrails help teams avoid unnecessarily restrictive alerts while still enforcing important security requirements.

Considerations

• All commits performed within a pull (merge) request are evaluated

  • Guardrails are triggered with a new pull request and any subsequent commit made to the PR/MR is evaluated, enabling a summarization of all security findings introduced and resolved within a Pull (Merge) Requets.

• Multiple rules are ANDed together

  • When applying multiple vulnerability or hygine rules to a single guardrail, these rules are ANDed together.

  • If you want to OR rules, then please create separate Guardrails.

  • On the roadmap is the ability to OR rules.

• Supported SCMs: GitHub, GitLab, and BitBucket

  • Guardrails is only supported on GitHub, GitLab, and BitBucket currently. Support for Azure DevOps is on the roadmap.

Product Experience

Guardrails Listing

Guardrails are created and managed from the main menu. From the Guardrails tab you can view all guardrails created along with their execution history

You are able to edit, delete, and view guardrails using the action on the right side of the table. The drawer allows you to quickly inspect any guardrail violations at the global level.

Creating a Guardrail

When creating guardrails the following fields are required:

• Name - You can name the guardrail anything you want but we recommend a useful name that allows you to quickly identify what the guardrail enforces.

• Type - Currently only Dependency guardrails are available. On the roadmap are additional guardrails relating to APIs.

• Rules - You are able to create rules for vulnerabilities or hygiene. When adding multiple rules, the rules are ANDed together, so only situations that match all rules will trigger the guardrail violation.

  • Vulnerability - Evaluate dependencies to determine if there is any known vulnerability within scope of the rule(s). We highly recommend that for any warn or block guardrail, that you add the Fix Version Available rule so developers are not alerted or blocked on issues that have no remediation available.

  • Hygiene - Evaluate dependencies to determine if any specific dependency violates the rule(s). Some of the hygiene rules are based off of the OSSF Scorecard. For more details on the definition or score of these rules please see: https://github.com/ossf/scorecard/blob/main/docs/checks.md

    • Compromised Package: Heeler leverages the OSSF Malicious Packages data set to identified compromised packages.

• Scope - Defines which repositories will be evaluated by the Guardrail.

  • Global - The guardrail will be evaluated for all repositories.

  • Repository - The guardrail will be evaluated for only the repositories defined.

  • Service Runtime Context - The guardrail will be evaluated for repositories which map to the runtime scope defined.

  • Branch - By default, guardrails run against all branches. Branch scoping allows teams to define different guardrail behaviors depending on where code changes are being made. Options for the Scope:

    • All

    • Default Branch

    • All Except Main Branch

    For example:

    • Developer branches → Warn developers about issues

    • Main branch → Block merges until issues are resolved

  • This approach ensures developers receive early feedback while still enforcing strong security requirements before code reaches the primary branch.

• Action - Defines the level of alert sent to the developer when the guardrail is violated. Guardrails run as pull request or merge request check.

  • Observe - Enables observation of a guardrail without commenting or blocking the pull request. Observe guardrails are great for evaluating how well a guardrail is followed prior to rolling it out across the organization.

  • Warn - Indicates the developer should implement a corrective action but is not required to do so.

  • Block - Indicates the developer must implement a corrective action to successfully merge.

    • GitHub - To enable blocking on GitHub pull requests, you must configure branch protection, see https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.

    • GitLab - To enable blocking on GitLab merge requests, you must enable external status checks, see https://docs.gitlab.com/user/project/merge_requests/status_checks/#block-merges-of-merge-requests-unless-all-status-checks-have-passed

    • BitBucket - To enable blocking on BitBucket pull requests, you must enable Branch restrictions, see https://support.atlassian.com/bitbucket-cloud/docs/pull-request-and-merge-settings/

Example GitHub Guardrail Check

Example GitLab Guardrail Check

Example BitBucket Guardrail Check

View Pull Requests

The Pull Requests page in Guardrails allows you to view all Pull Requests across your environment and drill into individual PRs for more details.

This page also provides visibility into the guardrail status for each Pull Request, including the number of violations identified and how many of those violations have been resolved.

The Pull Request listing includes the following columns:

• PR – Link to the Pull Request in your SCM

• Opened – Date the Pull Request was created

• Repository – Repository where the PR originated

• Contributor – Author of the Pull Request

• Feature Branch – Source branch for the PR

• Base Branch – Target branch for the merge

• Status – Current status of the Pull Request

• Violations – Total guardrail violations identified in the PR

• Resolved Violations – Number of violations that have been resolved

View Guardrail Violations

You can view all violations across the environment and drill into specific violation instances from the Violations section of Guardrails.

View Guardrail Executions

You can view guardrail executions at the global level or under a specific code root. To view executions linked to a specific Code Root go to the Catalog -> Code and select the code root you will to view.