Action policies

Learn about action policies and how to use them.

1: Action policy templates

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.

Sign in to Endor Labs and select Policies from the left sidebar.
Click on the Action Policies tab.
Use the search bar to search for a policy.
Enable or disable a policy using the toggle.
Select Hide Disabled to hide policies that are not enabled.
Select Hide Warnings to hide policies that are not blocking or notifications.
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.

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.

Sign in to Endor Labs, and select Policies from the left sidebar.
Click on the Action Policies tab.
Click Create Action Policy to create a new action policy.
First, you must Define a Policy. Choose a policy template and define the criteria for the action. For more information, see Action policy templates.
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 will not 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.
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 finding policy.
Note: You can set custom tags for your projects from Projects > Settings > Custom Tags. See also Tagging projects.
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 = @ _ -.
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.
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.

Sign in to Endor Labs, and select Policies from the left sidebar.
Click Create Action Policy.
Choose From Scratch to author an action policy.

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.

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
    }
  }
}

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

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:

Project - (Default) Select Project to create a single notification for all project findings.
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.

1 - Action policy templates

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

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. I.e. if the finding already exists in the baseline, then it is not considered to be a match. This of course assumes 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:

Parameter	Description
Finding Name Contains	Specify full or partial, case insensitive, finding name to match for this policy.
Finding Category	Violate this policy only for a specific category of finding.
Finding Type	Violate this policy only for a specific type of finding. See Finding types.
Severity	Violate this policy only for specific finding severities.
Fix Availability	Only violate this policy if a patch is available in the upstream dependency.
Dependency Reachability	Only violate this policy on findings where a vulnerable dependency is reachable.
Function Reachability	Only violate this policy on findings where the vulnerable function of a vulnerable dependency is reachable.
Exclude Test	Exclude test dependencies from this policy.
Source Code Ecosystem	Define a specific ecosystem for which an action policy should apply.
Finding Meta Tag	Only match findings that have this meta tag (set by the policy that created the finding). Note that these are different and separate from the system-defined finding tags.
Exclude if Dependency Name Contains	Allows you to define full or partial, case-insensitive, dependency names for which an action policy should exclude. For example, you want to exclude a specific dependency from this policy.
Exclude if Package Name Contains	Allows you to define full or partial, case-insensitive, package names for which an action policy should exclude. This is the resource that the finding is raised against. For example, the package indirectly or directly includes an unmaintained dependency.
Exclude findings for transitive dependencies	Exclude findings for transitive dependencies that can only be reached via other projects. This helps your team to not take action when they do not have control of findings introduced by libraries your team developed.
Include CI/CD dependency findings	Select Yes to include findings related to CI/CD dependencies. Note that CI/CD dependency findings are different from CI/CD tool findings. CI/CD dependency findings are for vulnerabilities in CI/CD dependency versions, while CI/CD tool findings are for the usage of a given tool. Findings related to CI/CD tools are included by default.

Finding types

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

Finding Type	Description
Custom	Custom findings defined in custom policies.
Dependency With Low Activity Score	Low Endor activity score.
Dependency With Low Popularity Score	Low Endor popularity score.
Dependency With Low Quality Score	Low Endor quality score.
Dependency With Multiple Low Scores	More than one Low Endor Score.
Dependency With Very Low Activity Scores	Very low Endor activity score.
Dependency With Very Low Popularity Score	Very low Endor popularity score.
Dependency With Very Low Quality Score	Very low Endor quality score.
License Risk	Missing, unknown, restricted, or problematic licenses.
Malware Dependency	Known malicious dependencies reported by Open Source Vulnerabilities (OSV).
Malware OSS Review	Potentially suspicious code that needs review.
Missing Source Code	Associated source code is not auditable.
Outdated Dependency	Outdated code with older versions of the released dependencies.
Typosquatted Dependency	Dependencies with intentionally similar names to popular packages.
Unmaintained Dependency	Unmaintained dependencies introducing vulnerabilities.
Unpinned Dependency	Variable version specifications of dependencies.
Unused Dependency	Unused dependencies in the code.

Detected Secrets

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

Parameter	Description
Validation Status	Secret validation status: Valid, Invalid, or Unable to Validate.

Outdated Releases

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

