Evidence Service

Overview

Artifactory enables you to attach evidence (signed metadata) to a designated subject, such as an artifact, build, package, or Release Bundle v2. These evidence files act as attestations, providing a signed and verified record of an external process performed on the subject, for example, test results, vulnerability scans, and official approvals.

JFrog's Evidence service generates an audit trail that documents all the security, quality, and operational steps performed to produce a production-ready software release. It provides a seamless way to consolidate information from the tools and platforms used in software development into a single source of truth that you can track and verify for governance and compliance.

This page describes how to:

Notes

  • The Evidence service requires Artifactory 7.104.2 or above.

  • The ability for users to attach external evidence to Artifactory, as described here, requires an Enterprise+ subscription.

  • The ability to collect internal evidence generated by Artifactory requires a Pro subscription or above. Internal evidence generated by Xray requires a Pro X subscription or above.

  • In the current release, an evidence file can be signed with one key only.

  • The maximum size evidence file supported by Artifactory is 16MB.

Click this link for a collection of code snippets that describe how to create evidence workflows in various tools using the JFrog CLI.

Click this link for a collection of code snippets that describe how to create evidence workflows in various tools using the JFrog CLI.

For more information about the API used for deploying evidence to Artifactory, see Deploy Evidence.

Create Evidence

The Create Evidence command creates external evidence files, which are then deployed to Artifactory. You can create evidence for:

Authentication

To create and deploy external evidence, use an access token or the web login mechanism for authentication. Basic authentication (username/password) is not supported.

Syntax

JFrog CLI uses the following syntax for creating evidence:

Artifact Evidence

jf evd create --predicate file-path --predicate-type predicate-type-uri --subject-repo-path <target-path> --subject-sha256 <digest> --key <local-private-key-path> --key-alias <public-key-name> --provider-id <provider-id>

Package Evidence

jf evd create --predicate file-path --predicate-type predicate-type-uri --package-name <name> --package-version <version-number> --package-repo-name <repo-name> --key <local-private-key-path> --key-alias <public-key-name> --provider-id <provider-id>

Build Evidence

jf evd create --predicate file-path --predicate-type predicate-type-uri --build-name <name> --build-number <version-number> --key <local-private-key-path> --key-alias <public-key-name> --provider-id <provider-id>

Release Bundle v2 Evidence

jf evd create --predicate file-path --predicate-type predicate-type-uri --release-bundle <name> --release-bundle-version <version-number> --key <local-private-key-path> --key-alias <public-key-name> --provider-id <provider-id>

Command parameters

Parameter
Required/Optional
Description

--predicate file-path

required

Defines the path to a locally-stored, arbitrary JSON file that contains the predicate (the content of the evidence).

--predicate-type predicate-type-uri

required

The type of predicate defined by the JSON file. Sample predicate type URIs:

https://in-toto.io/attestation/link/v0.3
https://in-toto.io/attestation/scai/attribute-report
https://in-toto.io/attestation/runtime-trace/v0.1
https://in-toto.io/attestation/test-result/v0.1
https://in-toto.io/attestation/vulns

--key local-private-key-path

optional

Path to a private key (see Tip below). Supported key types: 'rsa', 'ed25519', 'ecdsa' Supported key formats: PEM and SSH

--key-alias RSA-1024

optional

Case-sensitive name for the public key created from the private key (see Tip below). The public key is used to verify the DSSE envelope that contains the evidence.

  • If the key-alias is included, DSSE verification will fail if the same key-name is not found in Artifactory.

  • If the key-alias is not included, DSSE verification with the public key is not performed during creation.

--markdown md-file

optional

Path to a file that contains evidence in Markdown format.

--project project-name

optional

Name of the project associated with the evidence subject. This argument can be used with build, package, and Release Bundle evidence.

--provider-id

optional

Name of the provider that created the evidence.

--sigstore-bundle

optional

Path to a Sigstore bundle file containing a pre-signed DSSE envelope. If the evidence subject is not provided (using --subject-repo-path), Artifactory attempts to resolve the subject automatically from the DSSE envelope. Any subject resolution errors have exit code 2. --sigstore-bundle is incompatible with --key, --key-alias, --predicate, --predicate-type, and --subject-sha256.

Tip

You can define the key using the JFROG_CLI_SIGNING_KEY environment variable as an alternative to using the --key command parameter. If the environment variable is not defined, the --key command is mandatory.

Tip

