Skip to main content

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.

The examples/policies/ directory in the repository includes six ready-to-use policies. Each file can be used as-is, combined with others, or adapted to your organization’s risk tolerance.
Flags packages that have contributors from OFAC-sanctioned countries. Uses graduated action levels — hard deny for North Korea, review for other sanctioned countries, and warn for Russia’s partial sanctions.
# OFAC Compliance Policy
#
# Flags packages that have contributors from OFAC-sanctioned countries.
# The US Office of Foreign Assets Control (OFAC) restricts transactions
# with individuals and entities in sanctioned countries.
#
# This policy is intentionally conservative — it flags for review rather
# than outright denying, since open source contributors may be US persons
# or dual nationals who happen to be located in sanctioned countries.
#
# Sanctioned countries (as of 2024):
#   CU - Cuba
#   IR - Iran
#   KP - North Korea
#   SY - Syria
#   RU - Russia (partial sanctions)
#
# Customize by:
#   - Adding/removing country codes
#   - Changing action levels (deny vs review)
#   - Adding allow rules for vetted packages

apiVersion: netrise/v1
kind: Policy
metadata:
  name: ofac-compliance
  description: Flag packages with contributors from OFAC-sanctioned countries
spec:
  rules:
    # Allow well-known, widely-used packages even if they have
    # contributors from sanctioned countries
    - name: allow-linux-kernel
      description: Linux kernel is too fundamental to block
      action: allow
      match:
        package_purl: "pkg:generic/linux-kernel@*"

    # Deny packages with contributors from the most heavily sanctioned countries
    - name: deny-north-korea-contributors
      description: Deny packages with North Korean contributors
      action: deny
      match:
        contributor_countries:
          - KP

    # Review (human decision required) for other sanctioned countries
    - name: review-sanctioned-country-contributors
      description: Review packages with contributors from OFAC-sanctioned countries
      action: review
      match:
        contributor_countries:
          - CU
          - IR
          - SY

    # Warn on Russian contributors (partial sanctions)
    - name: warn-russia-contributors
      description: Flag packages with Russian contributors for awareness
      action: warn
      match:
        contributor_countries:
          - RU
Rules:
  • allow-linux-kernel — exempts the Linux kernel PURL from all other rules in this policy
  • deny-north-korea-contributors — hard blocks packages with any contributor from North Korea (KP)
  • review-sanctioned-country-contributors — flags Cuba, Iran, and Syria for human review
  • warn-russia-contributors — logs a warning for Russian contributors without blocking
Detects supply chain compromise indicators modeled after the XZ Utils attack (CVE-2024-3094). Combines advisory relationships with signing key change signals for layered detection.
# Supply Chain Compromise Detection Policy
#
# Detects indicators of supply chain compromise based on the
# Provenance advisory database and contributor security posture.
#
# This policy is modeled after the XZ Utils compromise (CVE-2024-3094),
# where a malicious contributor gained commit access, introduced a
# backdoor, and changed signing keys.
#
# Risk indicators:
#   - Direct advisory relationship: the package itself is known to be affected
#   - Indirect advisory + key change: compromise may have spread through
#     a contributor who also changed their signing key
#   - Key change alone: suspicious but not necessarily malicious
#
# Customize by:
#   - Adjusting advisory name patterns to match your threat intelligence
#   - Adding allow rules for packages you've manually reviewed

apiVersion: netrise/v1
kind: Policy
metadata:
  name: supply-chain-compromise
  description: Detect indicators of supply chain compromise
spec:
  rules:
    # Deny any package with a direct advisory — it's known to be affected
    - name: deny-direct-advisory
      description: Block packages with direct security advisories
      action: deny
      match:
        advisory_relationship: direct

    # Review if the package has an indirect advisory AND a signing key change
    # This combination suggests the compromise may have spread
    - name: review-indirect-advisory-with-key-change
      description: Review packages with indirect advisories and signing key changes
      action: review
      match:
        advisory_relationship: indirect
        key_change_detected: true

    # Review indirect advisories alone
    - name: review-indirect-advisory
      description: Review packages with indirect security advisories
      action: review
      match:
        advisory_relationship: indirect

    # Warn on signing key changes (could be legitimate rotation)
    - name: warn-key-change
      description: Flag signing key changes for awareness
      action: warn
      match:
        key_change_detected: true

    # Warn on specific advisory patterns
    - name: warn-netr-advisories
      description: Flag Provenance-specific advisories
      action: warn
      match:
        advisory_names:
          - "NETR-*"
