Guardrails

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 used at runtime. Guardrails run automatically when pull/merge requests are made to the mainline branch. They surface clear, actionable feedback in existing developer experiences (e.g. on a GitHub pull request), so developers catch and fix policy violations before code ever reaches production. Guardrails execution data, such as success rate, are made available in the Heeler so security teams can asses their effectiveness.

Key Benefits

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

• Runtime Aware: Tailor enforcement to runtime attributes—network exposure, application, or tier.

• Developer Friendly: Clear, tightly scoped guardrails helps teams avoid unnecessarily restrictive alerts.

Considerations

• 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 choose ANDing or ORing of rules but today only ANDing is supported.

• Only merges to the main branch are evaluated

  • Guardrails are only evaluated when developers create merge requests against the main branch. On the roadmap is the ability to specify branch patterns for non-main guardrail evaluation.

• Supported SCMs: GitHub and GitLab

  • Guardrails is only supported on GitHub and GitLab currently. Support for BitBucket and 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.

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

  • Notify - Indicates no corrective action is necessary and you only want to notify the developer. Good use case for Notify is the New Dependency rule, alerting the developer that they are introducing a dependency which is not used anywhere else within 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

Example GitHub Guardrail Check

Example GitLab Guardrail Check

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.