CRA Evidence CLI

Command-line tools for CRA Evidence workflows and local software supply-chain checks.

The CLI has two modes:

• Local commands that run without a CRA Evidence account or API key.
• Account commands that upload evidence or read release state from CRA Evidence.

This page covers the public command basics. The full reference lives in docs/. Registered CRA Evidence users can also sign in to view the command documentation at https://docs.craevidence.com/cli-reference.

The local checks are review aids and CI gates. They are not an audit, and exit 0 does not prove compliance.

Install

pip install craevidence
pipx install craevidence

pipx is a good fit for command-line tools because it installs the package in an isolated environment.

The installed command is:

craevidence --help

Python 3.12 or newer is required. Docker images and other install options are covered in the installation guide.

Documentation

Local Check

craevidence check scans a directory, container image, or existing SBOM and reports known vulnerability signals that can block CI when a threshold is met. It does not require an account and does not upload your project to CRA Evidence.

craevidence check .
craevidence check --image ghcr.io/acme/app:1.4.2
craevidence check --sbom sbom.cdx.json
craevidence check . --fail-on known-exploited

By default, check uses network data sources. It uses Grype when installed and working, falls back to OSV.dev when Grype is absent or fails, and consults CISA KEV plus FIRST EPSS for enrichment. For a network-restricted run, provide an SBOM with --sbom and run where Grype has a local database; CISA KEV and FIRST EPSS enrichment are reported as unavailable if they cannot be reached.

Verbose output includes a section named What this local snapshot cannot tell you. The JSON output keeps the same review context in machine-readable form.

Free Commands

These commands do not need CRA_EVIDENCE_API_KEY:

CI Examples

GitHub Actions:

jobs:
  cra-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pipx install craevidence
      - run: craevidence check . --fail-on known-exploited

GitLab CI:

cra-check:
  image: python:3.12-slim
  script:
    - pip install craevidence
    - craevidence check . --fail-on known-exploited

Account Commands

Commands that upload evidence or read CRA Evidence release state need an API key:

export CRA_EVIDENCE_API_KEY=...
craevidence create-version --product my-product --version 1.0.0
craevidence upload-sbom --product my-product --version 1.0.0 --file sbom.cdx.json
craevidence status --product my-product --version 1.0.0

create-version creates a draft under an existing product without uploading new evidence. CRA Evidence automatically links reusable product-level documents and templates to the version. This is useful when source-code findings need a version before an SBOM is available:

craevidence create-version --product my-product --version 1.0.0
craevidence code-check . --product my-product --version 1.0.0 --upload

code-check runs locally and uploads SARIF findings, not source code. Neither command proves compliance.

The default API URL is:

https://api.craevidence.com

You can override it with:

export CRA_EVIDENCE_URL=https://api.craevidence.com

Environment Variables

Credentials can also be stored in ~/.cra-evidence/config.yaml. Keep that file private, for example with chmod 600 ~/.cra-evidence/config.yaml.

Exit Codes

Exit 0 != compliance. Local output is a snapshot for review and CI policy, not a legal conclusion.

Data Sources

Support

• Website: https://craevidence.com
• Email: support@craevidence.com

License

MIT License. See the package license file for details.