Rules:
  • deny-direct-advisory — hard blocks any package with a direct advisory relationship
  • review-indirect-advisory-with-key-change — AND rule: both indirect advisory and key change must match; suggests spread of compromise
  • review-indirect-advisory — flags indirect advisories for human review
  • warn-key-change — logs key changes without blocking (legitimate rotation is common)
  • warn-netr-advisories — flags all advisories from Provenance’s advisory database
Enforces repository health standards — bus factor, staleness, Scorecard scores, and signed commit ratios. Graduated from hard deny for critical failures down to informational for low-signal findings.
# Repository Health Policy
#
# Evaluates the health and maintenance status of a package's source
# repository. Healthy repositories are more likely to receive timely
# security patches and less likely to have undetected vulnerabilities.
#
# This policy uses the Provenance repo health API to check:
#   - Bus factor: how many active maintainers the project has
#   - Archive/deprecation status: whether the project is still maintained
#   - Commit recency: whether the project is actively developed
#   - Signed commit ratio: whether contributors sign their work
#
# Customize by:
#   - Adjusting thresholds (bus_factor, commit days, scorecard score)
#   - Changing action levels based on your risk tolerance
#   - Adding allow rules for repos you've manually assessed

apiVersion: netrise/v1
kind: Policy
metadata:
  name: repo-health
  description: Evaluate repository health and maintenance status
spec:
  rules:
    # Deny archived repos with low bus factor — unmaintained and risky
    - name: deny-archived-low-bus-factor
      description: Deny archived repos with bus factor below 2
      action: deny
      match:
        repo_archived: true
        bus_factor_below: 2

    # Deny on very low bus factor alone
    - name: deny-single-maintainer
      description: Deny packages from single-maintainer repos
      action: deny
      match:
        bus_factor_below: 2

    # Review repos with no recent commits (stale for a year)
    - name: review-stale-repo
      description: Review repos with no commits in 365 days
      action: review
      match:
        no_recent_commits_days: 365

    # Warn on low scorecard score
    - name: warn-low-scorecard
      description: Flag repos with low OpenSSF scorecard scores
      action: warn
      match:
        scorecard_score_below: 5.0

    # Info on low signed commit ratio
    - name: info-unsigned-commits
      description: Note repos with low signed commit ratio
      action: info
      match:
        signed_commit_ratio_below: 0.5
Rules:
  • deny-archived-low-bus-factor — AND rule: only denies when archived AND bus factor below 2
  • deny-single-maintainer — denies any repo with fewer than 2 active maintainers
  • review-stale-repo — flags repos with no commits in the past year for human review
  • warn-low-scorecard — logs a warning for Scorecard scores below 5.0 out of 10
  • info-unsigned-commits — informational finding for repos where fewer than 50% of commits are signed
Assesses the security posture of package contributors. The combined has_breached_credentials + key_change_detected signal is modeled on the XZ Utils attack pattern.
# Contributor Risk Assessment Policy
#
# Evaluates the security posture of package contributors.
# Compromised contributor accounts are a primary vector for
# supply chain attacks.
#
# Risk indicators:
#   - Breached credentials: contributor's credentials found in known breaches
#   - Key change: signing key was changed (could indicate compromise or rotation)
#   - Low signed commit ratio: makes it harder to verify commit authenticity
#
# The combination of breached credentials AND key change is particularly
# concerning — it suggests an attacker may have taken over the account
# and rotated the signing key.
#
# Customize by:
#   - Adjusting the signed_commit_ratio threshold
#   - Adding allow rules for specific packages with known-safe contributors
#   - Changing deny to review if you want human oversight

apiVersion: netrise/v1
kind: Policy
metadata:
  name: contributor-risk
  description: Assess contributor security posture and breach risk