You can define a key alias using the JFROG_CLI_KEY_ALIAS environment variable as an alternative to using the --key-alias command parameter.

Note

In the unlikely event the public key is deleted from Artifactory, it may take up to 4 hours for the Evidence service to clear the key from the cache. Evidence can still be signed with the deleted key during this time.

Artifact command parameters

Parameter
Required/Optional
Description

--subject-repo-path

required

The target path of the artifact. Each evidence file must contain a single subject and include the path.

Artifacts located in local repositories aggregated inside virtual repositories are supported (evidence is added to the local path).

--subject-sha256

optional

Optional digest (sha256) of the artifact.

  • If a digest is provided, it is verified against the subject's sha256 as it appears in Artifactory.

  • If a digest is not provided, the sha256 is taken from the path in Artifactory.

Package command parameters

Parameter
Required/Optional
Description

--package-name

required

The package name.

--package-version

required

The package version.

--package-repo-name

required

The package repository name.

Build command parameters

Parameter
Required/Optional
Description

--build-name

required (unless environment variables are used - see tip below)

The build name.

--build-number

required (unless environment variables are used - see tip below)

The build number.

Tip

You can use the FROG_CLI_BUILD_NAME and FROG_CLI_BUILD_NUMBER environment variables as an alternative to the build command parameters.

Release Bundle v2 command parameters

Parameter
Required/Optional
Description

--release-bundle

required

Release Bundle name.

--release-bundle-version

required

Release Bundle version.

Note

When DSSE verification is successful, the following message is displayed:

Evidence successfully created and verified.

When DSSE verification is unsuccessful, the following message is displayed:

Evidence successfully created but not verified due to missing/invalid public key.

Sample commands

Artifact Evidence sample

jf evd create --subject-repo-path example-generic/file.txt --subject-sha256 7afd53a30794391969dd598dcae4daecd123ec7059b801c62a53c51b1ff17c21 --key private.pem --key-alias my-key-alias --predicate predicate.json --predicate-type https://jfrog.com/evidence/approval/v1 --provider-id gradle

In the sample above, the command creates a signed evidence file with a predicate type of SLSA provenance for an artifact named file.txt. The evidence was provided by gradle.

Package Evidence sample

jf evd create --predicate /Users/jsmith/Downloads/code-review.json --predicate-type https://in-toto.io/attestation/vulns --package-name DockerPackage --package-version 1.0.0 --package-repo-name local-docker --key /Users/jsmith/Documents/keys/private.pem --key-alias xyzey

Build Evidence sample

jf evd create --predicate /Users/jsmith/Downloads/code-review.json --predicate-type https://in-toto.io/attestation/vulns --build-name DockerBuild --build-number 1.0.0 --key /Users/jsmith/Documents/keys/private.pem --key-alias xyzey

Release Bundle v2 Evidence sample

jf evd create --predicate /Users/jsmith/Downloads/code-review.json --predicate-type https://in-toto.io/attestation/vulns --release-bundle bundledemo --release-bundle-version 1.0.0 --key /Users/jsmith/Documents/keys/private.pem --key-alias xyzey

Sigstore Bundle Evidence sample

jf evd create --sigstore-bundle bundle.json

Get Evidence

The Get Evidence command exports a list of all evidence associated with an artifact or a Release Bundle v2.

Note

You can also get evidence using a GraphQL API command. For more information, see Get Evidence.

Syntax

JFrog CLI uses the following syntax for getting evidence:

Artifact Evidence

jf evd get --subject-repo-path <target-path> --output <file-name>

Release Bundle v2 Evidence

jf evd get --release-bundle <name> --release-bundle-version <version-number> --output <file-name>

Command parameters

Parameter
Required/Optional
Description

--output

required

Name of the file to which evidence is exported.

--include-predicate

optional

Flag that determines whether the predicate is included in the exported file. By default, the predicate is not included.

--format

optional

Enables extended output. Supported formats: 'json', 'jsonl'

Tip

We recommend not to include the predicate if the evidence list is large, as the predicate will have a significant impact on file size.

Artifact command parameters

Parameter
Required/Optional
Description

--subject-repo-path

required

The path of the evidence target. Each evidence file must contain a single subject and must include the path. Artifacts located in local repositories that are aggregated inside virtual repositories are supported.

Release Bundle v2 command parameters

Parameter
Required/Optional
Description

--release-bundle

required

The Release Bundle name.

--release-bundle-version

required

The Release Bundle version.

--artifacts-limit

optional

