This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Exception policies

Learn about exception policies and how to use them.

Exception policies define the conditions for applying an exception to a finding. When an exception is applied to a finding, it is tracked as an exception and action policies do not apply to it. Findings with exceptions are filtered out from Endor Labs reports by default.

For example, exception policies can be used to:

  • Exclude a specific finding for a specific package from build breaking policies.
  • Exclude specific vulnerabilities that are accepted across your organization.
  • Mark an identified issue as a false positive.

Manage exception policies

You can view, enable, clone, disable, edit, or delete your Endor Labs exception policies.

  1. Sign in to Endor Labs, and select Policies & Rules from the left sidebar.
  2. Select Exception Policies.
  3. Use the search bar to search for a policy or click Create Exception Policy.
  4. Enable or disable a policy using the toggle.
  5. To delete a policy, click the vertical three dots and select Delete Policy.
  6. To edit a policy, click on the vertical three dots and select Edit Policy.

Create an exception policy from a template

You can create an exception policy in Endor Labs to apply an exception to a finding when a given set of conditions are met.

  1. Sign in to Endor Labs, and select Policies & Rules from the left sidebar.

  2. Select Exception Policies.

  3. Click Create Exception Policy.

  4. In Define Exception Criteria, choose a policy template and define the criteria for the exception.

    See exception policy templates to choose a template and define the criteria for the exception.

  5. Next, you must Choose a Reason for your exception and set an expiration time for the exception.

    • Select from the following reasons why you are applying this exception:
      • In Triage: The finding is still being triaged for more information.
      • False Positive: The finding is a false positive.
      • Risk Accepted: The risk associated with the finding is accepted.
      • Other: Another reason applies for this exception.
    • Select when the exception should expire. Options include 30, 60, 90 days, or Never.
  6. Assign Scope for which this exception policy should apply. Scopes are defined by the tags assigned to a project.

    • In Inclusions, enter the tags of the projects that you want to apply an exception to.
    • In Exclusions, enter the tags of the projects that you do not want to apply an exception to. Exclusions take precedence over the inclusions, in case of a conflict.
    • Click the link to view the projects included in the finding policy.
    • See Tagging projects for more information about creating project tags.
  7. Finally, you must Name Your Exception Policy.

    • Enter a human-readable Name for your exception policy.
    • Enter a Description for your exception policy that explains its function.
    • Enter any Policy Tags that you want to associate with your policy. Tags can have a maximum of 63 characters and can contain letters, numbers, and characters = @ _ -.
  8. Advanced: When you define a policy, it applies to the current namespace and all its child namespaces. To prevent the policy from being applied to any child namespace, click Advanced and deselect Propagate this policy to all child namespaces.

  9. Click Create Exception Policy. The policy is enabled by default.

Create an exception policy from scratch

Write an exception policy from scratch using the OPA Rego policy language.

You can create an exception policy in Endor Labs to apply an exception to a finding when a given set of conditions are met.

  1. Sign in to Endor Labs, and select Policies from the left sidebar.

  2. Click on the Exception Policies tab.

  3. Click Create Exception Policy to create a new exception policy

  4. First, choose From Scratch to author an exception policy under Define Exception Criteria.

  5. Next, you must Choose a Reason for your exception and set an expiration time for the exception.

    • Select from the following reasons why you are applying this exception:
      • In Triage: The finding is still being triaged for more information.
      • False Positive: The finding is a false positive.
      • Risk Accepted: The risk associated with the finding is accepted.
      • Other: Another reason applies for this exception.
    • Select when the exception should expire. Options include 30, 60, 90 days, or Never.
  6. Enter the Rego rule for the policy in Rego Definition. For example, the following Rego rule recognizes a set of 3 vulnerabilities acknowledged by an organization, with an organization-wide exception. For more information about findings, see the Finding resource kind documentation.

    package exceptions
    
    match_vuln_id(finding, ids) {
      finding.spec.finding_metadata.vulnerability.meta.name = ids[_]
    }
    
    match_vuln_id(finding, ids) {
      finding.spec.finding_metadata.vulnerability.spec.aliases[_] = ids[_]
    }
    
    match_finding[result] {
      some i
      ids := ["CVE-2020-10683", "CVE-2019-0231", "CVE-2017-0144"]
      match_vuln_id(data.resources.Finding[i], ids)
      result = {
        "Endor" : {
          "Finding" : data.resources.Finding[i].uuid
        }
      }
    }
    
  7. Enter the OPA Query Statement for the rule in the following format: data.<package-name>.<function-name>. For the example above the query statement is data.exceptions.match_finding.

  8. Select the Resource Kinds required to evaluate the policy. For the example above, the required resource kind is Finding. The requested resource kind records for the current scan are made available to the Rego code under data.resources.<ResourceKind>.

  9. Assign Scope for which this exception policy should apply. Scopes are defined by the tags assigned to a project.

    • In Inclusions, enter the tags of the projects that you want to apply an exception to.
    • In Exclusions, enter the tags of the projects that you do not want to apply an exception to. Exclusions take precedence over the inclusions, in case of a conflict.
    • Click the link to view the projects included in the exception policy.
    • See Tagging projects for more information about creating project tags.
  10. Finally, you must Name Your Exception Policy.

    • Enter a human-readable Name for your exception policy.
    • Enter a Description for your exception policy that explains its function.
    • Enter any Policy Tags that you want to associate with your policy. Tags can have a maximum of 63 characters and can contain letters, numbers, and characters = @ _ -.
  11. Advanced: When you define a policy, it applies to the current namespace and all its child namespaces. To prevent the policy from being applied to any child namespace, click Advanced and deselect Propagate this policy to all child namespaces.

  12. Click Create Exception Policy. The policy is enabled by default.

