This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Policies

Policies are rules that allow you to customize the behavior of the Endor Labs scan.

You can use policies to:

  • Enable, disable, or edit out-of-the-box features
  • Create custom findings
  • Set guardrails for the development process
  • Create custom ticketing or messaging workflows

Endor Labs comes with various out-of-the-box policies that enable you to quickly get started with the product. Policy templates are available to help you easily create custom findings and configure workflows around known vulnerabilities, outdated, unmaintained, or unused software dependencies, license risks, code review guidelines, repository configurations, and more.

You can also write policies from scratch using Rego policy language and customize policies based on organizational rules and needs.

Policy types

There are two types of policies that you can set up with Endor Labs.

  1. Finding policies - Enable or disable out-of-the-box features and create custom finding policies to identify and raise findings for issues in your development environment. For example, you can create a finding policy to raise findings for missing, unknown, problematic, or incompatible licenses.
  2. Action policies - Create action policies to define the system behavior and set up workflows when a finding with a given set of properties is raised. For example, you can create an action policy to create a Jira task when packages with outdated dependencies are included in your projects.

Key benefits

Policies are essential to define risk tolerance, set automated rules for open source components, check your repository or organization configuration, and more.

  • Identify and triage issues - Policies give you a quick and automated way to identify and triage issues in your environment. This saves valuable development time and ensures developers consider security issues at the early stages of application development.
  • Improve decision-making - Automating enforcement simplifies decision-making in an organization and reduces complexity. Policies make assessing the OSS components simpler and allow developers to focus on violations critical to the organization.
  • Establish governance - Use policies to set up an organization’s governance methods such as enforcing Multi-Factor Authentication, setting up code review guidelines, guidelines on the use of the open source components, preventing misconfiguration of source code repositories, and more.

1 - 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. 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:

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

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.

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

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

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 on how to create policies from policy templates.

Policy Template Description Severity
Unauthorized Tool Usage Raise a finding if a repository uses a tool that is specifically not approved by the company policy. Medium
Require Tool Category Raise a finding if a repository does not have any tools in a required tool category. Medium
Require Tool Raise a finding if a required tool is not detected in a repository. Medium

1.2 - License policies

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

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 on how to create policies from policy templates.

Policy Template Description Severity
Permit only specified software licenses Use this template to define an allowed list of software licenses permitted within your organization or a subset of projects. Endor Labs will raise findings when dependencies in packages or projects have licenses that are not on the allowed list. Medium
Restricted software licenses Use this template to define a blocked list of software licenses that should be restricted from use or only used within specific contexts within your organization. Endor Labs will raise findings when dependencies in packages or projects have licenses that are on the blocked list. Medium
Restricted software license types Use this template to create an organizational policy to restrict certain license types or limit a license type to specific contexts within an organization. This is useful to identify license risks and violations in 3rd party open source packages. The license type classification in this policy follows the industry best practice rules defined by Google license types. Medium

1.3 - Open-source policies

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

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 on how to enable or disable out-of-the-box policies.

Policy Description Severity
Vulnerabilities Vulnerabilities indicate security weaknesses or flaws in the dependencies used by a software project. They can pose risks to the overall security and stability of a project. Raises findings for projects where vulnerabilities are detected. Critical
Flag Phantom Dependencies Raise findings when dependencies are used in source code but not declared in the package’s manifest files. These dependencies are called phantom dependencies and are detected during the deep scan. They are not detected while performing the --quick-scan. Medium
Outdated Dependencies Outdated dependencies are software libraries, frameworks, or modules that are being used in a project but have newer versions available. They are usually superseded by newer releases that offer bug fixes, security patches, improved functionality, or better performance. Raises findings for projects with outdated software libraries, frameworks, or modules. Medium
Unmaintained Dependencies Unmaintained dependencies refer to external libraries, frameworks, or modules that are no longer actively maintained or supported by their developers. These dependencies may have reached end-of-life, without updates, bug fixes, security patches, or any form of support. Raises findings for projects with unmaintained packages. Medium
Unpinned Direct Dependencies Unpinned direct dependencies indicate the absence of a specific version or range of versions for a dependency. This can lead to potential issues because different versions of dependencies may introduce changes, bug fixes, or even breaking changes, which can impact the project’s behavior or stability. Raises findings for projects with unpinned dependencies. Medium
Unused Direct Dependencies Unused direct dependencies are listed in a project’s configuration or dependency file and are not utilized or referenced in the project’s source code. Raise findings for projects with unused direct dependencies. Medium
Low Endor Activity Scores Projects with low Endor Labs activity scores are less likely to be kept up to date. They are susceptible to software bugs and security risks. Raise findings for packages with low Endor Labs activity scores. Low
Missing Source Code If you cannot audit the source code associated with a software component, there is limited visibility that can result in operational and security risks. Raises findings for packages with missing source code. Low
Low Endor Quality Scores Projects with low Endor Labs quality scores are highly likely to be susceptible to security and operational risks. Raise findings for packages with low Endor Labs quality scores. Low
Potential Typosquats Typosquats is a malicious practice where a domain name closely resembles popular or legitimate domain names but contains typographical errors. This can deceive or exploit users who make mistakes while typing the intended website’s URL or package name. Raises findings for packages that contain potential typosquats. Low
Low Endor Popularity Scores A popularity score indicates how well the software component is being used by developers. Raise findings for repositories that have low popularity scores. Low

