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.

Both modes accept an SBOM you already have. If you do not have one, the CLI generates it from a directory or a container image with its bundled engine, so no separate SBOM tool is required. See Generating an SBOM.

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. Given a directory or an image, it generates the SBOM first. 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.

If Grype returns a valid incomplete assessment, check keeps its findings and reports partial coverage in the report and a notice on stderr instead of replacing them with OSV results. --strict rejects an incomplete Grype assessment. Without --strict, configured finding gates still apply, and exit 0 does not mean every package was assessed.

SBOM license expressions are preserved as written. --deny-license compares complete license strings without evaluating AND, OR, or WITH expressions.

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.

Generating an SBOM

The CLI generates the SBOM itself when you point it at a directory or a container image. It uses the bundled CRA Evidence Grype engine, which embeds the Syft library for package cataloguing, so no separate SBOM tool is needed.

craevidence check .
craevidence check --image ghcr.io/acme/app:1.4.2
craevidence check . --sbom-output sbom.cdx.json

--sbom-output keeps the generated file as a CI artifact. It is ignored when the SBOM was supplied with --sbom.

upload-sbom generates the same way from --image or --source:

craevidence upload-sbom --product my-product --version 1.0.0 --image ghcr.io/acme/app:1.4.2
craevidence upload-sbom --product my-product --version 1.0.0 --source ./src

Both write to a temporary directory that is removed after the upload, so no local copy remains. Use check --sbom-output when you want to keep one.

Generated output is CycloneDX JSON. upload-sbom --format spdx selects SPDX JSON instead. The CLI does not generate XML.

Generation and local matching need the engine, which the supported PyPI platform wheels and the published Docker image bundle. Editable and source-distribution installs do not bundle it, and native Windows generation is not supported. --file uploads an SBOM you already have and needs no engine, so a build that produces its own SBOM can skip generation entirely:

syft ghcr.io/acme/app:1.4.2 -o cyclonedx-json > sbom.cdx.json
craevidence upload-sbom --product my-product --version 1.0.0 --file sbom.cdx.json

Use your own tool when you need XML, a specific cataloguer, path exclusions, or Syft configuration, none of which the bundled engine exposes. check --sbom, eol-check --sbom, egress-check --sbom, and draft --sbom read CycloneDX JSON or SPDX JSON only; upload-sbom --file and validate --sbom also accept .xml, which the server validates.

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 upload-sbom --product my-product --version 1.0.0 --image ghcr.io/acme/app:1.4.2
craevidence status --product my-product --version 1.0.0

upload-sbom takes an SBOM you already have with --file, or generates one from --image or --source. See Generating an SBOM.

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 sanitized SARIF finding metadata, not source code. The bundled pack has 104 rules: 54 run by default and 50 broader rules require --include-experimental; the command reports exact per-language rule counts. Default coverage by language:

• Python: 42 focused rules.
• Go: direct crypto/tls dial calls that disable verification without a custom callback.
• Java: compiler-attested JDK weak-digest calls.
• PHP: fully qualified global \unserialize calls fed from a reviewed HTTP superglobal source.
• C#: the framework accept-any certificate-validator assignment, attested through Roslyn against the signed HttpClientHandler type.
• Rust: literal TLS verification disablement, bound to the exact crates.io reqwest package.
• C and C++: three compiler-attested rules each, covering fixed-array out-of-bounds literal writes, a system printf whose format argument is main's own argv parameter, and direct system-shell commands, through pinned libclang C17 and C++17 profiles.
• JavaScript and TypeScript: assigned odd integer literals above the exact binary64 safe-integer boundary.

The C, C++, C#, Java, and Rust defaults consume a versioned --semantic-evidence envelope produced by code-evidence. Missing, ambiguous, stale, or invalid evidence reports degraded coverage instead of a clean result. Broader rules remain opt-in where corpus precision, parser coverage, type resolution, namespace binding, or intrafile dataflow is insufficient for default use. No group is general SAST coverage for its language. Neither command proves compliance. Exact rule scopes, evidence requirements, and toolchain profiles are documented in Local commands and the rule pack reference.

The default API URL is:

https://api.craevidence.com

You can override it with:

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

For a self-hosted instance, configure the exact API origin and register the same normalized origin as trusted:

export CRA_EVIDENCE_URL=https://cra-api.internal.example
export CRA_EVIDENCE_TRUSTED_ORIGIN=https://cra-api.internal.example
export CRA_EVIDENCE_CA_BUNDLE=/etc/ssl/certs/cra-internal-ca.pem

The API URL and trusted origin must be origins only: scheme, host, and optional port, with no user information, path, query, or fragment. HTTPS is required except for loopback development URLs. The trusted-origin setting suppresses the custom-host typo warning only for an exact normalized match. It is a configuration safeguard, not a security boundary.

CRA_EVIDENCE_CA_BUNDLE selects a PEM CA bundle for account API requests. Without it, the standard SSL_CERT_FILE and SSL_CERT_DIR variables remain available. TLS verification cannot be disabled. See the CI/CD integration guide for runner egress, proxy, GitHub Action, and GitLab Component examples.

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.