diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..ecbda72db --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +# This file is documented at https://git-scm.com/docs/gitattributes. +# Linguist-specific attributes are documented at +# https://github.com/github/linguist. + +doc/cosign*.md linguist-generated=true diff --git a/.github/workflows/verify-docgen.yaml b/.github/workflows/verify-docgen.yaml new file mode 100644 index 000000000..21c1c2f8e --- /dev/null +++ b/.github/workflows/verify-docgen.yaml @@ -0,0 +1,30 @@ +# +# Copyright 2021 The Sigstore Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Docgen + +on: [push, pull_request] + +jobs: + docgen: + name: Verify Docgen + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-go@v2 + with: + go-version: '1.17.x' + - run: ./cmd/help/verify.sh diff --git a/cmd/cosign/cli/commands.go b/cmd/cosign/cli/commands.go index d9b4f4d02..12cd98baa 100644 --- a/cmd/cosign/cli/commands.go +++ b/cmd/cosign/cli/commands.go @@ -31,7 +31,8 @@ var ( func New() *cobra.Command { cmd := &cobra.Command{ - Use: "cosign", + Use: "cosign", + DisableAutoGenTag: true, PersistentPreRunE: func(cmd *cobra.Command, args []string) error { if ro.OutputFile != "" { out, err := os.Create(ro.OutputFile) diff --git a/cmd/cosign/main.go b/cmd/cosign/main.go index fcc8942ec..b82fb6d12 100644 --- a/cmd/cosign/main.go +++ b/cmd/cosign/main.go @@ -1,4 +1,3 @@ -// // Copyright 2021 The Sigstore Authors. // // Licensed under the Apache License, Version 2.0 (the "License"); diff --git a/cmd/help/main.go b/cmd/help/main.go new file mode 100644 index 000000000..a3f059356 --- /dev/null +++ b/cmd/help/main.go @@ -0,0 +1,42 @@ +// Copyright 2021 The Sigstore Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package main + +import ( + "fmt" + "os" + + "github.com/sigstore/cosign/cmd/cosign/cli" + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +func main() { + var dir string + root := &cobra.Command{ + Use: "gendoc", + Short: "Generate cosign's help docs", + SilenceUsage: true, + Args: cobra.NoArgs, + RunE: func(*cobra.Command, []string) error { + return doc.GenMarkdownTree(cli.New(), dir) + }, + } + root.Flags().StringVarP(&dir, "dir", "d", "doc", "Path to directory in which to generate docs") + if err := root.Execute(); err != nil { + fmt.Println(err) + os.Exit(1) + } +} diff --git a/cmd/help/verify.sh b/cmd/help/verify.sh new file mode 100755 index 000000000..43fe6f388 --- /dev/null +++ b/cmd/help/verify.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash + +# Copyright 2021 The Sigstore Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +set -e + +# Verify that generated Markdown docs are up-to-date. +tmpdir=$(mktemp -d) +go run cmd/help/main.go --dir "$tmpdir" +echo "###########################################" +echo "If diffs are found, run: go run ./cmd/help/" +echo "###########################################" +diff -Naur "$tmpdir" doc/ diff --git a/doc/cosign.md b/doc/cosign.md new file mode 100644 index 000000000..99594cc45 --- /dev/null +++ b/doc/cosign.md @@ -0,0 +1,37 @@ +## cosign + + + +### Options + +``` + -h, --help help for cosign + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign attach](cosign_attach.md) - Provides utilities for attaching artifacts to other artifacts in a registry +* [cosign attest](cosign_attest.md) - Attest the supplied container image. +* [cosign clean](cosign_clean.md) - Remove all signatures from an image. +cosign clean +* [cosign copy](cosign_copy.md) - Copy the supplied container image and signatures. +* [cosign dockerfile](cosign_dockerfile.md) - Provides utilities for discovering images in and performing operations on Dockerfiles +* [cosign download](cosign_download.md) - Provides utilities for downloading artifacts and attached artifacts in a registry +* [cosign generate](cosign_generate.md) - Generates (unsigned) signature payloads from the supplied container image. +* [cosign generate-key-pair](cosign_generate-key-pair.md) - Generates a key-pair. +* [cosign initialize](cosign_initialize.md) - Initializes SigStore root to retrieve trusted certificate and key targets for verification. +* [cosign manifest](cosign_manifest.md) - Provides utilities for discovering images in and performing operations on Kubernetes manifests +* [cosign policy](cosign_policy.md) - subcommand to manage a keyless policy. +* [cosign public-key](cosign_public-key.md) - Gets a public key from the key-pair. +* [cosign sign](cosign_sign.md) - Sign the supplied container image. +* [cosign sign-blob](cosign_sign-blob.md) - Sign the supplied blob, outputting the base64-encoded signature to stdout. +* [cosign triangulate](cosign_triangulate.md) - Outputs the located cosign image reference. This is the location cosign stores the specified artifact type. +cosign triangulate +* [cosign upload](cosign_upload.md) - Provides utilities for uploading artifacts to a registry +* [cosign verify](cosign_verify.md) - Verify a signature on the supplied container image +* [cosign verify-attestation](cosign_verify-attestation.md) - Verify an attestation on the supplied container image +* [cosign verify-blob](cosign_verify-blob.md) - Verify a signature on the supplied blob +* [cosign version](cosign_version.md) - Prints the cosign version + diff --git a/doc/cosign_attach.md b/doc/cosign_attach.md new file mode 100644 index 000000000..cd3fddbb7 --- /dev/null +++ b/doc/cosign_attach.md @@ -0,0 +1,23 @@ +## cosign attach + +Provides utilities for attaching artifacts to other artifacts in a registry + +### Options + +``` + -h, --help help for attach +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - +* [cosign attach sbom](cosign_attach_sbom.md) - Attach sbom to the supplied container image +* [cosign attach signature](cosign_attach_signature.md) - Attach signatures to the supplied container image + diff --git a/doc/cosign_attach_sbom.md b/doc/cosign_attach_sbom.md new file mode 100644 index 000000000..d97c7c345 --- /dev/null +++ b/doc/cosign_attach_sbom.md @@ -0,0 +1,34 @@ +## cosign attach sbom + +Attach sbom to the supplied container image + +``` +cosign attach sbom [flags] +``` + +### Examples + +``` + cosign attach sbom +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -h, --help help for sbom + --sbom string path to the sbom, or {-} for stdin + --type string type of sbom (spdx|cyclonedx) (default "spdx") +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign attach](cosign_attach.md) - Provides utilities for attaching artifacts to other artifacts in a registry + diff --git a/doc/cosign_attach_signature.md b/doc/cosign_attach_signature.md new file mode 100644 index 000000000..10aeb8370 --- /dev/null +++ b/doc/cosign_attach_signature.md @@ -0,0 +1,34 @@ +## cosign attach signature + +Attach signatures to the supplied container image + +``` +cosign attach signature [flags] +``` + +### Examples + +``` + cosign attach signature +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -h, --help help for signature + --payload string path to the payload covered by the signature (if using another format) + --signature string the signature, path to the signature, or {-} for stdin +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign attach](cosign_attach.md) - Provides utilities for attaching artifacts to other artifacts in a registry + diff --git a/doc/cosign_attest.md b/doc/cosign_attest.md new file mode 100644 index 000000000..eb10102f5 --- /dev/null +++ b/doc/cosign_attest.md @@ -0,0 +1,64 @@ +## cosign attest + +Attest the supplied container image. + +``` +cosign attest [flags] +``` + +### Examples + +``` + cosign attest --key | [--predicate ] [--a key=value] [--upload=true|false] [--f] [--r] + + # attach an attestation to a container image Google sign-in (experimental) + COSIGN_EXPERIMENTAL=1 cosign attest --predicate --type + + # attach an attestation to a container image with a local key pair file + cosign attest --predicate --type --key cosign.key + + # attach an attestation to a container image with a key pair stored in Azure Key Vault + cosign attest --predicate --type --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] + + # attach an attestation to a container image with a key pair stored in AWS KMS + cosign attest --predicate --type --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] + + # attach an attestation to a container image with a key pair stored in Google Cloud KMS + cosign attest --predicate --type --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]/versions/[VERSION] + + # attach an attestation to a container image with a key pair stored in Hashicorp Vault + cosign attest --predicate --type --key hashivault://[KEY] + + # attach an attestation to a container image which does not fully support OCI media types + COSIGN_DOCKER_MEDIA_TYPES=1 cosign attest --predicate --type --key cosign.key legacy-registry.example.com/my/image +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + --cert string path to the x509 certificate to include in the Signature + -f, --force skip warnings and confirmations + --fulcio-url string [EXPERIMENTAL] address of sigstore PKI server (default "https://fulcio.sigstore.dev") + -h, --help help for attest + --identity-token string [EXPERIMENTAL] identity token to use for certificate from fulcio + --key string path to the private key file, KMS URI or Kubernetes Secret + --predicate string path to the predicate file. + -r, --recursive if a multi-arch image is specified, additionally sign each discrete image + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) + --type string specify predicate type (default: custom) (slsaprovenance|link|spdx) (default "custom") + --upload whether to upload the signature (default true) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_clean.md b/doc/cosign_clean.md new file mode 100644 index 000000000..00bce2564 --- /dev/null +++ b/doc/cosign_clean.md @@ -0,0 +1,31 @@ +## cosign clean + +Remove all signatures from an image. +cosign clean + +### Synopsis + +Remove all signatures from an image. + +``` +cosign clean [flags] +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -h, --help help for clean +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_copy.md b/doc/cosign_copy.md new file mode 100644 index 000000000..e090672de --- /dev/null +++ b/doc/cosign_copy.md @@ -0,0 +1,43 @@ +## cosign copy + +Copy the supplied container image and signatures. + +``` +cosign copy [flags] +``` + +### Examples + +``` + cosign copy + + # copy a container image and its signatures + cosign copy example.com/src:latest example.com/dest:latest + + # copy the signatures only + cosign copy --sig-only example.com/src example.com/dest + + # overwrite destination image and signatures + cosign copy -f example.com/src example.com/dest +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -f, --force overwrite destination image(s), if necessary + -h, --help help for copy + --sig-only only copy the image signature +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_dockerfile.md b/doc/cosign_dockerfile.md new file mode 100644 index 000000000..009fe359d --- /dev/null +++ b/doc/cosign_dockerfile.md @@ -0,0 +1,22 @@ +## cosign dockerfile + +Provides utilities for discovering images in and performing operations on Dockerfiles + +### Options + +``` + -h, --help help for dockerfile +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - +* [cosign dockerfile verify](cosign_dockerfile_verify.md) - Verify a signature on the base image specified in the Dockerfile + diff --git a/doc/cosign_dockerfile_verify.md b/doc/cosign_dockerfile_verify.md new file mode 100644 index 000000000..878979ef5 --- /dev/null +++ b/doc/cosign_dockerfile_verify.md @@ -0,0 +1,79 @@ +## cosign dockerfile verify + +Verify a signature on the base image specified in the Dockerfile + +### Synopsis + +Verify signature and annotations on images in a Dockerfile by checking claims +against the transparency log. + +Shell-like variables in the Dockerfile's FROM lines will be substituted with values from the OS ENV. + +``` +cosign dockerfile verify [flags] +``` + +### Examples + +``` + cosign dockerfile verify --key || + + # verify cosign claims and signing certificates on the FROM images in the Dockerfile + cosign dockerfile verify + + # only verify the base image (the last FROM image) + cosign dockerfile verify --base-image-only + + # additionally verify specified annotations + cosign dockerfile verify -a key1=val1 -a key2=val2 + + # (experimental) additionally, verify with the transparency log + COSIGN_EXPERIMENTAL=1 cosign dockerfile verify + + # verify images with public key + cosign dockerfile verify --key cosign.pub + + # verify images with public key provided by URL + cosign dockerfile verify --key https://host.for/ + + # verify images with public key stored in Azure Key Vault + cosign dockerfile verify --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] + + # verify images with public key stored in AWS KMS + cosign dockerfile verify --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] + + # verify images with public key stored in Google Cloud KMS + cosign dockerfile verify --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] + + # verify images with public key stored in Hashicorp Vault + cosign dockerfile verify --key hashivault://[KEY] +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -a, --annotations strings extra key=value pairs to sign + --attachment string related image attachment to sign (sbom), default none + --base-image-only only verify the base image (the last FROM image in the Dockerfile) + --cert-email string the email expected in a valid fulcio cert + --check-claims whether to check the claims found (default true) + -h, --help help for verify + --key string path to the private key file, KMS URI or Kubernetes Secret + -o, --output string output format for the signing image information (json|text) (default "json") + --rekor-url string [EXPERIMENTAL] address of rekor STL server (default "https://rekor.sigstore.dev") + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign dockerfile](cosign_dockerfile.md) - Provides utilities for discovering images in and performing operations on Dockerfiles + diff --git a/doc/cosign_download.md b/doc/cosign_download.md new file mode 100644 index 000000000..138c1c84b --- /dev/null +++ b/doc/cosign_download.md @@ -0,0 +1,23 @@ +## cosign download + +Provides utilities for downloading artifacts and attached artifacts in a registry + +### Options + +``` + -h, --help help for download +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - +* [cosign download sbom](cosign_download_sbom.md) - Download SBOMs from the supplied container image +* [cosign download signature](cosign_download_signature.md) - Download signatures from the supplied container image + diff --git a/doc/cosign_download_sbom.md b/doc/cosign_download_sbom.md new file mode 100644 index 000000000..6c6c692f8 --- /dev/null +++ b/doc/cosign_download_sbom.md @@ -0,0 +1,32 @@ +## cosign download sbom + +Download SBOMs from the supplied container image + +``` +cosign download sbom [flags] +``` + +### Examples + +``` + cosign download sbom +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -h, --help help for sbom +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign download](cosign_download.md) - Provides utilities for downloading artifacts and attached artifacts in a registry + diff --git a/doc/cosign_download_signature.md b/doc/cosign_download_signature.md new file mode 100644 index 000000000..8f658e1a9 --- /dev/null +++ b/doc/cosign_download_signature.md @@ -0,0 +1,32 @@ +## cosign download signature + +Download signatures from the supplied container image + +``` +cosign download signature [flags] +``` + +### Examples + +``` + cosign download signature +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -h, --help help for signature +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign download](cosign_download.md) - Provides utilities for downloading artifacts and attached artifacts in a registry + diff --git a/doc/cosign_generate-key-pair.md b/doc/cosign_generate-key-pair.md new file mode 100644 index 000000000..b4d885857 --- /dev/null +++ b/doc/cosign_generate-key-pair.md @@ -0,0 +1,58 @@ +## cosign generate-key-pair + +Generates a key-pair. + +### Synopsis + +Generates a key-pair for signing. + +``` +cosign generate-key-pair [flags] +``` + +### Examples + +``` + cosign generate-key-pair [--kms KMSPATH] + + # generate key-pair and write to cosign.key and cosign.pub files + cosign generate-key-pair + + # generate a key-pair in Azure Key Vault + cosign generate-key-pair --kms azurekms://[VAULT_NAME][VAULT_URI]/[KEY] + + # generate a key-pair in AWS KMS + cosign generate-key-pair --kms awskms://[ENDPOINT]/[ID/ALIAS/ARN] + + # generate a key-pair in Google Cloud KMS + cosign generate-key-pair --kms gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] + + # generate a key-pair in Hashicorp Vault + cosign generate-key-pair --kms hashivault://[KEY] + + # generate a key-pair in Kubernetes Secret + cosign generate-key-pair k8s://[NAMESPACE]/[NAME] + +CAVEATS: + This command interactively prompts for a password. You can use + the COSIGN_PASSWORD environment variable to provide one. +``` + +### Options + +``` + -h, --help help for generate-key-pair + --kms string create key pair in KMS service to use for signing +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_generate.md b/doc/cosign_generate.md new file mode 100644 index 000000000..aaea65872 --- /dev/null +++ b/doc/cosign_generate.md @@ -0,0 +1,48 @@ +## cosign generate + +Generates (unsigned) signature payloads from the supplied container image. + +### Synopsis + +Generates an unsigned payload from the supplied container image and flags. +This payload matches the one generated by the "cosign sign" command and can be used if you need +to sign payloads with your own tooling or algorithms. + +``` +cosign generate [flags] +``` + +### Examples + +``` + cosign generate [--a key=value] + + # Generate a simple payload for an image + cosign generate + + # Generate a payload with specific annotations + cosign generate -a foo=bar + + # Use this payload in another tool + gpg --output image.sig --detach-sig <(cosign generate ) +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -a, --annotations strings extra key=value pairs to sign + -h, --help help for generate +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_initialize.md b/doc/cosign_initialize.md new file mode 100644 index 000000000..92048d08b --- /dev/null +++ b/doc/cosign_initialize.md @@ -0,0 +1,59 @@ +## cosign initialize + +Initializes SigStore root to retrieve trusted certificate and key targets for verification. + +### Synopsis + +Initializes SigStore root to retrieve trusted certificate and key targets for verification. + +The following options are used by default: + - The initial 1.root.json is embedded inside cosign. + - SigStore current TUF repository is pulled from the GCS mirror at sigstore-tuf-root. + - A default threshold of 3 root signatures is used. + +To provide an out-of-band trusted initial root.json, use the -root flag with a file or URL reference. + +The resulting updated TUF repository will be written to $HOME/.sigstore/root/. + +Trusted keys and certificate used in cosign verification (e.g. verifying Fulcio issued certificates +with Fulcio root CA) are pulled form the trusted metadata. + +``` +cosign initialize [flags] +``` + +### Examples + +``` + cosign initialize -mirror -out + + # initialize root with distributed root keys, default mirror, and default out path. + cosign initialize + + # initialize with an out-of-band root key file. + cosign initialize + + # initialize with an out-of-band root key file and custom repository mirror. + cosign initialize -mirror -root +``` + +### Options + +``` + -h, --help help for initialize + --mirror string GCS bucket to a SigStore TUF repository. (default "sigstore-tuf-root") + --root string path to trusted initial root. defaults to embedded root + --upload int threshold of root key signers (default 3) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_manifest.md b/doc/cosign_manifest.md new file mode 100644 index 000000000..c89e825d2 --- /dev/null +++ b/doc/cosign_manifest.md @@ -0,0 +1,22 @@ +## cosign manifest + +Provides utilities for discovering images in and performing operations on Kubernetes manifests + +### Options + +``` + -h, --help help for manifest +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - +* [cosign manifest verify](cosign_manifest_verify.md) - Verify all signatures of images specified in the manifest + diff --git a/doc/cosign_manifest_verify.md b/doc/cosign_manifest_verify.md new file mode 100644 index 000000000..aaae2c338 --- /dev/null +++ b/doc/cosign_manifest_verify.md @@ -0,0 +1,73 @@ +## cosign manifest verify + +Verify all signatures of images specified in the manifest + +### Synopsis + +Verify all signature of images in a Kubernetes resource manifest by checking claims +against the transparency log. + +``` +cosign manifest verify [flags] +``` + +### Examples + +``` + cosign manifest verify --key || + + # verify cosign claims and signing certificates on images in the manifest + cosign manifest verify + + # additionally verify specified annotations + cosign manifest verify -a key1=val1 -a key2=val2 + + # (experimental) additionally, verify with the transparency log + COSIGN_EXPERIMENTAL=1 cosign manifest verify + + # verify images with public key + cosign manifest verify --key cosign.pub + + # verify images with public key provided by URL + cosign manifest verify --key https://host.for/ + + # verify images with public key stored in Azure Key Vault + cosign manifest verify --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] + + # verify images with public key stored in AWS KMS + cosign manifest verify --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] + + # verify images with public key stored in Google Cloud KMS + cosign manifest verify --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] + + # verify images with public key stored in Hashicorp Vault + cosign manifest verify --key hashivault://[KEY] +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -a, --annotations strings extra key=value pairs to sign + --attachment string related image attachment to sign (sbom), default none + --cert-email string the email expected in a valid fulcio cert + --check-claims whether to check the claims found (default true) + -h, --help help for verify + --key string path to the private key file, KMS URI or Kubernetes Secret + -o, --output string output format for the signing image information (json|text) (default "json") + --rekor-url string [EXPERIMENTAL] address of rekor STL server (default "https://rekor.sigstore.dev") + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign manifest](cosign_manifest.md) - Provides utilities for discovering images in and performing operations on Kubernetes manifests + diff --git a/doc/cosign_policy.md b/doc/cosign_policy.md new file mode 100644 index 000000000..c6d819ff7 --- /dev/null +++ b/doc/cosign_policy.md @@ -0,0 +1,32 @@ +## cosign policy + +subcommand to manage a keyless policy. + +### Synopsis + +policy is used to manage a root.json policy +for keyless signing delegation. This is used to establish a policy for a registry namespace, +a signing threshold and a list of maintainers who can sign over the body section. + +``` +cosign policy [flags] +``` + +### Options + +``` + -h, --help help for policy +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - +* [cosign policy init](cosign_policy_init.md) - generate a new keyless policy. + diff --git a/doc/cosign_policy_init.md b/doc/cosign_policy_init.md new file mode 100644 index 000000000..013966532 --- /dev/null +++ b/doc/cosign_policy_init.md @@ -0,0 +1,43 @@ +## cosign policy init + +generate a new keyless policy. + +### Synopsis + +init is used to generate a root.json policy +for keyless signing delegation. This is used to establish a policy for a registry namespace, +a signing threshold and a list of maintainers who can sign over the body section. + +``` +cosign policy init [flags] +``` + +### Examples + +``` + + # extract public key from private key to a specified out file. + cosign policy init -ns --maintainers {email_addresses} --threshold --expires (days) +``` + +### Options + +``` + -h, --help help for init + -m, --maintainers strings list of maintainers to add to the root policy + --namespace string registry namespace that the root policy belongs to (default "ns") + --out string output policy locally (default "o") + --threshold int threshold for root policy signers (default 1) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign policy](cosign_policy.md) - subcommand to manage a keyless policy. + diff --git a/doc/cosign_public-key.md b/doc/cosign_public-key.md new file mode 100644 index 000000000..6c2cb249a --- /dev/null +++ b/doc/cosign_public-key.md @@ -0,0 +1,57 @@ +## cosign public-key + +Gets a public key from the key-pair. + +### Synopsis + +Gets a public key from the key-pair and +writes to a specified file. By default, it will write to standard out. + +``` +cosign public-key [flags] +``` + +### Examples + +``` + + # extract public key from private key to a specified out file. + cosign public-key --key --outfile + + # extract public key from URL. + cosign public-key --key https://host.for/ --outfile + + # extract public key from Azure Key Vault + cosign public-key --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] + + # extract public key from AWS KMS + cosign public-key --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] + + # extract public key from Google Cloud KMS + cosign public-key --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] + + # extract public key from Hashicorp Vault KMS + cosign public-key --key hashivault://[KEY] +``` + +### Options + +``` + -h, --help help for public-key + --key string path to the private key file, KMS URI or Kubernetes Secret + --outfile string path to a payload file to use rather than generating one + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_sign-blob.md b/doc/cosign_sign-blob.md new file mode 100644 index 000000000..ef8666f18 --- /dev/null +++ b/doc/cosign_sign-blob.md @@ -0,0 +1,61 @@ +## cosign sign-blob + +Sign the supplied blob, outputting the base64-encoded signature to stdout. + +``` +cosign sign-blob [flags] +``` + +### Examples + +``` + cosign sign-blob --key | + + # sign a blob with Google sign-in (experimental) + COSIGN_EXPERIMENTAL=1 cosign sign-blob + + # sign a blob with a local key pair file + cosign sign-blob --key cosign.key + + # sign a blob with a key pair stored in Azure Key Vault + cosign sign-blob --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] + + # sign a blob with a key pair stored in AWS KMS + cosign sign-blob --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] + + # sign a blob with a key pair stored in Google Cloud KMS + cosign sign-blob --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] + + # sign a blob with a key pair stored in Hashicorp Vault + cosign sign-blob --key hashivault://[KEY] +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + --b64 whether to base64 encode the output (default true) + --fulcio-url string [EXPERIMENTAL] address of sigstore PKI server (default "https://fulcio.sigstore.dev") + -h, --help help for sign-blob + --identity-token string [EXPERIMENTAL] identity token to use for certificate from fulcio + --key string path to the private key file, KMS URI or Kubernetes Secret + --oidc-client-id string [EXPERIMENTAL] OIDC client ID for application (default "sigstore") + --oidc-client-secret string [EXPERIMENTAL] OIDC client secret for application + --oidc-issuer string [EXPERIMENTAL] OIDC provider to be used to issue ID token (default "https://oauth2.sigstore.dev/auth") + --output string write the signature to FILE + --rekor-url string [EXPERIMENTAL] address of rekor STL server (default "https://rekor.sigstore.dev") + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_sign.md b/doc/cosign_sign.md new file mode 100644 index 000000000..5a5cf4349 --- /dev/null +++ b/doc/cosign_sign.md @@ -0,0 +1,82 @@ +## cosign sign + +Sign the supplied container image. + +### Synopsis + +Sign the supplied container image. + +``` +cosign sign [flags] +``` + +### Examples + +``` + cosign sign --key | [--payload ] [-a key=value] [--upload=true|false] [-f] [-r] + + # sign a container image with Google sign-in (experimental) + COSIGN_EXPERIMENTAL=1 cosign sign + + # sign a container image with a local key pair file + cosign sign --key cosign.key + + # sign a multi-arch container image AND all referenced, discrete images + cosign sign --key cosign.key --r + + # sign a container image and add annotations + cosign sign --key cosign.key -a key1=value1 -a key2=value2 + + # sign a container image with a key pair stored in Azure Key Vault + cosign sign --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] + + # sign a container image with a key pair stored in AWS KMS + cosign sign --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] + + # sign a container image with a key pair stored in Google Cloud KMS + cosign sign --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]/versions/[VERSION] + + # sign a container image with a key pair stored in Hashicorp Vault + cosign sign --key hashivault://[KEY] + + # sign a container image with a key pair stored in a Kubernetes secret + cosign sign --key k8s://[NAMESPACE]/[KEY] + + # sign a container in a registry which does not fully support OCI media types + COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -a, --annotations strings extra key=value pairs to sign + --attachment string related image attachment to sign (sbom), default none + --cert string path to the x509 certificate to include in the Signature + -f, --force skip warnings and confirmations + --fulcio-url string [EXPERIMENTAL] address of sigstore PKI server (default "https://fulcio.sigstore.dev") + -h, --help help for sign + --identity-token string [EXPERIMENTAL] identity token to use for certificate from fulcio + --key string path to the private key file, KMS URI or Kubernetes Secret + --oidc-client-id string [EXPERIMENTAL] OIDC client ID for application (default "sigstore") + --oidc-client-secret string [EXPERIMENTAL] OIDC client secret for application + --oidc-issuer string [EXPERIMENTAL] OIDC provider to be used to issue ID token (default "https://oauth2.sigstore.dev/auth") + --payload string path to a payload file to use rather than generating one + -r, --recursive if a multi-arch image is specified, additionally sign each discrete image + --rekor-url string [EXPERIMENTAL] address of rekor STL server (default "https://rekor.sigstore.dev") + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) + --upload whether to upload the signature (default true) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_triangulate.md b/doc/cosign_triangulate.md new file mode 100644 index 000000000..5d04067c3 --- /dev/null +++ b/doc/cosign_triangulate.md @@ -0,0 +1,32 @@ +## cosign triangulate + +Outputs the located cosign image reference. This is the location cosign stores the specified artifact type. +cosign triangulate + +### Synopsis + +Outputs the located cosign image reference. This is the location cosign stores the specified artifact type. + +``` +cosign triangulate [flags] +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -h, --help help for triangulate + --type string related attachment to triangulate (attestation|sbom|signature), default signature (default "signature") +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_upload.md b/doc/cosign_upload.md new file mode 100644 index 000000000..0f26734ee --- /dev/null +++ b/doc/cosign_upload.md @@ -0,0 +1,23 @@ +## cosign upload + +Provides utilities for uploading artifacts to a registry + +### Options + +``` + -h, --help help for upload +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - +* [cosign upload blob](cosign_upload_blob.md) - Upload one or more blobs to the supplied container image address. +* [cosign upload wasm](cosign_upload_wasm.md) - Upload a wasm module to the supplied container image reference + diff --git a/doc/cosign_upload_blob.md b/doc/cosign_upload_blob.md new file mode 100644 index 000000000..90ad07b22 --- /dev/null +++ b/doc/cosign_upload_blob.md @@ -0,0 +1,46 @@ +## cosign upload blob + +Upload one or more blobs to the supplied container image address. + +``` +cosign upload blob [flags] +``` + +### Examples + +``` + cosign upload blob -f + + # upload a blob named foo to the location specified by + cosign upload blob -f foo + + # upload a blob named foo to the location specified by , setting the os field to "MYOS". + cosign upload blob -f foo:MYOS + + # upload a blob named foo to the location specified by , setting the os field to "MYOS" and the platform field to "MYPLATFORM". + cosign upload blob -f foo:MYOS/MYPLATFORM + + # upload two blobs named foo-darwin and foo-linux to the location specified by , setting the os fields + cosign upload blob -f foo-darwin:darwin -f foo-linux:linux +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + --ct string content type to set + -f, --files strings :[platform/arch] + -h, --help help for blob +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign upload](cosign_upload.md) - Provides utilities for uploading artifacts to a registry + diff --git a/doc/cosign_upload_wasm.md b/doc/cosign_upload_wasm.md new file mode 100644 index 000000000..927bd04ab --- /dev/null +++ b/doc/cosign_upload_wasm.md @@ -0,0 +1,33 @@ +## cosign upload wasm + +Upload a wasm module to the supplied container image reference + +``` +cosign upload wasm [flags] +``` + +### Examples + +``` + cosign upload wasm -f foo.wasm +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -f, --file string path to the wasm file to upload + -h, --help help for wasm +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign upload](cosign_upload.md) - Provides utilities for uploading artifacts to a registry + diff --git a/doc/cosign_verify-attestation.md b/doc/cosign_verify-attestation.md new file mode 100644 index 000000000..37a0c9f1b --- /dev/null +++ b/doc/cosign_verify-attestation.md @@ -0,0 +1,69 @@ +## cosign verify-attestation + +Verify an attestation on the supplied container image + +### Synopsis + +Verify an attestation on an image by checking the claims +against the transparency log. + +``` +cosign verify-attestation [flags] +``` + +### Examples + +``` + cosign verify-attestation --key || [ ...] + + # verify cosign attestations on the image + cosign verify-attestation + + # verify multiple images + cosign verify-attestation ... + + # additionally verify specified annotations + cosign verify-attestation -a key1=val1 -a key2=val2 + + # (experimental) additionally, verify with the transparency log + COSIGN_EXPERIMENTAL=1 cosign verify-attestation + + # verify image with public key + cosign verify-attestation --key cosign.pub + + # verify image with public key provided by URL + cosign verify-attestation --key https://host.for/ + + # verify image with public key stored in Google Cloud KMS + cosign verify-attestation --key gcpkms://projects//locations/global/keyRings//cryptoKeys/ + + # verify image with public key stored in Hashicorp Vault + cosign verify-attestation --key hashivault:/// +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + --check-claims whether to check the claims found (default true) + --fulcio-url string [EXPERIMENTAL] address of sigstore PKI server (default "https://fulcio.sigstore.dev") + -h, --help help for verify-attestation + --identity-token string [EXPERIMENTAL] identity token to use for certificate from fulcio + --key string path to the private key file, KMS URI or Kubernetes Secret + -o, --output string output format for the signing image information (json|text) (default "json") + --rekor-url string [EXPERIMENTAL] address of rekor STL server (default "https://rekor.sigstore.dev") + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_verify-blob.md b/doc/cosign_verify-blob.md new file mode 100644 index 000000000..d331bbf26 --- /dev/null +++ b/doc/cosign_verify-blob.md @@ -0,0 +1,74 @@ +## cosign verify-blob + +Verify a signature on the supplied blob + +### Synopsis + +Verify a signature on the supplied blob input using the specified key reference. +You may specify either a key, a certificate or a kms reference to verify against. + If you use a key or a certificate, you must specify the path to them on disk. + +The signature may be specified as a path to a file or a base64 encoded string. +The blob may be specified as a path to a file or - for stdin. + +``` +cosign verify-blob [flags] +``` + +### Examples + +``` + cosign verify-blob (--key ||)|(--cert ) --signature + + # Verify a simple blob and message + cosign verify-blob --key cosign.pub --signature sig msg + + # Verify a simple blob with remote signature URL, both http and https schemes are supported + cosign verify-blob --key cosign.pub --signature http://host/my.sig + + # Verify a signature from an environment variable + cosign verify-blob --key cosign.pub --signature $sig msg + + # verify a signature with public key provided by URL + cosign verify-blob --key https://host.for/ --signature $sig msg + + # Verify a signature against a payload from another process using process redirection + cosign verify-blob --key cosign.pub --signature $sig <(git rev-parse HEAD) + + # Verify a signature against Azure Key Vault + cosign verify-blob --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] --signature $sig + + # Verify a signature against AWS KMS + cosign verify-blob --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] --signature $sig + + # Verify a signature against Google Cloud KMS + cosign verify-blob --key gcpkms://projects/[PROJECT ID]/locations/[LOCATION]/keyRings/[KEYRING]/cryptoKeys/[KEY] --signature $sig + + # Verify a signature against Hashicorp Vault + cosign verify-blob --key hashivault://[KEY] --signature $sig +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + --cert string path to the public certificate + -h, --help help for verify-blob + --key string path to the private key file, KMS URI or Kubernetes Secret + --rekor-url string [EXPERIMENTAL] address of rekor STL server (default "https://rekor.sigstore.dev") + --signature string signature content or path or remote URL + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_verify.md b/doc/cosign_verify.md new file mode 100644 index 000000000..de6250848 --- /dev/null +++ b/doc/cosign_verify.md @@ -0,0 +1,73 @@ +## cosign verify + +Verify a signature on the supplied container image + +### Synopsis + +Verify signature and annotations on an image by checking the claims +against the transparency log. + +``` +cosign verify [flags] +``` + +### Examples + +``` + cosign verify --key || [ ...] + + # verify cosign claims and signing certificates on the image + cosign verify + + # verify multiple images + cosign verify ... + + # additionally verify specified annotations + cosign verify -a key1=val1 -a key2=val2 + + # (experimental) additionally, verify with the transparency log + COSIGN_EXPERIMENTAL=1 cosign verify + + # verify image with public key + cosign verify --key cosign.pub + + # verify image with public key provided by URL + cosign verify --key https://host.for/[FILE] + + # verify image with public key stored in Google Cloud KMS + cosign verify --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] + + # verify image with public key stored in Hashicorp Vault + cosign verify --key hashivault://[KEY] + + # verify image with public key stored in a Kubernetes secret + cosign verify --key k8s://[NAMESPACE]/[KEY] +``` + +### Options + +``` + --allow-insecure-registry whether to allow insecure connections to registries. Don't use this for anything but testing + -a, --annotations strings extra key=value pairs to sign + --attachment string related image attachment to sign (sbom), default none + --cert-email string the email expected in a valid fulcio cert + --check-claims whether to check the claims found (default true) + -h, --help help for verify + --key string path to the private key file, KMS URI or Kubernetes Secret + -o, --output string output format for the signing image information (json|text) (default "json") + --rekor-url string [EXPERIMENTAL] address of rekor STL server (default "https://rekor.sigstore.dev") + --sk whether to use a hardware security key + --slot string security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management) +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - + diff --git a/doc/cosign_version.md b/doc/cosign_version.md new file mode 100644 index 000000000..c0550fd1d --- /dev/null +++ b/doc/cosign_version.md @@ -0,0 +1,30 @@ +## cosign version + +Prints the cosign version + +### Synopsis + +Prints the cosign version + +``` +cosign version [flags] +``` + +### Options + +``` + -h, --help help for version + --json print JSON instead of text +``` + +### Options inherited from parent commands + +``` + --output-file string log output to a file + -d, --verbose log debug output +``` + +### SEE ALSO + +* [cosign](cosign.md) - +