1.4 - SCPM policies

Learn about the out-of-the-box finding policies for source code posture management (SCPM).

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 on how to enable, disable, or edit out-of-the-box policies.

Policy Description Severity
At least two administrators should be configured for a repository Having fewer than two administrators for a repository may cause problems when the administrator is unavailable. A minimum of two administrators must be configured to meet this requirement. Medium
Authorization to push or merge to protected branches should be limited Limiting the authorization to push or merge code to protected branches is a best practice in software development workflows. By restricting access to protected branches, you maintain control over code changes and ensure that only authorized individuals can make modifications. Raises findings for repositories that do not enforce rules around merging code to protected branches. Medium
Branch protection rules should be enforced on administrators Enforcing branch protection rules on administrators is a best practice in software development workflows. By applying branch protection rules to administrators, you ensure that even privileged individuals follow the established processes and adhere to the same standards as other team members. Raises findings for repositories that do not enforce branch protection rules. Medium
Branches should be up-to-date before merging Ensuring that branches are up-to-date before merging is a best practice in software development. It avoids conflicts, helps in the early detection of issues, and maintains code coherence. Raise findings for repositories that do not enforce rules on branches to be up-to-date before merging. Medium
Code owner review is required when a change affects owned code Code owner review is a practice in software development where specific individuals or teams are designated as code owners for certain parts of the codebase. When a change is proposed that affects code owned by a particular individual or team, a code owner review is required before the change can be merged into the main codebase. Low
Code owner should be configured for sensitive code Code owner review is a best practice in software development workflows where specific individuals or teams are designated as code owners for certain parts of the codebase. When a change is proposed that affects code owned by a particular individual or team, a code owner review is required before the change can be merged into the main codebase. Raises findings for repositories that do not enforce code owner reviews. Low
Comments should be resolved before merging Resolving comments ensures that all feedback, questions, and issues raised during the code review process have been addressed satisfactorily before the code is considered ready for integration. Raises findings for repositories that do not resolve comments before merging. Low
Commits should be signed for new changes Requiring commits to be signed for new changes is a best practice in software development workflows. Commit signing involves using digital signatures to verify the authenticity and integrity of the commit. Raises findings for repositories that do not enforce signed commits. Medium
Contributors should not approve their own changes Robust code reviews are essential and contributors should not approve their own changes in a collaborative software development environment. Raises findings for repositories that do not enforce code reviews. High
Dismissing Code Change Reviews should be restricted Restricting the ability to dismiss code change reviews is a best practice in software development workflows. Dismissing code change reviews should be limited to specific cases and authorized individuals to ensure accountability, maintain code quality, and promote a collaborative and transparent review process. Raises findings for repositories that do not enforce rules around dismissing code reviews. Medium
Ensure branch protection is enforced for the default branch Branch protection rules allow you to set controls over your software development processes. The default branch for this repository has no branch protection rules and should be protected. High
Force pushing code to protected branches should be restricted Restricting the ability to force push code to protected branches is a best practice in software development workflows. Restricting this action helps maintain code integrity, accountability, and collaboration. Raises findings for repositories that do not enforce rules around pushing code to protected branches. Medium
Linear commit history should be required Linear comment history indicates a chronological sequence of commits made to a code repository. It provides a clear and chronological view of the code changes made to a repository, aiding in code navigation, collaboration, and bug tracking. Raises findings for repositories that do not have linear commit history. Low
Missing Source Code If you cannot audit the source code associated with a software component, there is limited visibility that can result in operational and security risks. Raises findings for packages with missing source code. Low
Multi-Factor Authentication (MFA) should be required for external contributors Multi-Factor Authentication adds an additional layer of security to access accounts or systems and prevents unauthorized access to code repositories. Raises findings for repositories that do not enforce MFA for external contributors. High
Multi-Factor Authentication (MFA) should be required for organization members Multi-Factor Authentication adds an additional layer of security to access accounts or systems and prevents unauthorized access to code repositories. Raises findings for repositories that do not enforce MFA for members in their organization. High
Organization webhooks should use HTTPS A webhook URL is used to send notifications, along with a payload, to designated internet endpoints. Given that the payload contains sensitive information, all webhooks must be directed toward endpoints secured by HTTPS. Medium
Organization webhooks should use SSL verification When Organization webhook SSL verification is disabled, GitHub is explicitly instructed not to verify the identity of of the remote server it is sending information to. This configuration bypasses standard security controls in the HTTP protocol, which are designed to prevent attackers from executing man in the middle attacks. Low
Organizations should be verified The Organization Verified badge on GitHub is a visual indicator that signifies an organization’s authenticity and official status. It helps users identify legitimate and trusted organizations on the GitHub platform. Raise findings for organizations that are not verified. Low
Organizations should should have fewer than three owners Organization administrators have the highest level of permissions, including the ability to add/remove collaborators, create or delete repositories, change branch protection policy, and convert to a publicly-accessible repository. Due to the permissive access granted to an organization administrator, it is highly recommended to have at most three administrator accounts. Medium
Protected Branch Deletion should be blocked Protecting branch deletion, especially for critical branches, is a best practice in software development workflows. Raises findings for repositories that do not enforce rules around protected branch deletion. Medium
Repository webhooks should use HTTPS A webhook URL is used to send notifications, along with a payload, to designated internet endpoints. Given that the payload contains sensitive information, all webhooks must be directed toward endpoints secured by HTTPS. Medium
Repository webhooks should use SSL verification When repository webhook SSL verification is disabled, GitHub is explicitly instructed not to verify the identity of of the remote server it is sending information to. This configuration bypasses standard security controls in the HTTP protocol, which are designed to prevent attackers from executing man in the middle attacks. Low
Require a SECURITY.md file A SECURITY.md outlines security practices, reporting procedures, and guidelines for handling security-related issues within a project. It is included in the root directory of software repositories. Raise finings for repositories that do not include a SECURITY.md file. Low
Stale approvals should be dismissed To prevent malicious code from being introduced into a codebase, it is important to have a robust approval process for code changes. When changes are made to a proposal, outdated approvals must be declined, and previously accepted code changes must be re-evaluated. The approval process should involve multiple reviewers, and organizations should also consider implementing automated code analysis and security testing. Medium
Status checks should pass before merging new code Ensuring that status checks pass before merging new code is a best practice in software development workflows. Status checks serve as automated checks or validations that assess the quality, integrity, and readiness of the code changes before they are merged into the main codebase. Raises findings for repositories that do not enforce status checks before merging new code. Medium
Two informed reviews should be required for code changes Requiring two informed reviews for code changes is a best practice in software development. It helps ensure that code changes are thoroughly examined, promotes collaboration, and increases the overall quality of the codebase. Raises findings for repositories that do not enforce two reviews for code changes. Medium
Workflows should not be allowed to create and approve pull requests Allowing workflows to create and approve pull requests within an organization can enable users to evade code-review protocols. Attackers could exploit this by establishing workflows that autonomously approve their pull requests and merge them discreetly. Consequently, they can introduce potentially harmful code into the production system. High