Expected output format

All exception policies must list the matching Finding UUID under “Endor” in the following format.

foo[result] {
  <match conditions>

  result = {
    "Endor": {
      Finding: <finding-uuid>
    }
  }
}

Validate policy

The application verifies the Rego syntax and query statement before generating the policy. However, it is important to note that the logic cannot be completely validated without input data.

See the endorctl validate policy command for instructions on validating a custom policy and inspecting the matches returned for a specific project.

1 - Exception policy templates

Learn about the predefined exception policy templates and how to customize them.

Endor Labs provides the following exception policy templates that you can use to quickly create exception policies. Each exception policy template provides parameters to help you customize the conditions under which an exception is applied.

Common

Define exceptions for common use cases such as:

  • Exclude a specific finding, for a specific package, for a specific dependency.
  • Exclude all findings for a specific dependency.
  • Exclude all findings for a specific package.
  • Exclude all vulnerabilities that do not have a patch available.

The following table describes the parameters for the common exception policy template.

Parameter Description
Vulnerability ID The vulnerability identifier. For example, CVE-2024-3727 or GHSA-qh2h-chj9-jffq (case insensitive).
Finding Name Match full or partial finding name.
Dependency Name Match full or partial dependency name.
Package Name Match full or partial package name. Do not specify a package version if you want the exception to apply to multiple versions of the package.
Fix Availability Select Fix Not Available to apply the exception if a patch is not available for the dependency.

Custom

Define exceptions based on custom criteria that are less common for findings. For example, you can exclude all findings generated based on approximate scans for a specific ecosystem.

The following table describes the parameters for the custom exception policy template.

Parameter Description
Vulnerability ID The vulnerability identifier. For example, CVE-2024-3727 or GHSA-qh2h-chj9-jffq (case insensitive).
Finding Name Match full or partial finding name.
Dependency Name Match full or partial dependency name.
Package Name Match full or partial package name. Do not specify a package version here if you want the exception to apply to multiple versions of the package.
Fix Availability Select Fix Not Available to apply the exception if a patch is not available for the dependency.
Category Match finding category.
Type Match finding type.
Severity Match finding severity.
Relationship Select Direct Dependency to only match findings for direct dependencies, or Transitive Dependency to only match findings for transitive dependencies.
Dependency Reachability Match findings based on the reachability of the vulnerable dependency.

Select Unreachable Dependency to match findings where the vulnerable dependency is not reachable, Reachable Dependency to match findings where the vulnerable dependency is reachable, and Potentially Reachable Dependency to match findings where the vulnerable dependency is potentially reachable.

You can choose any combination of these options. Be aware that the more options you select, the more exceptions you will create. This might result in the exclusion of important findings.

Function Reachability Match findings based on the reachability of the vulnerable function.

Select Unreachable Function to match findings where the vulnerable function is not reachable, Reachable Function to match findings where the vulnerable function is reachable, and Potentially Reachable Function to match findings where the vulnerable function is potentially reachable.

Be aware that the more options you select, the more exceptions you will create. This might result in the exclusion of important findings.

Ecosystem Match finding ecosystem.
Custom Tag Apply exceptions to findings with this meta tag, set by the policy that generated the finding or with the --finding-tags CLI option. These tags are different and separate from the system-defined finding tags.
File Path Only match findings for dependencies or files that match this glob style file pattern. For example, src/golang/**.
Dependency Scope Match findings based on the scope of the dependency.

Select Normal to match findings generated for dependencies essential for the primary operation of the application, and used in a production environment.

Select Test to match findings for dependencies required for testing purposes, such as testing frameworks and libraries not used in a production environment.

You can choose either option or both.

Approximate Dependency Select Yes to match findings that have been generated based on approximate scans.

SAST

Define exceptions for SAST findings.

Parameter Description
Rule Name Full name of the rule. For example, Insecure cookie-based authentication (case insensitive).
SAST Tag Only match findings with this SAST tag. For example, A02:2021 or OWASP-Top-10 (case insensitive).
Custom Tag Only match findings with this meta tag, set by the policy that generated the finding or with the --finding-tags CLI option. These tags are different and separate from the system-defined finding tags.
File Path Only match findings for files that match this glob style file pattern. For example, src/golang/**.