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.
provenance is a CLI tool that queries the Provenance API to surface risk in your software dependencies: who wrote it, where it comes from, whether it has been compromised, and whether it meets your compliance policies.
It works with individual packages, SBOMs, and OCI container images, and integrates into CI/CD pipelines via YAML-based policy enforcement with semantic exit codes.
Key capabilities
- Query package provenance, repository health, contributor security posture, and advisory data by PURL, repo URL, contributor email, or advisory ID.
- Scan SBOMs in CycloneDX, SPDX, or CSV format and query every package concurrently against the API.
- Scan OCI containers directly — extract an SBOM from any OCI image using cosign or syft, then analyze all packages in one pass.
- Enforce YAML-based policies that gate CI/CD on contributor risk, advisory exposure, repository health, and compliance requirements such as OFAC sanctions screening.
- Output human-readable tables, structured JSON, or SARIF v2.1.0 for GitHub Code Scanning integration.
Supported SBOM formats
Format is auto-detected from file content. Use--stdin to pipe SBOMs from other tools.
| Format | Extensions | Detection |
|---|---|---|
| CycloneDX JSON | .cdx.json, .json | bomFormat field |
| CycloneDX XML | .cdx.xml, .xml | <bom> root element |
| SPDX JSON | .spdx.json, .json | spdxVersion field |
| SPDX tag-value | .spdx, .spdx.tv | SPDXVersion: line |
| CSV | .csv | Header row with purl or type,namespace,name,version |
Output formats
All commands support three output formats via--format:
| Format | Flag | Use case |
|---|---|---|
human | --format human (default) | Interactive terminal use — colored tables with Unicode borders |
json | --format json | Automation, scripting, piping to jq |
sarif | --format sarif | GitHub Code Scanning, Azure DevOps, SARIF-compatible tools |
Architecture
provenance is a stateless CLI that talks to a single remote API:
PROVENANCE_API_TOKEN.
Configuration is resolved in priority order: CLI flags > environment variables > config file (~/.config/provenance/config.yaml) > defaults.
Where to go next
Quick start
Authenticate and run your first scan in minutes.
Installation
Install from pre-built binaries or build from source.
Command reference
Detailed documentation for every command, subcommand, and flag.
Policy engine
Write YAML policies to gate CI/CD on contributor risk, advisories, and repo health.