1.5 - Secret policies

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

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 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 Description Severity
Valid Secrets Scan the code for active secrets. When a secret is valid, it means that the secret meets the necessary criteria or requirements to be considered acceptable or legitimate within a given context. For example GitHub personal access tokens of an employee that are not yet expired and can be used to access an organization’s codebase. Critical
Invalid Secrets Scan the code for any secrets that are no longer valid. Low
Secrets without validation rules Detect secrets that cannot be validated either because there is no validator or the validation failed for any reason. Medium

Policy templates for secret detection

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

Policy Template Description Severity
Valid Secrets Use this template to scan the code for active secrets. When a secret is valid, it means that the secret meets the necessary criteria or requirements to be considered acceptable or legitimate within a given context. For example GitHub personal access tokens of an employee that are not yet expired and can be used to access an organization’s codebase. Critical
Invalid Secrets Use this template to scan the code for any secrets that are no longer valid. Low
Secrets without validation rules Use this template to detect secrets that cannot be validated either because there is no validator or the validation failed for any reason. Medium
Define custom secret token policy rules Use this template to detect secrets in the code using a custom secret rule to detect secret of any service that may not be included in the other rules. Critical

2 - Action policies

Learn about action policies and how to use them.

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

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

  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

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.

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

3 - Tag projects

Learn about tagging projects to manage policies in Endor Labs

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.

Almost all 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.

Use Case Rationale Example Tags
Data Classification Apply controls to projects from which applications that proccess sensitive are developed. Classification_Restricted, Classification_HighlySensitive, Classification_Public
Application Importance Apply controls to projects based on the importance of the applications developed in them. Application_CrownJewel, Application_Critical
Application Exposure Apply controls to project from which applications that are exposed internally or to the public internet differently. Exposure_Public , Exposure_Internal
Compliance Apply controls to projects where specific compliance or regulatory controls may apply. Compliance_SOC2, Compliance_HIPAA, Compliance_PCI, Compliance_None
Business Unit Apply controls to projects based on a business units maturity or onboarding status. Apply different controls to a new aquisition. BU_Infrastructure, BU_Clinical
Policy Exceptions Do not apply a control to a repository that has an approved policy exception Policy_Exception_Branch_Protection

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.

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.