spec:
  rules:
    # Deny if BOTH breached credentials AND key change — strong compromise signal
    - name: deny-breached-with-key-change
      description: Deny when contributor has breached credentials and key change
      action: deny
      match:
        has_breached_credentials: true
        key_change_detected: true

    # Review breached credentials alone — may not indicate active compromise
    - name: review-breached-credentials
      description: Review packages with contributors who have breached credentials
      action: review
      match:
        has_breached_credentials: true

    # Warn on key change alone — could be legitimate rotation
    - name: warn-key-change
      description: Flag signing key changes for awareness
      action: warn
      match:
        key_change_detected: true

    # Info on low signed commit ratio
    - name: info-low-signing-ratio
      description: Note repos where less than half of commits are signed
      action: info
      match:
        signed_commit_ratio_below: 0.5
Rules:
  • deny-breached-with-key-change — AND rule: hard blocks when credentials are breached AND a signing key was changed (strongest compromise signal)
  • review-breached-credentials — flags breached credentials alone for human review (may be stale breach data)
  • warn-key-change — logs key changes; by itself could be legitimate key rotation
  • info-low-signing-ratio — informational: less than half of commits signed
Blocks known-bad contributor identities and flags suspicious repository sources. Demonstrates contributor_emails and repo_urls glob matching, with an allow exemption for vetted packages.
# Targeted Risk Policy
#
# Blocks known-bad contributor identities and flags suspicious repository
# sources. Inspired by the XZ Utils compromise (CVE-2024-3094), where the
# attacker "Jia Tan" used personal email addresses (jiat0218@gmail.com,
# jiat75@gmail.com) to gain commit access to the tukaani-project/xz repo.
#
# This policy demonstrates two conditions:
#   - contributor_emails: glob-match against contributor email addresses
#     from the package's repository_details.contributors[].email field
#   - repo_urls: glob-match against the package's repository URL
#     from repository_details.url
#
# Both conditions accept a list of glob patterns. A match on ANY pattern
# triggers the rule. Multiple conditions on the same rule are AND-joined.
#
# Exit codes when used with `provenance check`:
#   0 = PASS (all clear, or only info/warn findings)
#   1 = DENY (at least one deny rule matched)
#   2 = REVIEW (at least one review rule, but no denies)
#
# Usage:
#   provenance check 'pkg:deb/debian/xz-utils@5.0.0-2' --policy examples/policies/targeted-risk.yaml
#   provenance check sbom.json --policy examples/policies/targeted-risk.yaml

apiVersion: netrise/v1
kind: Policy
metadata:
  name: targeted-risk
  description: Block known-bad contributor emails and flag suspicious repository sources
spec:
  rules:
    # ── DENY: Known-bad contributor identities ──────────────────────────
    #
    # Hard block on specific email addresses associated with the XZ Utils
    # supply chain attack. These are the exact addresses used by the
    # attacker to commit malicious code.

    - name: deny-known-bad-contributor
      description: Block packages with contributors matching known compromised email addresses
      action: deny
      message: "Contributor email matches a known-bad identity associated with supply chain attacks"
      match:
        contributor_emails:
          - "jiat0218@gmail.com"
          - "jiat75@gmail.com"

    # ── DENY: Blocked repository organizations ──────────────────────────
    #
    # Block all packages sourced from a specific GitHub organization.
    # Replace "blocked-org" with actual organization names your security
    # team has identified as untrusted or compromised.

    - name: deny-blocked-org
      description: Block packages from untrusted repository organizations
      action: deny
      message: "Package repository belongs to a blocked organization"
      match:
        repo_urls:
          - "*github.com/blocked-org/*"

    # ── REVIEW: Suspicious repository sources ───────────────────────────
    #
    # Flag all packages from the tukaani-project organization for manual
    # review. Even after the XZ compromise was discovered and remediated,
    # ongoing scrutiny of this project is warranted.

    - name: review-xz-project
      description: Flag packages from the tukaani-project for additional scrutiny
      action: review
      message: "Package originates from the tukaani-project, which was targeted in a supply chain attack"
      match:
        repo_urls:
          - "*tukaani-project*"

    # ── WARN: Disposable/anonymous email contributors ───────────────────
    #
    # Flag contributors using noreply addresses. These are generated by
    # GitHub when users hide their email, and while common, they reduce
    # traceability of who authored code.

    - name: warn-disposable-emails
      description: Flag contributors using noreply or anonymous email addresses
      action: warn
      message: "Contributor uses a noreply or anonymous email address, reducing traceability"
      match:
        contributor_emails:
          - "*noreply*"

    # ── ALLOW: Vetted packages ──────────────────────────────────────────
    #
    # Exempt specific packages that have been manually reviewed and
    # approved, even if they would otherwise trigger deny or review rules.
    # This curl package is an example of an exemption.

    - name: allow-vetted
      description: Exempt manually reviewed packages from deny/review rules
      action: allow
      message: "Package has been manually vetted and approved"
      match:
        package_purl: "pkg:deb/debian/curl@*"
