CLI reference¶

gapsign — container-image signing for airgapped and egress-restricted fleets

Usage:
  gapsign keygen [-out DIR] [-name NAME] [-force]    generate a signing keypair
  gapsign sign   [-config FILE] [-key PATH] IMAGE     sign a first-party image (CI publish)
  gapsign verify [-config FILE] [-pub PATH] IMAGE     verify a signature offline (fail-closed)
  gapsign ingest [-config FILE] SRC DST               mirror-copy then sign a third-party image (policy-gated)
  gapsign policy render [-config FILE] [-o FILE]      render the fail-closed Kyverno admission policy
  gapsign backends                                    list registered signer backends
  gapsign version                                     print version

Config defaults to $GAPSIGN_CONFIG or ~/.config/gapsign/config.yaml.
Signatures commit to the image digest (never a mutable tag).

Common flags¶

Flag	Commands	Meaning
`-config FILE`	sign, verify, ingest, policy	config path (default `~/.config/gapsign/config.yaml`)
`-key PATH`	sign, verify	use the cosign-key backend with this key directly
`-pub PATH`	verify	verify against this public key directly
`-insecure`	sign, verify, ingest	allow a plain-HTTP / self-signed registry
`-o FILE`	policy render	write to FILE instead of stdout

keygen¶

$ gapsign keygen [-out DIR] [-name NAME] [-force]

Generates a cosign-compatible ECDSA P-256 keypair. The private key is written mode 0600 (never committed); the public key is the GitOps-distributed trust anchor. Default output directory is ~/.config/gapsign/. -force overwrites existing files (fresh files, no symlink following).

sign / verify¶

$ gapsign sign   -key ~/.config/gapsign/cosign.key IMAGE
$ gapsign verify -pub ~/.config/gapsign/cosign.pub IMAGE

sign resolves the reference to a digest and pushes a cosign-layout signature. verify fails closed: exit non-zero on an unsigned image, a wrong key, or a digest/repo mismatch. Both accept a full reference (tag or @sha256:…).

ingest¶

$ gapsign ingest -config config.yaml SRC DST

Policy-gated mirror + re-attest. Requires a config with a policy, a signer_name, and a non-empty sources allowlist. See Mirror ingest.

policy render¶

$ gapsign policy render -config config.yaml -o kyverno-policy.yaml

Emits a fail-closed Kyverno ClusterPolicy. See Admission enforcement.

backends¶

$ gapsign backends
cosign-key
cosign-x509

Exit codes¶

0 success · 1 a runtime/verification failure (fail-closed) · 2 a usage error.