Skip to main content

CLI

In some cases, we don't have an extension for installing and running Cimon. This is either due to a lack of infrastructure or to the requirement to install it manually. In such cases, we've provided methods for installing and executing Cimon. Our extensions (GitHub Actions and Azure Pipelines) do precisely that behind the scenes.

Installation Cimon CLI

The quickest way to install Cimon CLI is with the install script. It will automatically select the latest version according to the architecture. The default folder for the installation is ./bin:

curl -sSfL https://cimon-releases.s3.amazonaws.com/install.sh | sh -s -- -h

sh: download go binaries for Cimon
Usage: sh [-b] bindir [-d] [tag]
-b sets bindir or installation directory, Defaults to ./bin
-d turns on debug logging
[tag] is a tag from
https://github.com/cycodelabs/cimon-releases/releases
If tag is missing, then the latest will be used.

Examples

Fetching the latest version to ./bin

curl -sSfL https://cimon-releases.s3.amazonaws.com/install.sh | sh

Installing Cimon to a path that is already included in the PATH variable, but it will require higher privileges:

curl -sSfL https://cimon-releases.s3.amazonaws.com/install.sh | sudo sh -s -- -b /usr/local/bin

cimon -h

Fetching a specific version tag

curl -sSfL https://cimon-releases.s3.amazonaws.com/install.sh | sh -s -- v0.10.0

Cimon Attest Sub-commands

generate-and-sign

Attest and optionally sign supplied subjects (aka artifacts).

Parameters

Here are the parameters that are supported:

ParameterDefaultDescription
client-idClient ID for backend
secretSecret for backend
urlhttps://api.cycode.comURL for backend
subjectsA white space seperated list of paths, or base64-encoded subjects. Each path can be file, directory or image reference
output-provprovenance.intoto.jsonlPath to write provenance statement
output-signed-provprovenance.intoto.jsonl.sigPath to write signed provenance statement
output-certcert.pemPath to write short-lived certificate
keyPath to a private ECDSA/RSA key used to sign provenance statement
keylessfalseUse keyless signing and verifying
include-timestampfalseAllow timestamping of the artifact signature
tlog-uploadtrueUpload the signature to the transparency log
rekor-server-urlhttps://rekor.sigstore.devRekor server URL
fulcio-server-urlhttps://fulcio.sigstore.devFulcio server URL
timestamp-server-urlTimestamp server URL
yesfalseAgree to submit data to an immutable public transparency log (Needed for public Sigstore)
report-job-summaryfalseEnable to report provenance through a job summary (supported for GitHub, Azure, and Buildkite)
report-artifactfalseEnable to upload provenance through an artifact (supported for Azure and GitLab)
log-levelinfoLog level (trace, debug, info, warn, error)
verbosefalseVerbose output (debug level)

Examples

Generate provenace for a single file

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects dist/artifact

Generate provenance for multiple files

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects "dist/artifact1 dist/artifact2"

Generate provenance for a directory

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects dist/

Generate provenance for a docker image (referenced by digest)

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects cycodelabs/cimon@sha256:<digest>

Generate provenance for a docker image (referenced by tag)

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects cycodelabs/cimon:v0.10.0

Generate and sign provenance using a private key

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects artifact.txt --key private.pem

Generate and sign provenance using keyless signing with public Sigstore

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects artifact.txt --keyless  --yes

Generate and sign provenance using keyless signing with private infrastructure

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects artifact.txt --keyless --rekor-server-url <rekor-server> --fulcio-server-url <fulcio-server>

Generate and sign provenance using keyless signing with timestamping instead of transparency log

cimon attest generate-and-sign --client-id <client-id> --secret <secret> --subjects artifact.txt --keyless --fulcio-server-url <fulcio-server> --timestamp-server-url <ts-server>` -->

verify

Verify attestation content and signature (optional).

Parameters

Here are the parameters that are supported:

ParameterDefaultDescription
client-idClient ID for backend
secretSecret for backend
urlhttps://api.cycode.comURL for backend
subjectsA white space seperated list of paths, or base64-encoded subjects. Each path can be file, directory or image reference
signed-provholds path to read and verify a signed provenance statement. If provided, the backend is not queried for provenance.
keyPath to a public RSA or ECDSA key used to verify provenance statement signature
certPath to the public certificate
cert-chainPath to a list of CA certificates in PEM format
keylessfalseUse keyless signing and verifying
ignore-timestampfalseSkip timestamp verification
ignore-tlogfalseSkip transparency log verification
rekor-server-urlhttps://rekor.sigstore.devRekor server URL
fulcio-server-urlhttps://fulcio.sigstore.devFulcio server URL
timestamp-server-urlTimestamp server URL
verify-repoRepository name to verify against the attestation
verify-repo-regexRepository regex to verify against the attestation
verify-refRef to verify against the attestation
verify-ref-regexRef regex to verify against the attestation
verify-cert-oidc-issuerOIDC issuer to verify against the attestation
verify-cert-oidc-issuer-regexOIDC issuer regex to verify against the attestation
verify-hosted-onlyVerify only attestation from hosted runners
log-levelinfoLog level (trace, debug, info, warn, error)
verbosefalseVerbose output (debug level)

Examples

Verify attestation for a given subject

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact

Verify attestation for a several subjects

cimon attest verify --client-id <client-id> --secret <secret> --subjects "dist/artifact1 dist/artifact2"

Verify attestation for a docker image

cimon attest verify --client-id <client-id> --secret <secret> --subjects cycodelabs/cimon:v0.10.0

Verify given attestation against provided subjects

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --signed-prov provenance.intoto.jsonl.sig

Verify attestation with a public key

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --key public.pem

Verify attestation with a certificate (by using its public key)

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --cert cert.pem

Verify attestation with a certificate and a chain of certificates

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --cert cert.pem --cert-chain chain.pem

Verify attestation using keyless mode with public Sigstore

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --keyless

Verify attestation using keyless mode with private infrastructure

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --keyless --rekor-server-url https://rekor.example.com --fulcio-server-url https://fulcio.example.com

Verify attestation using keyless mode with timestamp server

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --keyless --fulcio-server-url https://fulcio.example.com --timestamp-server-url https://timestamp.example.com

Verify attestation created by a specific repository

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --verify-repo https://github.com/CycodeLabs/example-repo

Verify attestation created by a repository matching a regex

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --verify-repo-regex ".*/CycodeLabs/.*"

Verify attestation created by a specific ref

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --verify-ref main

Verify attestation created from github hosted runners

cimon attest verify --client-id <client-id> --secret <secret> --subjects dist/artifact --verify-cert-oidc-issuer https://token.actions.githubusercontent.com --verify-hosted-only`,