Rules:
  • deny-known-bad-contributor — hard blocks packages where any contributor email matches the exact addresses used in the XZ Utils attack
  • deny-blocked-org — hard blocks packages sourced from a configurable blocked GitHub organization (replace blocked-org with real values)
  • review-xz-project — flags all packages from the tukaani-project GitHub org for ongoing scrutiny
  • warn-disposable-emails — logs a warning for contributors using noreply addresses
  • allow-vetted — exempts pkg:deb/debian/curl@* from all deny and review rules in this policy
Comprehensive policy combining rules from all four domains: OFAC compliance, supply chain compromise detection, repository health, and contributor risk. Designed for high-security environments.
# Full Compliance Policy
#
# Comprehensive policy combining rules from all four domains:
#   1. OFAC compliance (contributor country checks)
#   2. Supply chain compromise detection (advisory relationships, key changes)
#   3. Repository health (bus factor, staleness, scorecard)
#   4. Contributor risk (breached credentials, signing practices)
#
# This policy is intentionally strict — it's designed for high-security
# environments where software supply chain risk must be minimized.
# Adjust action levels and thresholds based on your organization's
# risk tolerance.
#
# Exit codes when used with `provenance check`:
#   0 = PASS (all clear, or only info/warn findings)
#   1 = DENY (at least one deny rule matched)
#   2 = REVIEW (at least one review rule, but no denies)
#
# Usage:
#   provenance check my-sbom.json --policy examples/policies/full-compliance.yaml
#   provenance check 'pkg:deb/debian/xz-utils@5.0.0-2' --policy examples/policies/full-compliance.yaml

apiVersion: netrise/v1
kind: Policy
metadata:
  name: full-compliance
  description: Comprehensive supply chain compliance policy
