Policies

• 1: Finding policies
• 1.1: CI/CD tool policies
• 1.2: License policies
• 1.3: Open-source policies
• 1.4: SCPM policies
• 1.5: Secret policies
• 1.6: GitHub Action policies
• 2: Exception policies
• 2.1: Exception policy templates
• 3: Action policies
• 3.1: Action policy templates
• 4: Tag projects

1 - 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. - 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 won’t apply to that project.
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:

• Project
• Repository
• RepositoryVersion
• PackageVersion
• DependencyMetadata
• LinterResult
• Metric

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.

1.1 - CI/CD tool policies

Policy templates for CI/CD tool detection

Endor Labs provides the following finding policy templates for detecting CI/CD tool usage. See Finding Policies for details on how to create policies from policy templates.

1.2 - License policies

Policy templates for open source license detection

Endor Labs provides the following policy templates for detecting open source license usage. See Finding Policies for details on how to create policies from policy templates.

1.3 - Open-source policies

Open source risk policies generally fall into one of several categories:

• Vulnerabilities - Known vulnerabilities associated with a software component.
• Operational Risk - Issues that may make it more expensive to address any application impacting bug, including a security vulnerability.
• License Risk - Issues that may cause legal or compliance risk associated with your software.

Policies for open source risk management

Endor Labs comes with the following out-of-the-box finding policies to detect open source risks. See Finding Policies for details on how to enable or disable out-of-the-box policies.

1.4 - SCPM policies

Strong information security practices are necessary to secure your open source code used in your development and delivery infrastructure.

Policies for source code posture management

Endor Labs comes with the following out-of-the-box policies that help you determine the effectiveness of your security practices. See Finding Policies for details on how to enable, disable, or edit out-of-the-box policies.

1.5 - Secret policies

Policies for secret detection

Endor Labs comes with the following out-of-the-box finding policies to detect leaked secrets. See Finding Policies for details on how to enable, disable, or edit out-of-the-box policies.

Note: The out-of-the-box secret policies can be deleted and re-created from the corresponding policy templates. See Policy templates for secret detection below.

Policy templates for secret detection

Endor Labs provides the following finding policy templates for detecting secrets. See Finding Policies for details on how to create policies from policy templates.

1.6 - GitHub Action policies

Endor Labs provides the following out-of-the-box policies that help you assess the security posture of GitHub Actions used in your software delivery process.

• Policies for Repository Security Posture Management (RSPM) in GitHub.
• Policies for evaluating configuration settings in workflow file.

See Finding Policies for details on how to enable, disable, or edit out-of-the-box policies.

Policies for RSPM

Policies for assessing configuration settings in workflow files

2 - Exception policies

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 from the left sidebar.
2. Click on the Exception Policies tab.
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 from the left sidebar.
2. Click on the Exception Policies tab.
3. Click Create Exception Policy to create a new exception policy.
4. First, you must Define Exception Criteria. Choose a policy template and define the criteria for the exception. For more information, see exception policy templates.
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.

2.1 - Exception policy templates

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.

Standard exception finding attributes

Allows you to 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.

Custom exception finding attributes

Allows you to define where exceptions apply based on custom criteria that are less common for findings.

3 - Action policies

Action policies define the workflows that are triggered when the application encounters a given set of criteria (a.k.a. findings).

For example, action policies can be used to:

• Configure the behavior of scan in a CI/CD based environment.
• Set up custom ticketing workflows.
• Set up custom messaging workflows.

Manage action policies

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

1. Sign in to Endor Labs and select Policies from the left sidebar.
2. Click on the Action Policies tab.
3. Use the search bar to search for a policy.
4. Enable or disable a policy using the toggle.
5. Select Hide Disabled to hide policies that are not enabled.
6. Select Hide Warnings to hide policies that are not blocking or notifications.
7. To delete a policy, click the vertical three dots and select Delete Policy.
8. To edit a policy, click on the vertical three dots and select Edit Policy.

Create an action policy from template

You can create an action policy in Endor Labs to perform a given action 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 Action Policies tab.

3. Click Create Action Policy to create a new action policy.

4. First, you must Define a Policy. Choose a policy template and define the criteria for the action. For more information, see Action policy templates.

5. Next, Choose an Action to take when the policy criteria are met.

   • Choose Enforce Policy to define the behavior of endorctl scans.

     • A Warn enforcement action will warn the user when the policy criteria are met by letting them know which findings violate the policy. Warn enforcement actions will only notify users of policy violations and will still return a 0 exit code in CI/CD environments, which won’t fail a job. However, it is possible to configure the scan to return a non-zero (129) exit code for policy warnings by setting the --exit-on-policy-warning flag.
     • A Break the Build enforcement action will return a non-zero (128) exit code, which will fail the job. This action will inform the user which findings violate the policy as part of the scan.

   • Choose Send Notification to create a ticket or send a custom message to an integrated notification system.

     1. A Notification Target must be set to send a notification. A notification target may be defined as a notification integration. For more information, see Endor Labs integrations.
     2. Choose an Aggregation Type for notifications. Choosing Project triggers a single notification for all findings, while choosing Dependency creates multiple notifications categorizing them based on dependencies. For more information, see Aggregation types for notifications.