The maximum number of artifacts in the Release Bundle to include in the evidence list. The default is 1000 artifacts.

Sample commands

Artifact Get Evidence sample

jf evd get --subject-repo-path commons-dev-generic-local/commons/file.txt --output my-evidences.json

In the sample above, the command exports the evidence list for an artifact named file.txt.

Release Bundle v2 Evidence sample

jf evd get --release-bundle bundledemo --release-bundle-version 1.0.0 --artifacts-limit 100 --output /Users/dort/evidence-verifyers/bundle-demo/evidence-list.json

In the sample above, the command exports the evidence list for the 100 artifacts in the Release Bundle, including builds if relevant.

Verify Evidence

The Verify Evidence command provides client-side verification that the evidence related to a given subject has not been altered. Verification of artifact integrity is performed using a checksum (digest), and attestation signatures are validated using public keys.

This command can be run on a variety of evidence subjects, including artifacts, packages, builds, and Release Bundles. It requires you to define the evidence subject and the keys to use for verification.

Syntax

JFrog CLI uses the following syntax for verifying evidence:

Artifact Evidence

jf evd verify --subject-repo-path <target-path> --public-keys <key-array>

Package Evidence

jf evd verify --package-name <package-name> --package-version <package-version> --public-keys <key-array>

Build Evidence

jf evd verify --build-name <build-name> --build-number <build-number> --public-keys <key-array>

Release Bundle v2 Evidence

jf evd verify --release-bundle <name> --release-bundle-version <version-number> --public-keys <key-array>

Command parameters

Parameter
Required/Optional
Description

--public-keys

required (unless the --use-artifactory-keys parameter is used)

An array of public keys to use for signature verification with ";" separator. Supported key types: 'ecdsa', 'rsa', 'ed25519'

--project

optional

The project key associated with the created evidence.

--format

optional

Enables extended output. Supported formats: 'json', 'jsonl'

--use-artifactory-keys

optional

Default: false When enabled, the command retrieves keys from Artifactory to perform verification.

Artifact parameters

Parameter
Required/Optional
Description

--subject-repo-path

optional

The full path to the evidence subject.

Package parameters

Parameter
Required/Optional
Description

--package-name

optional

The package name.

--package-repo-name

optional

The package repository name.

--package-version

optional

The package version.

Build parameters

Parameter
Required/Optional
Description

--build-name

optional

The build name.

--build-number

optional

The build number.

Release Bundle parameters

Parameter
Required/Optional
Description

--release-bundle

optional

The Release Bundle name.

--release-bundle-version

optional

The Release Bundle version.

Sample command

The following command verifies Sigstore bundle evidence on an artifact using keys retrieved from Artifactory.

Subject sha256:        4bf2da010af20d8ed0364caf14f90bcab22b312520c68b9a01bb3479ba9a742c
Subject:               cli-sigstore-test/readme.txt
Loaded 3 evidence

Verification passed for 3 out of 3 evidence

- Evidence 1:
    - Media type:                            sigstore.bundle
    - Predicate type:                        in-toto
    - Evidence subject sha256:               4bf2da010af20d8ed0364caf14f90bcab22b312520c68b9a01bb3479ba9a742c
    - Key source:                            Sigstore Bundle Key
    - Sigstore verification status:          success
- Evidence 2:
    - Media type:                            evidence.dsse
    - Predicate type:                        application/vnd.in-toto+json
    - Evidence subject sha256:               4bf2da010af20d8ed0364caf14f90bcab22b312520c68b9a01bb3479ba9a742c
    - Key source:                            User Provided Key
    - Key fingerprint:                       /IyvutGSsuTPykv+mGtG4sph4TGh3Cl4HRNxbEZo1z4=
    - Sha256 verification status:            success
    - Signatures verification status:        success
- Evidence 3:
    - Media type:                            evidence.dsse
    - Predicate type:                        vulnerability-scan
    - Evidence subject sha256:               4bf2da010af20d8ed0364caf14f90bcab22b312520c68b9a01bb3479ba9a742c
    - Key source:                            Artifactory Key
    - Key fingerprint:                       uz1SAgymeLMkH+lJ5ROCvbTCCnbwgUgy3zeDAR4J47k=
    - Sha256 verification status:            success
    - Signatures verification status:        success

JSON format output

The attached file contains sample JSON format output.

14KB
verification_result.json
PreviousCleaning Up Unreferenced Files from a Git LFS RepositoryNextCLI for JFrog Security

Last updated