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

Return to the regular view of this page.

validate

Use the validate command to validate policies and ignore files

Table of Contents

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

Return to the regular view of this page.

Use the validate command to validate policies and ignore files

The endorctl validate command provides validation utilities for policy and ignore files.

The syntax of endorctl validate is:

endorctl validate [command]

The following commands are supported:

  • endorctl validate ignore validates ignore file syntax and entries.
  • endorctl validate policy validates policies against project data.

ignore

The endorctl validate ignore command validates that an ignore file follows the yaml schema and flags duplicates or invalid entries.

The syntax of the endorctl validate ignore command is:

endorctl validate ignore [flags]

The endorctl validate ignore command uses the following flags and environment variables:

Flag Environment Variable Type Description
path ENDOR_VALIDATE_IGNORE_PATH string Path to the ignore file to validate (default: .endorignore.yaml).

Validate an ignore file:

endorctl validate ignore --path .customignore.yaml

ERROR invalid-args: Duplicate ignore entry for 'Unmaintained Dependency org.webjars.bowergithub.webcomponents:shadycss@1.9.1': endorlabs/app-java-demo-2
ERROR invalid-args: Duplicate ignore entry for 'Unmaintained Dependency org.webjars.bowergithub.webcomponents:shadycss@1.9.1': endorlabs/app-java-demo-3

An invalid argument was provided.
details: 2 errors detected

policy

Use the endorctl validate policy command to validate one or more policies against data from one or more projects. If the policy is valid, the command returns all matches for the given projects, in the requested format, with the corresponding exit code.

The syntax of the endorctl validate policy command is:

endorctl validate policy [policies] [flags]

The endorctl validate policy command uses the following flags and environment variables:

Flag Environment Variable Type Description
all-releases ENDOR_VALIDATE_POLICY_ALL_RELEASES boolean Load data from all official releases of the project.
filter ENDOR_VALIDATE_POLICY_PROJECT_FILTER string Filter projects to load data from. For example, "meta.tags contains sanity".
input ENDOR_VALIDATE_POLICY_INPUT_FILE_PATH json Path to a json file containing the input parameter values, if applicable. Input parameters are sometimes used for policy templates.
output-type ENDOR_VALIDATE_POLICY_SUMMARY_OUTPUT_TYPE string Set output format (json, yaml, or table) (default table).
policy ENDOR_VALIDATE_POLICY_FILE_PATH string Path to a file containing the policies to be validated. Supported formats: Text (plain Rego rules), json (one or more policies), or yaml (one or more policies or policy templates).
policy-uuid ENDOR_VALIDATE_POLICY_UUID string UUIDs of policies to be validated.
pr-baseline ENDOR_VALIDATE_POLICY_PR_BASELINE string Name of the baseline version from which to load data. For example, main.
pr-uuid ENDOR_VALIDATE_POLICY_PR_UUID string PR scan from which to load data.
query ENDOR_VALIDATE_POLICY_QUERY_STATEMENTS string Query statements for this policy (for example, data.packagename.match_finding). This option is only needed for plain text Rego rules.
resource-kinds ENDOR_VALIDATE_POLICY_RESOURCE_KINDS comma-separated string Resource kinds required by this policy (for example, PackageVersion,Metric). This option is only needed for plain text Rego rules.
uuid ENDOR_VALIDATE_POLICY_PROJECT_UUID string UUID of the project from which to load data.

Use one of the following formats to specify one or more policies:

Input format Description
Plain text Rego Provide the file path to a file containing just the Rego rules. The query statement is provided as a separate parameter. For example, endorctl validate policy --policy policy.txt --query data.example.match_package_version_score.
json Provide the file path to a json file containing one or more Policy objects (see Policy, Policies, and ListPoliciesResponse). For example, endorctl validate policy --policy policy.json.
yaml Provide the file path to a yaml file containing one or more policy or policy template definitions (see Policies and PolicyTemplates). For example, endorctl validate policy --policy policy.yaml.
UUID Provide one or more UUIDs of existing Policy objects. For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025.

Use one of the following formats to specify one or more projects from which to load data:

Input format Description
Filter Load data from all projects matching a given filter. For example, endorctl validate policy --policy policy.rego --query data.example.match_package_version_score --filter "meta.tags contains release".
UUID Provide the UUID of the project from which to load data. For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 --uuid 6699c827cd89accb3a017536.
PR UUID Provide the UUID of a PR from which to load data. Add the baseline version name to match only new findings. For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 --uuid 6699c827cd89accb3a017536 --pr-uuid 43064105-1fd7-42fe-a380-bd5e36657d39 --pr-baseline main.

As with the other endorctl commands, you can specify if you prefer the output as a table, or in json or yaml format. If the output format is json or yaml the matching findings are listed under "matching_findings" and the results for all other resource kinds are listed under "matching_resources".

For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 --uuid 6699c827cd89accb3a017536 --output-type json.

If the policy is valid and there are no matches the command returns 0. The following table lists the non-zero exit codes returned by the endorctl validate policy command:

Value Exit Code Name Description
3 ENDORCTL_RC_INVALID_ARGS An invalid argument was provided.
18 ENDORCTL_RC_POLICY_ERROR There was an error evaluating one or more policies. See log for details.
128 ENDORCTL_RC_POLICY_VIOLATION One or more policies had matching findings for the given projects.

For a complete list of endorctl exit codes, see endorctl CLI exit codes.

Below is an example on how to verify that a Rego policy is correctly formatted.

  1. First, define a Rego policy. Let’s take the example policy below that searches for dependencies with an Endor Labs overall score of less than 7. You can save this to a file called “test_policy.rego”.

    package example

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

  2. Next, validate that the policy is correctly formatted.

    endorctl validate policy \
  --policy test_policy.rego \
  --query data.example.match_package_version_score

  3. Add a project UUID to validate the policy against real data.

    endorctl validate policy \
  --policy test_policy.rego \
  --query data.example.match_package_version_score \
  --uuid $PROJECT_UUID \
  --output-type json > output.json

  4. Inspect the policy output.

    {
  "matching_resources": {
    "6553132357b462874261f054": {
      "Policy 1": {
        "PackageVersion": [
          {
            "resource_name": "pypi://astunparse@1.6.3",
            "resource_uuid": "63f599e177cf1f3d7f286ea1",
            "result": {
              "None": [
                {
                  "Score": "6"
                }
              ]
            }
          },
  • Set --output-type to json or yaml for formatted output
  • Add the --verbose flag for detailed output
  • Set --log-level debug for more information