Documentation Index
Fetch the complete documentation index at: https://mintlify.com/NetRiseInc/provenance-cli/llms.txt
Use this file to discover all available pages before exploring further.
Policies are YAML files that define rules for evaluating packages against supply chain risk criteria. Each rule matches on conditions derived from API data and triggers an action. Multiple policy files can be combined — all rules from all files are evaluated together.
Policy file structure
Every policy file follows this schema:
apiVersion: netrise/v1
kind: Policy
metadata:
name: my-policy
description: What this policy enforces
spec:
rules:
- name: rule-name
description: What this rule checks
action: deny # deny | review | warn | info | allow
message: "Why this matters"
match:
bus_factor_below: 2
repo_archived: true # Multiple conditions are AND-joined
| Field | Required | Description |
|---|
apiVersion | Yes | Must be netrise/v1 |
kind | Yes | Must be Policy |
metadata.name | No | Human-readable policy name |
metadata.description | No | What this policy enforces |
spec.rules | Yes | List of rules to evaluate |
rules[].name | Yes | Rule identifier used in output |
rules[].action | Yes | One of deny, review, warn, info, allow |
rules[].match | No | Map of conditions (AND-joined) |
rules[].description | No | Explains what the rule checks |
rules[].message | No | Message shown when the rule matches |
Actions and exit codes
| Action | Behavior | Exit code |
|---|
deny | Hard failure — blocks CI/CD pipelines | 1 |
review | Flags for human review | 2 |
warn | Logs a warning, does not affect exit | 0 |
info | Informational finding | 0 |
allow | Exempts matching packages from deny/review/warn | 0 |
allow rules are evaluated first. If a package matches an allow rule, it is exempt from all deny, review, and warn rules regardless of what other rules match.
Condition logic
Multiple conditions in a single rule are AND-joined. All conditions must match for the rule to trigger.
# This rule only matches when BOTH conditions are true
- name: deny-archived-low-bus-factor
action: deny
match:
repo_archived: true
bus_factor_below: 2
# These two rules together implement OR logic
- name: deny-archived
action: deny
match:
repo_archived: true
- name: deny-low-bus-factor
action: deny
match:
bus_factor_below: 2
Loading policies
Pass one or more policy files or directories to any provenance check or provenance scan command:
# Single policy file
provenance check sbom.json --policy ofac.yaml
# Multiple files (all rules are combined)
provenance check sbom.json --policy ofac.yaml --policy repo-health.yaml
# Entire directory of policy files
provenance check sbom.json --policy examples/policies/
# Using --policy-dir flag
provenance check sbom.json --policy-dir policies/
When you pass a directory path to --policy, every .yaml and .yml file in that directory is loaded. All rules from all files are evaluated together as if they were in a single policy.
Automatic API data fetching
The engine fetches only the data needed for the conditions in your policies. No extra API calls are made for conditions you aren’t using.
| Conditions | Data fetched automatically |
|---|
bus_factor_below, repo_archived, repo_deprecated, scorecard_score_below, no_recent_commits_days, has_breached_credentials, contributor_countries, license_spdx | Repository health data |
key_change_detected, signed_commit_ratio_below | Contributor security data |
advisory_relationship, advisory_names, contributor_emails, repo_urls, package_purl | Package data (always fetched) |