Parameter	Description
Dependency Reachability	Only violate this policy on findings where a vulnerable dependency is reachable.
Relationship	Allows you to exclude a direct or transitive dependency.
Exclude if Dependency Name Contains	Allows you to define full or partial, case-insensitive, dependency names for which an action policy should exclude. For example, you want to exclude a specific dependency from this policy.
Exclude if Package Name Contains	Allows you to define full or partial, case-insensitive, package names for which an action policy should exclude. This is the resource that the finding is raised against.
Exclude findings for transitive dependencies via other projects?	Exclude findings for transitive dependencies that can only be reached via other projects. This helps your team to not take action when they do not have control of findings introduced by libraries your team developed.
Exclude Test	Exclude test dependencies from this policy.
Source Code Ecosystem	Define a specific ecosystem for which an action policy should apply.

Unmaintained dependencies

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

Parameter	Description
Dependency Reachability	Only violate this policy on findings where a vulnerable dependency is reachable.
Relationship	Allows you to exclude a direct or transitive dependency.
Exclude if Dependency Name Contains	Allows you to define full or partial, case-insensitive, dependency names for which an action policy should exclude. For example, you want to exclude a specific dependency from this policy.
Exclude if Package Name Contains	Allows you to define full or partial, case-insensitive, package names for which an action policy should exclude. This is the resource that the finding is raised against.
Exclude findings for transitive dependencies via other projects?	Exclude findings for transitive dependencies that can only be reached via other projects. This helps your team to not take action when they do not have control of findings introduced by libraries your team developed.
Exclude Test	Exclude test dependencies from this policy.
Source Code Ecosystem	Define a specific ecosystem for which an action policy should apply.

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:

Parameter	Description
Exclude if Dependency Name Contains	Allows you to define full or partial, case-insensitive, dependency names for which an action policy should exclude. For example, you want to exclude a specific dependency from this policy.
Exclude if Package Name Contains	Allows you to define full or partial, case-insensitive, package names for which an action policy should exclude. This is the resource that the finding is raised against.
Exclude findings for transitive dependencies via other projects?	Exclude findings for transitive dependencies that can only be reached via other projects. This helps your team to not take action when they do not have control of findings introduced by libraries your team developed.
Exclude Test	Exclude test dependencies from this policy.
Source Code Ecosystem	Define a specific ecosystem for which an action policy should apply.

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:

Parameter	Description
Exclude if Dependency Name Contains	Allows you to define full or partial, case-insensitive, dependency names for which an action policy should exclude. For example, you want to exclude a specific dependency from this policy.
Exclude if Package Name Contains	Allows you to define full or partial, case-insensitive, package names for which an action policy should exclude. This is the resource that the finding is raised against.
Exclude findings for transitive dependencies via other projects?	Exclude findings for transitive dependencies that can only be reached via other projects. This helps your team to not take action when they do not have control of findings introduced by libraries your team developed.
Exclude Test	Exclude test dependencies from this policy.
Source Code Ecosystem	Define a specific ecosystem for which an action policy should apply.

Vulnerabilities

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

Parameter	Description
Dependency Reachability	Only violate this policy on findings where a vulnerable dependency is reachable.
Relationship	Allows you to exclude a direct or transitive dependency.
Exclude if Dependency Name Contains	Allows you to define full or partial, case-insensitive, dependency names for which an action policy should exclude. For example, you want to exclude a specific dependency from this policy.
Exclude if Package Name Contains	Allows you to define full or partial, case-insensitive, package names for which an action policy should exclude. This is the resource that the finding is raised against.
Exclude findings for transitive dependencies via other projects?	Exclude findings for transitive dependencies that can only be reached via other projects. This helps your team to not take action when they do not have control of findings introduced by libraries your team developed.
Exclude Test	Exclude test dependencies from this policy.
Source Code Ecosystem	Define a specific ecosystem for which an action policy should apply.
Severity	Violate this policy only for specific finding severities.
Fix Availability	Only violate this policy if a patch is available in the upstream dependency.
Function Reachability	Only violate this policy on findings where the vulnerable function of a vulnerable dependency is reachable.
EPSS Probability Threshold	Only match findings with an EPSS probability score equal to or higher than this threshold (0.00-1.00). The EPSS probability score represents the probability [0-1] of exploitation in the wild in the next 30 days following score publication.
EPSS Percentile Threshold	Only match findings with an EPSS percentile threshold equal to or higher than this threshold (0.00-100.00). The EPSS percentile threshold represents the percentile ranking among all vulnerabilities that a vulnerability will be exploited.
Include CI/CD dependency findings	Select Yes to include findings related to CI/CD dependencies. Note that CI/CD dependency findings are different from CI/CD tool findings. CI/CD dependency findings are for vulnerabilities in CI/CD dependency versions, while CI/CD tool findings are for the usage of a given tool. Findings related to CI/CD tools are included by default.