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:
| Parameter | Default | Description |
|---|---|---|
client-id | Client ID for backend | |
secret | Secret for backend | |
url | https://api.cycode.com | URL for backend |
subjects | A white space seperated list of paths, or base64-encoded subjects. Each path can be file, directory or image reference | |
output-prov | provenance.intoto.jsonl | Path to write provenance statement |
output-signed-prov | provenance.intoto.jsonl.sig | Path to write signed provenance statement |
output-cert | cert.pem | Path to write short-lived certificate |
key | Path to a private ECDSA/RSA key used to sign provenance statement | |
keyless | false | Use keyless signing and verifying |
include-timestamp | false | Allow timestamping of the artifact signature |
tlog-upload | true | Upload the signature to the transparency log |
rekor-server-url | https://rekor.sigstore.dev | Rekor server URL |
fulcio-server-url | https://fulcio.sigstore.dev | Fulcio server URL |
timestamp-server-url | Timestamp server URL | |
yes | false | Agree to submit data to an immutable public transparency log (Needed for public Sigstore) |
report-job-summary | false | Enable to report provenance through a job summary (supported for GitHub, Azure, and Buildkite) |
report-artifact | false | Enable to upload provenance through an artifact (supported for Azure and GitLab) |
log-level | info | Log level (trace, debug, info, warn, error) |
verbose | false | Verbose 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:
| Parameter | Default | Description |
|---|---|---|
client-id | Client ID for backend | |
secret | Secret for backend | |
url | https://api.cycode.com | URL for backend |
subjects | A white space seperated list of paths, or base64-encoded subjects. Each path can be file, directory or image reference | |
signed-prov | holds path to read and verify a signed provenance statement. If provided, the backend is not queried for provenance. | |
key | Path to a public RSA or ECDSA key used to verify provenance statement signature | |
cert | Path to the public certificate | |
cert-chain | Path to a list of CA certificates in PEM format | |
keyless | false | Use keyless signing and verifying |
ignore-timestamp | false | Skip timestamp verification |
ignore-tlog | false | Skip transparency log verification |
rekor-server-url | https://rekor.sigstore.dev | Rekor server URL |
fulcio-server-url | https://fulcio.sigstore.dev | Fulcio server URL |
timestamp-server-url | Timestamp server URL | |
verify-repo | Repository name to verify against the attestation | |
verify-repo-regex | Repository regex to verify against the attestation | |
verify-ref | Ref to verify against the attestation | |
verify-ref-regex | Ref regex to verify against the attestation | |
verify-cert-oidc-issuer | OIDC issuer to verify against the attestation | |
verify-cert-oidc-issuer-regex | OIDC issuer regex to verify against the attestation | |
verify-hosted-only | Verify only attestation from hosted runners | |
log-level | info | Log level (trace, debug, info, warn, error) |
verbose | false | Verbose 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`,