Evidence Service

Overview

This page describes how to use the JFrog CLI to create external evidence files, which are then deployed to Artifactory. You can create evidence for:

  • Artifacts

  • Packages

  • Builds

  • Release Bundles v2

Note

The Evidence service requires Artifactory 7.104.2 or above.

The ability to create external evidence files and deploy them to Artifactory requires an Enterprise+ subscription.

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

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

Authentication

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

Package Evidence

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

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>

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>

Command parameters

  1. --predicate file-path Mandatory field. Defines the path to a locally-stored, arbitrary json file that contains the predicates.

{
// any kind of valid json
}

  1. --predicate-type predicate-type-uri Mandatory field. The type of predicate defined by the json file. Sample predicate type uris include:

 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

  1. --key local-private-key-path Optional path for a private key (see Tip below). Supported key types include:

 `rsa`
 `ed25519`
 `ecdsa`

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.

Note

Two key formats are supported: PEM and SSH

  1. --key-alias RSA-1024 Optional case-sensitive name for the public key created from the private key. 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.

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.

  1. --markdown md file Optional path to a file that contains evidence formatted in markdown.

Artifact command parameters

  1. --subject-repo-path target-path Mandatory field. Each evidence file must have a single subject only and must include the path.

  2. --subject-sha256 digest 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

  1. --package-name name Mandatory field.

  2. --package-version version-number Mandatory field.

  3. --package-repo-key repo-name Mandatory field.

Build command parameters

  1. --build-name name Mandatory field unless environment variables are used (see tip below).

  2. --build-number version-number Mandatory field unless environment variables are used (see tip below).

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

  1. --release-bundle name Mandatory field.

  2. --release-bundle-version version-number Mandatory field.

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

evd create --predicate /Users/jsmith/Downloads/code-review.json --predicate-type https://in-toto.io/attestation/vulns --subject-repo-path commons-dev-generic-local/commons/file.txt --subject-sha256 69d29925ba75eca8e67e0ad99d1132b47d599c206382049bc230f2edd2d3af30 --key /Users/jsmith/Documents/keys/private.pem --key-alias xyzey

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

Package Evidence Sample

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-key local-docker --key /Users/jsmith/Documents/keys/private.pem --key-alias xyzey

Build Evidence Sample

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

Release Bundle v2 Evidence Sample

evd create --predicate /Users/jsmith/Downloads/code-review.json --predicate-type https://in-toto.io/attestation/vulns --release-bundle bundledemo --release-bundle-version (mandatory) 1.0.0 --key /Users/jsmith/Documents/keys/private.pem --key-alias xyzey
PreviousCleaning Up Unreferenced Files from a Git LFS RepositoryNextCLI for JFrog Security

Last updated