What are finding policies?

Learn about finding policies in Endor Labs and how to use them.

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 comes with several out-of-the-box findings policies for various use cases:

Create finding polices from a template or from scratch using the Open Policy Agent (OPA) Rego policy language.

Create a finding policy from a template

You can 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 a template.
  4. Choose a Policy Template from the list. The template details are prefilled 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. In Finding Tags, enter tags that you want to associate with the findings of this policy. Tags can have a maximum of 63 characters and can contain letters, numbers, and characters = @ _ -.
  7. You can assign a scope to the finding policy by specifying what projects the policy has to scan.
    • In Inclusions, enter the tags of the projects that you want to scan.
    • In Exclusions, enter the tags of the projects that you do not want to scan. Exclusions take precedence over the inclusions, in case of a conflict.
    • Click the link to view the projects included in the finding policy scan.

    Note: You can set custom tags for your projects from Projects > Settings > Custom Tags.

  8. Enter a Name and Description for your policy.
  9. Enter any Policy Tags that you want to associate with your policy.
  10. Click Create Finding Policy.

Create a finding policy from scratch

Author 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.

Define a policy

  1. 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, j
  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])
  }
}
  1. Enter the OPA Query Statement to validate the rule in the following format: data.<package-name>.<function-name>. For the example above the query statement is data.examples.match_package_version_score.
  2. Select the Resource Kinds required to evaluate the policy. For the example above the required resource kinds are PackageVersion and Metric.
  3. 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.
  4. Choose a Severity for the generated finding.
  5. Enter a short Summary of the finding.
  6. Enter an Explanation for the finding. You can include additional information or explain why this finding is important.
  7. Describe how to mitigate the finding in Remediation.
  8. Enter the Finding Name.
  9. Enter any tags that you want to associate with the finding in Finding Tags.
  10. Select one or more categories for the finding in Finding Categories.

Assign scope

  1. You can assign a scope to the finding policy by specifying what projects the policy has to scan.
    • In Inclusions, enter the tags of the projects that you want to scan.
    • In Exclusions, enter the tags of the projects that you do not want to scan. Exclusions take precedence over the inclusions, in case of a conflict.
    • Click the link to view the projects included in the finding policy scan.

    Note: You can set custom tags for your projects from Projects > Settings > Custom Tags.

Name your finding policy

  1. Enter a Name and Description for your policy.
  2. Enter any Policy Tags that you want to associate with your policy.

Create finding policy

  1. Click Create Finding Policy. Before creating the policy the UI will validate the Rego syntax and the query statement. If it fails and it is not a Rego syntax error, the most likely problem is that the query statement does not match the Rego code.
  2. Fix any errors.
  3. Click Create Finding Policy.

Available resource kinds

Every policy must specify the resource kinds it needs in order to execute the Rego logic. The following resource kinds are available.

Resource Kind API Documentation Link
Project ProjectService
Repository RepositoryService
RepositoryVersion RepositoryVersionService
PackageVersion PackageVersionService
Metric MetricService
DependencyMetadata DependencyMetadataService
LinterResult LinterResultService

Finding targets

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

  1. Repository (e.g. default branch protections)
  2. RepositoryVersion (e.g. CI/CD coverage, secrets)
  3. PackageVersion (e.g. 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.

Manage finding policies

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

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