Endor Validate Policy

Endor Labs Policy Validation

Validate a policy against project data to confirm it matches the expected findings before enforcement.

Input Parsing

Extract from user input:

1. Policy identifier (required) — one of:
   • Policy UUID (e.g., 69de807f2b1bacdc078462e9)
   • Path to a policy file (JSON, YAML, or plain Rego)
2. Project identifier (required) — one of:
   • Project UUID (e.g., 69de7d2281aeff029f3fb926)
   • Project filter string (e.g., meta.name contains my-project)
3. Optional modifiers:
   • PR scan UUID — validate against a specific PR scan
   • PR baseline — name of baseline version for PR comparison
   • All releases — validate against all official releases
   • Input file — JSON file with template parameter values
   • Output format — json, yaml, or table (default: table)

SBOM-Based Projects

Projects created from SBOMs (e.g., pkg:sbom/...) have no git-based scan releases. The validate command loads findings by release, so without --all-releases it will find no data and return 0 matches even when matching findings exist.

Always use --all-releases for SBOM-based projects. Detect them by checking if the project name starts with pkg:sbom/ or if spec.sbom is present in the project resource.

Workflow

Step 1: Resolve Identifiers and Detect Project Type

If the user provides names instead of UUIDs, resolve them:

# Look up project UUID by name
endorctl api list --resource Project --filter "meta.name contains '{name}'" --field-mask "uuid,meta.name" 2>/dev/null

# Look up policy UUID by name
endorctl api list --resource Policy --filter "meta.name contains '{name}'" --field-mask "uuid,meta.name" 2>/dev/null

Check if the project is SBOM-based (name starts with pkg:sbom/ or has spec.sbom). If so, you must add --all-releases to the validate command.

Step 2: Validate

By policy UUID against a project (git-based):

endorctl validate policy --policy-uuid "{POLICY_UUID}" --uuid "{PROJECT_UUID}" 2>&1

By policy UUID against an SBOM-based project (requires --all-releases):

endorctl validate policy --policy-uuid "{POLICY_UUID}" --uuid "{PROJECT_UUID}" --all-releases 2>&1

By policy UUID against a PR scan:

endorctl validate policy --policy-uuid "{POLICY_UUID}" --uuid "{PROJECT_UUID}" --pr-uuid "{PR_UUID}" 2>&1

By policy UUID with PR baseline:

endorctl validate policy --policy-uuid "{POLICY_UUID}" --uuid "{PROJECT_UUID}" --pr-baseline "{BASELINE}" 2>&1

By policy UUID against all releases:

endorctl validate policy --policy-uuid "{POLICY_UUID}" --uuid "{PROJECT_UUID}" --all-releases 2>&1

From a policy file:

endorctl validate policy --policy "{FILE_PATH}" --uuid "{PROJECT_UUID}" 2>&1

Plain Rego with custom query:

endorctl validate policy --policy "{REGO_FILE}" --uuid "{PROJECT_UUID}" \
  --query "data.packagename.match_finding" \
  --resource-kinds "Finding,PackageVersion" 2>&1

With template parameter input file:

endorctl validate policy --policy-uuid "{POLICY_UUID}" --uuid "{PROJECT_UUID}" \
  --input "{INPUT_FILE}" 2>&1

JSON output for programmatic parsing:

endorctl validate policy --policy-uuid "{POLICY_UUID}" --uuid "{PROJECT_UUID}" -o json 2>&1

Step 3: Present Results

If Policy Matches Findings

## Policy Validation: PASS (matches found)

**Policy:** {policy_name} (`{policy_uuid}`)
**Project:** {project_name} (`{project_uuid}`)

### Matched Findings

| Finding UUID | Vulnerability | Severity | Package |
|-------------|---------------|----------|---------|
| {uuid} | {cve/ghsa} | {level} | {package} |

### Summary
- **Total matches:** {count}
- **Policy type:** {exception/finding/action}
- **Effect:** {what the policy will do when enforced}

If Policy Does Not Match

## Policy Validation: NO MATCH

**Policy:** {policy_name} (`{policy_uuid}`)
**Project:** {project_name} (`{project_uuid}`)

No findings in this project match the policy criteria.

### Possible Reasons
- **SBOM-based project without `--all-releases`** — if the project name starts with `pkg:sbom/`, retry with `--all-releases`
- The targeted vulnerability may not exist in this project's dependencies
- Filter criteria (severity, relationship, scope) may be too narrow
- Project may not have been scanned yet

### Next Steps
1. `/endor-findings` — View project findings to compare
2. `/endor-policy` — Review or adjust policy criteria
3. `/endor-scan` — Re-scan the project

Error Handling

For data source policy, read references/data-sources.md.