Finding policies

Learn about finding policies and how to use them.

All findings are enabled, disabled and/or customized via policies. There are three types of Finding Policies:

  1. Open-source software management - Enable or disable findings for Vulnerabilities and Malicious Packages, Outdated Dependencies, Unmaintained Dependencies, Unpinned Direct Dependencies, Unused Direct Dependencies, License Risks
  2. Repository security posture management configuration - Enable, disable, or customize out-of-the-box policies repository security posture management (RSPM)
  3. Custom - Create custom policies from scratch or from pre-defined policy templates

Manage finding policies

To view, enable, disable, edit, or delete your Endor Labs policies:

  1. Sign in to Endor Labs and select Policies from the left sidebar.
  2. Use the search bar to search for a policy.
  3. Enable or disable a policy using the toggle.
  4. Select Hide Disabled to hide policies that are not enabled.
  5. Use Finding Level to filter policies by Critical, High, Medium, or Low.
  6. To delete a policy, click the vertical three dots and select Delete Policy.
  7. To edit a policy, click on the vertical three dots and select Edit Policy.

Custom finding policies

Create custom finding policies to identify additional issues based on the needs of your organization. For example, you can create license violation policies to define the behavior for missing, unknown, problematic, or incompatible licenses. You can permit or restrict packages with certain license types.

Endor Labs provides finding policy templates for various use cases:

Create a finding policy from template

Create a finding policy from a pre-defined Endor Labs template.

  1. Sign in to Endor Labs, and select Policies from the left sidebar.
  2. Click Create Finding Policy.
  3. Choose From Template to create a finding policy from template.
  4. Choose a Policy Template from the list. The template details are pre-filled with recommended values on the form.
  5. Severity, Summary, Explanation, Remediation, Finding Name, and Finding Categories are pre-populated with Endor Labs’ recommended values. You can modify them to suit your requirements.
  6. Name Your Finding Policy.
    • Enter a human readable Name for your finding policy.
    • Enter a Description for your finding policy that describes what it does.
    • 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 = @ _ -.
  7. Advanced: When you define a policy you do so for the current namespace and all child namespaces. If you do not want the policy to be applied to any child namespaces, click Advanced and deselect Propagate this policy to all child namespaces.
  8. Click Create Finding Policy. The policy will be enabled by default.

Create a finding policy from scratch

Write a finding policy from scratch using the OPA Rego policy language.

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

  2. Click Create Finding Policy.

  3. Choose From Scratch to author a finding policy from scratch.

  4. Enter the Rego rule for the policy in Rego Definition. For instance, the following Rego rule identifies dependencies with an Endor Labs overall score lower than 7.

    package examples
    
    match_package_version_score[result] {
      some i
      data.resources.Metric[i].meta.name == "package_version_scorecard"
      data.resources.Metric[i].meta.parent_kind == "PackageVersion"
      data.resources.Metric[i].meta.parent_uuid == data.resources.PackageVersion[_].uuid
      score := data.resources.Metric[i].spec.metric_values.scorecard.score_card.overall_score
      score < 7
    
      result = {
        "Endor": {
          "PackageVersion": data.resources.Metric[i].meta.parent_uuid
        },
        "Score": sprintf("%v", [score])
      }
    }
    
  5. Enter the OPA Query Statement for the rule in the following format: data.<package-name>.<function-name>. For the example, the query statement is data.examples.match_package_version_score in the above Rego rule.

  6. Select the Resource Kinds required to evaluate the policy. For the example above the required resource kinds are PackageVersion and Metric.

  7. In Group by Fields, if applicable, list which custom output fields to group the findings by in addition to the resource UUID. Use this optional field if you want to be able to raise multiple findings against the same finding target. For example, a repository version may have multiple exposed secrets and thus there are multiple findings of the same type for the same repository version. Note that you do not need to add all (or any) custom fields here, just the ones you want to be used to group the matches by.

  8. Choose a Severity for the generated finding.

  9. Enter a short Summary of the finding.

  10. Enter an Explanation for the finding. You can include additional information or explain why this finding is important.

  11. Describe how to mitigate the finding in Remediation.

  12. Enter the Finding Name.

  13. Select one or more categories for the finding in Finding Categories.

  14. See steps 6-10 above under Create a finding policy from template

Note: The application verifies the Rego syntax and query statement before creating the policy. However, please note that the logic cannot be fully validated without input data. See also validate policy.

Available resource kinds

Every policy must specify the resource kinds it needs to execute the Rego logic. Requested resource kind objects for the current scan are made available to the Rego code under data.resources.<ResourceKind>. The following resource kinds are available:

Finding targets

Findings are raised against finding targets. Findings targets have one of three resource kinds:

  1. Repository (for example, default branch protections)
  2. RepositoryVersion (for example, CI/CD coverage, secrets)
  3. PackageVersion (for example, vulnerabilities, scores, licenses)

Individual finding target records are identified by their universally unique identifier (UUID). The finding target record is the parent of the finding record.

Note: The finding target resource kind is PackageVersion for findings in the root package as well as for findings in its dependencies. A dependency PackageVersion record may or not be in the same namespace as the root package. The relationships between the root package and its dependencies is captured by the corresponding DependencyMetadata records. All DependencyMetadata records are children of the root PackageVersion record in the same namespace as the root PackageVersion.

Expected output format

All finding policies must generate the finding payload as json data, listing the finding target resource kind and UUID under “Endor” in the following format.

foo[result] {
  <match conditions>

  result = {
    "Endor": {
      <resource-kind>: <resource-uuid>
    },
    <custom-key>: <custom-value>
  }
}
Custom output fields

Custom key-value pairs are optional. The value is treated as a single string and must be formatted accordingly. If a custom key is specified in the Group by Fields list then the value is appended to the finding name (the key is not included). Example: SSL disabled for Webhook ID #444611302, where SSL disabled for Webhook is the value of the Finding Name field and ID #444611302 is the value of a custom key. Otherwise, both the key and the value are listed at the end of the finding summary on a new line for each pair. Example: Score: 4.10.

Validate policy

See the endorctl validate policy command for details on how to validate a custom policy and inspect the matches returned for a given project.


CI/CD tool policies

Learn about the predefined finding policy templates for CI/CD tools used in your software development environment.

License policies

Learn about the predefined finding policy templates for open source license risk management.

Open-source policies

Learn about the out-of-the-box finding policies for open source risk management.

RSPM policies

Learn about the out-of-the-box finding policies for repository security posture management (RSPM).

Secret policies

Learn about the out-of-the-box finding policies and templates for secret detection.

GitHub Action policies

Learn about the out-of-the-box finding policies for GitHub Actions.