Finding policies

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. Source code management system configuration - Enable, disable, or customize out-of-the-box policies source code posture management (SCPM)
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:

• CI/CD tool management
• License management
• Secret detection

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.

   Note

   To ensure your modifications persist after upgrades, you must disable Enable Automatic Policy Updates from Endor Labs under Settings > Policy Settings. See also Configure system settings.
6. In Finding Meta Tags, enter tags that you want to associate with the findings of this policy. Meta tags can have a maximum of 63 characters and can contain letters, numbers, and characters = @ _ -. Note that these are different and separate from the system defined finding tags.
7. You can Assign 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. See also Tagging projects.
     • If your policy has both include and exclude tags, and a project matches both, the exclude tag takes precedence, and the policy will not apply to that project.
8. 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 = @ _ -.
9. 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.
10. 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, 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])
     }
   }
   

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

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: Before creating the policy, the application verifies the Rego syntax and query statement. If validation fails and it’s not due to Rego syntax, the probable issue is that the query statement doesn’t match the Rego code. See also validate 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. Requested resource kind records for the current scan are made available to the Rego code under data.resources.<ResourceKind>.

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.

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.