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 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.