6. Assign Scope for which this action 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 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 action policy.

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

7. Name Your Action Policy.

   • Enter a human readable Name for your action policy.
   • Enter a Description for your action 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 = @ _ -.

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

9. Click Create Action Policy. The policy will be enabled by default.

Create an action policy from scratch

Write an action 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 Action Policy.

3. Choose From Scratch to author an action policy.

4. Enter the Rego rule for the policy in Rego Definition. For instance, the following Rego rule identifies all repository version findings that are not present in the baseline. Action policies should only operate on Findings. For more information about findings, see the Finding resource kind documentation.

   package examples
   
   match_baseline(finding) {
     some i
     data.baseline.Finding[i].meta.description == finding.meta.description
   }
   
   match_repo_version_finding[result] {
     some i
     data.resources.Finding[i].meta.parent_kind == "RepositoryVersion"
     not match_baseline(data.resources.Finding[i])
   
     result = {
       "Endor": {
         "Finding": data.resources.Finding[i].uuid
       }
     }
   }
   

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

6. 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>. The corresponding baseline records are available under data.baseline.<ResourceKind>. Note: Action policies should only operate on Findings.

7. See steps 5-9 above under Create an action policy from template

Expected output format

All action 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 creating the policy. However, please note that the logic cannot be fully validated without input data.

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

Aggregation types for notifications

Aggregation types for notifications streamline the organization and management of findings for efficient workflow. By default, all project findings are included in a single notification. With the option to select aggregation types, notifications can be tailored to specific criteria based on dependencies. This customization simplifies developer actions and enhances productivity.

Endor Labs enables you to choose the following notification aggregation types, each offering distinct benefits:

1. Project - (Default) Select Project to create a single notification for all project findings.
2. Dependency - Select Dependency to create separate notifications for each dependency in a project.

Example

For Jira integration notifications, a parent ticket is created with the selected issue type, either Task or Bug. The parent ticket includes the project name. Each identified dependency is grouped under a dedicated sub-ticket. The sub-ticket includes both the project name and dependency name. Findings without any dependency are grouped in a separate sub-ticket. During future scans, the existing sub-ticket status is updated or resolved. If a new dependency is found, a new sub-ticket is created.

3.1 - Action policy templates

Endor Labs provides the following action policy templates that you can use to quickly create action policies. Each policy template provides parameters to help you customize the conditions under which a policy action takes place.

Note: All action policy templates automatically only match new findings for PR scans. If the finding already exists in the baseline, then it is not considered to be a match. The assumption is that there is a baseline to compare against (see the --pr-baseline and/or --enable-pr-comments options).

Custom Finding Attributes

Allows you to define a custom action policy based on the attributes of the finding. The following parameters are supported:

Finding types

Findings are classified into the following types when the packages scanned include:

Detected Secrets

Allows you to define the action taken when a leaked secret is detected based on the validation status of the secret.

Outdated Releases

Matches findings based on older versions of software or dependencies and are not actively updated. The following parameters are supported:

Unmaintained dependencies

Matches findings based on dependencies that are no longer maintained or may have reached end-of-life. The following parameters are supported:

Unpinned direct dependencies

Matches findings based on direct dependencies that do not have a version or a range of versions specified. Supported configuration parameters for this action policy template are:

Unreachable direct dependencies

Matches findings based on dependencies that are not directly used or called within a project. Supported configuration parameters for this action policy template are:

Vulnerabilities

Matches findings that are vulnerabilities that meet specific parameters. The following parameters are supported:

4 - Tag projects

All Endor Labs policies provide the option to define inclusion and exclusion criteria based on project tags. This allows you to implement exception workflows, to onboard new teams or business units, and to set specific policies that only apply to sets of projects, such as those that are mature or the crown jewel applications of an organization.

Most organizations have projects with differing compliance and security requirements. Adopting a single standard for all projects can lead to challenges. While many controls apply equally across an environment, some controls are excessive or irrelevant for projects that don’t need to meet specific regulatory frameworks, or do not process sensitive information.

For example, an organization may want to look for leaked secrets in all repositories, but may not require a robust vulnerability management program and branch protection strategy on projects where internal documentation is developed.

The following reference tagging strategies can help organizations align their policies with their internal control needs.

Tag your projects

Tags add additional metadata to projects and help you identify them. You can also use the project tags to define the scope of a finding or an action policy for a project.

• For more details on finding policies, see Finding policies
• For more details on action polices, see Action policies

To create tags for a project:

1. Sign in to Endor Labs and select Projects from the sidebar.
2. Select a project and click Settings.
3. Type a name for the tag in Custom Tags and press Enter. Tags can have a maximum length of 63 characters and can contain letters (A-Z), numbers (0-9), and characters (=@-_).
4. Click Save Tags.
5. Use Reset Tags to make a new entry.