spec:
  rules:
    # ── SUPPLY CHAIN COMPROMISE ──────────────────────────────────────────

    # Hard deny on direct advisories
    - name: deny-direct-advisory
      description: Block packages with known direct security advisories
      action: deny
      match:
        advisory_relationship: direct

    # ── CONTRIBUTOR RISK ─────────────────────────────────────────────────

    # Hard deny on breached credentials + key change combination
    - name: deny-compromised-contributor
      description: Block when contributor shows signs of account compromise
      action: deny
      match:
        has_breached_credentials: true
        key_change_detected: true

    # ── REPOSITORY HEALTH ────────────────────────────────────────────────

    # Hard deny on archived single-maintainer repos
    - name: deny-abandoned-repo
      description: Block packages from archived repos with single maintainer
      action: deny
      match:
        repo_archived: true
        bus_factor_below: 2

    # ── OFAC COMPLIANCE ──────────────────────────────────────────────────

    # Deny North Korean contributors
    - name: deny-kp-contributors
      description: Block packages with North Korean contributors
      action: deny
      match:
        contributor_countries:
          - KP

    # ── TARGETED CONTRIBUTOR RISK ────────────────────────────────────────

    # Hard deny on known-compromised contributor emails (e.g., Jia Tan)
    - name: deny-known-compromised-emails
      description: Block packages with contributors matching known compromised email addresses
      action: deny
      match:
        contributor_emails:
          - "jiat0218@gmail.com"
          - "jiat75@gmail.com"

    # Review packages with contributors using anonymous email providers
    - name: review-anonymous-email-contributors
      description: Review packages with contributors using anonymous email providers
      action: review
      match:
        contributor_emails:
          - "*@protonmail.com"
          - "*@tutanota.com"

    # ── REPOSITORY SOURCE CONTROL ────────────────────────────────────────

    # Review packages from blocked repository organizations
    - name: review-blocked-repo-orgs
      description: Review packages sourced from flagged repository organizations
      action: review
      match:
        repo_urls:
          - "*github.com/blocked-org/*"

    # Informational: track repository source for visibility
    - name: info-repo-source-tracking
      description: Note packages from the tukaani-project for ongoing monitoring
      action: info
      match:
        repo_urls:
          - "*tukaani-project*"

    # ── REVIEW-LEVEL FINDINGS ────────────────────────────────────────────

    # Review indirect advisories with key changes
    - name: review-indirect-advisory-key-change
      description: Review packages with indirect advisories and key changes
      action: review
      match:
        advisory_relationship: indirect
        key_change_detected: true

    # Review indirect advisories
    - name: review-indirect-advisory
      description: Review packages with indirect security advisories
      action: review
      match:
        advisory_relationship: indirect

    # Review breached credentials
    - name: review-breached-credentials
      description: Review packages with contributors who have breached credentials
      action: review
      match:
        has_breached_credentials: true

    # Review single-maintainer repos
    - name: review-low-bus-factor
      description: Review packages from single-maintainer repos
      action: review
      match:
        bus_factor_below: 2

    # Review stale repos
    - name: review-stale-repo
      description: Review repos with no commits in 365 days
      action: review
      match:
        no_recent_commits_days: 365

    # Review sanctioned country contributors
    - name: review-sanctioned-countries
      description: Review packages with contributors from sanctioned countries
      action: review
      match:
        contributor_countries:
          - CU
          - IR
          - SY

    # ── WARNING-LEVEL FINDINGS ───────────────────────────────────────────

    # Warn on key changes
    - name: warn-key-change
      description: Flag signing key changes
      action: warn
      match:
        key_change_detected: true

    # Warn on low scorecard
    - name: warn-low-scorecard
      description: Flag repos with low OpenSSF scorecard scores
      action: warn
      match:
        scorecard_score_below: 5.0

    # Warn on Russian contributors
    - name: warn-russia-contributors
      description: Flag packages with Russian contributors
      action: warn
      match:
        contributor_countries:
          - RU

    # ── INFORMATIONAL FINDINGS ───────────────────────────────────────────

    # Info on unsigned commits
    - name: info-unsigned-commits
      description: Note repos with low signed commit ratio
      action: info
      match:
        signed_commit_ratio_below: 0.5

    # Info on no-assertion license
    - name: info-no-license
      description: Note packages with no license assertion
      action: info
      match:
        license_spdx:
          - NONE
Rules summary by domain:
  • Supply chain compromise: deny-direct-advisory, review-indirect-advisory-key-change, review-indirect-advisory
  • Contributor risk: deny-compromised-contributor, deny-known-compromised-emails, review-anonymous-email-contributors, review-breached-credentials, warn-key-change, info-unsigned-commits
  • Repository health: deny-abandoned-repo, review-low-bus-factor, review-stale-repo, warn-low-scorecard, info-no-license
  • OFAC compliance: deny-kp-contributors, review-sanctioned-countries, warn-russia-contributors
  • Repository source: review-blocked-repo-orgs, info-repo-source-tracking

​
Combining policies

Multiple policy files can be passed in a single invocation. All rules from all files are merged and evaluated together. 
# Combine two policy files
provenance check sbom.json --policy ofac.yaml --policy repo-health.yaml

# Load an entire directory of policies
provenance check sbom.json --policy examples/policies/
When multiple policies are combined, the overall verdict is the most severe finding across all rules and all packages: deny > review > pass.

​
Using allow rules

allow rules are evaluated before all other rules. A package matching an allow rule is exempt from any deny, review, or warn rules in the same evaluation — including rules from other policy files loaded in the same invocation. Use package_purl with a glob pattern to exempt specific packages: 
- name: allow-linux-kernel
  action: allow
  match:
    package_purl: "pkg:generic/linux-kernel@*"
You can also combine conditions on allow rules. The package must match all conditions to be exempted: 
- name: allow-vetted-curl
  description: Exempt manually reviewed curl packages
  action: allow
  match:
    package_purl: "pkg:deb/debian/curl@*"
Add allow rules to your policy files rather than maintaining a separate allowlist. This keeps exemptions version-controlled alongside the rules they override.

Build docs developers (and LLMs) love

Get started for freeTalk to us