// Generated by conforma CLI documentation tooling. DO NOT EDIT.
= ec validate image

Validate conformance of container images with the provided policies

== Synopsis

Validate conformance of container images with the provided policies

For each image, validation is performed in stages to determine if the image
conforms to the provided policies.

The first validation stage determines if an image has been signed, and the
signature matches the provided public key. This is akin to the "cosign verify"
command.

The second validation stage determines if one or more attestations exist, and
those attestations have been signed matching the provided public key, similarly
to the "cosign verify-attestation" command. This stage temporarily stores the
attestations for usage in the next stage.

The final stage verifies the attestations conform to rego policies defined in
the EnterpriseContractPolicy.

Validation advances each stage as much as possible for each image in order to
capture all issues in a single execution.

[source,shell]
----
ec validate image [flags]
----

== Examples
Validate single image with the policy defined in the EnterpriseContractPolicy
custom resource named "default" in the enterprise-contract-service Kubernetes
namespace:

  ec validate image --image registry/name:tag

Validate multiple images from an ApplicationSnapshot Spec file:

  ec validate image --images my-app.yaml

Validate attestation of images from an inline ApplicationSnapshot Spec:

  ec validate image --images '{"components":[{"containerImage":"<image url>"}]}'

Use a different public key than the one from the EnterpriseContractPolicy resource:

  ec validate image --image registry/name:tag --public-key <path/to/public/key>

Use a different Rekor URL than the one from the EnterpriseContractPolicy resource:

  ec validate image --image registry/name:tag --rekor-url https://rekor.example.org

Return a non-zero status code on validation failure:

  ec validate image --image registry/name:tag

Return a zero status code even if there are validation failures:

  ec validate image --image registry/name:tag --strict=false

Use an EnterpriseContractPolicy resource from the currently active kubernetes context:

  ec validate image --image registry/name:tag --policy my-policy

Use an EnterpriseContractPolicy resource from a different namespace:

  ec validate image --image registry/name:tag --policy my-namespace/my-policy

Use an inline EnterpriseContractPolicy spec

  ec validate image --image registry/name:tag --policy '{"publicKey": "<path/to/public/key>"}'

Use an EnterpriseContractPolicy spec from a local YAML file
  ec validate image --image registry/name:tag --policy my-policy.yaml

Use a git url for the policy configuration. In the first example there should be a '.ec/policy.yaml'
or a 'policy.yaml' inside a directory called 'default' in the top level of the git repo. In the second
example there should be a '.ec/policy.yaml' or a 'policy.yaml' file in the top level
of the git repo. For git repos not hosted on 'github.com' or 'gitlab.com', prefix the url with
'git::'. For the policy configuration files you can use json instead of yaml if you prefer.

  ec validate image --image registry/name:tag --policy github.com/user/repo//default?ref=main

  ec validate image --image registry/name:tag --policy github.com/user/repo

Write output in JSON format to a file

  ec validate image --image registry/name:tag --output json=<path>

Write output in YAML format to stdout and in appstudio format to a file

  ec validate image --image registry/name:tag --output yaml --output appstudio=<path>


Validate a single image with keyless workflow.

  ec validate image --image registry/name:tag --policy my-policy \
    --certificate-identity 'https://github.com/user/repo/.github/workflows/push.yaml@refs/heads/main' \
    --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
    --rekor-url 'https://rekor.sigstore.dev'

Use a regular expression to match certificate attributes.

  ec validate image --image registry/name:tag --policy my-policy \
    --certificate-identity-regexp '^https://github\.com' \
    --certificate-oidc-issuer-regexp 'githubusercontent' \
    --rekor-url 'https://rekor.sigstore.dev'

== Options

--allow-past-effective-time:: Allow setting --effective-time to a date in the past. By default, dates
in the past are rejected.
 (Default: false)
--attestation-format:: Attestation output format: dsse (signed envelope), predicate (raw JSON) (Default: dsse)
--attestation-output-dir:: Directory for attestation output files. Defaults to a temp directory under /tmp. Must be under /tmp or the current working directory.
--certificate-identity:: URL of the certificate identity for keyless verification
--certificate-identity-regexp:: Regular expression for the URL of the certificate identity for keyless verification
--certificate-oidc-issuer:: URL of the certificate OIDC issuer for keyless verification
--certificate-oidc-issuer-regexp:: Regular expression for the URL of the certificate OIDC issuer for keyless verification
--color:: Enable color when using text output even when the current terminal does not support it (Default: false)
--effective-time:: Run policy checks with the provided time. Useful for testing rules with
effective dates in the future. The value can be "now" (default) - for
current time, "attestation" - for time from the youngest attestation, or
a RFC3339 formatted value, e.g. 2022-11-18T00:00:00Z.
 (Default: now)
--extra-rule-data:: Extra data to be provided to the Rego policy evaluator. Use format 'key=value'. May be used multiple times.
 (Default: [])
-f, --file-path:: DEPRECATED - use --images: path to ApplicationSnapshot Spec JSON file
--filter-type:: Filter type to use for policy evaluation. Options: "include-exclude" (default) or "ec-policy".
- "include-exclude": Uses traditional include/exclude filtering without pipeline intentions
- "ec-policy": Uses Enterprise Contract policy filtering with pipeline intention support (Default: include-exclude)
-h, --help:: help for image (Default: false)
--ignore-rekor:: Skip Rekor transparency log checks during validation. (Default: false)
-i, --image:: OCI image reference
--images:: path to ApplicationSnapshot Spec JSON file or JSON representation of an ApplicationSnapshot Spec
--info:: Include additional information on the failures. For instance for policy
violations, include the title and the description of the failed policy
rule. (Default: false)
-j, --json-input:: DEPRECATED - use --images: JSON representation of an ApplicationSnapshot Spec
--no-color:: Disable color when using text output even when the current terminal supports it (Default: false)
--output:: write output to a file in a specific format. Use empty string path for stdout.
May be used multiple times. Possible formats are:
json, yaml, text, appstudio, summary, summary-markdown, junit, attestation, policy-input, vsa. In following format and file path
additional options can be provided in key=value form following the question
mark (?) sign, for example: --output text=output.txt?show-successes=false
 (Default: [])
-o, --output-file:: [DEPRECATED] write output to a file. Use empty string for stdout, default behavior
-p, --policy:: Policy configuration as:
  * Kubernetes reference ([<namespace>/]<name>)
  * file (policy.yaml)
  * git reference (github.com/user/repo//default?ref=main), or
  * inline JSON ('{sources: {...}, identity: {...}}')")
-k, --public-key:: path to the public key. Overrides publicKey from EnterpriseContractPolicy
-r, --rekor-url:: Rekor URL. Overrides rekorURL from EnterpriseContractPolicy
--skip-att-sig-check:: Skip attestation signature validation checks. (Default: false)
--skip-image-sig-check:: Skip image signature validation checks. (Default: false)
--snapshot:: Provide the AppStudio Snapshot as a source of the images to validate, as inline
JSON of the "spec" or a reference to a Kubernetes object [<namespace>/]<name>
-s, --strict:: Return non-zero status on non-successful validation. Defaults to true. Use --strict=false to return a zero status code. (Default: true)
--vsa:: Generate a Verification Summary Attestation (VSA) for each validated image. (Default: false)
--vsa-expiration:: Expiration threshold for existing VSAs. If a valid VSA exists and is newer than this threshold, validation will be skipped. (default 168h) (Default: 168h0m0s)
--vsa-signing-key:: Path to the private key for signing the VSA. Supports file paths and Kubernetes secret references (k8s://namespace/secret-name/key-field).
--vsa-upload:: Storage backends for VSA upload. Format: backend@url?param=value. Examples: rekor@https://rekor.sigstore.dev, local@./vsa-dir (Default: [])
--workers:: Number of workers to use for validation. Defaults to 5. (Default: 5)

== Options inherited from parent commands

--debug:: same as verbose but also show function names and line numbers (Default: false)
--kubeconfig:: path to the Kubernetes config file to use
--logfile:: file to write the logging output. If not specified logging output will be written to stderr
--quiet:: less verbose output (Default: false)
--retry-duration:: base duration for exponential backoff calculation (Default: 1s)
--retry-factor:: exponential backoff multiplier (Default: 2)
--retry-jitter:: randomness factor for backoff calculation (0.0-1.0) (Default: 0.1)
--retry-max-retry:: maximum number of retry attempts (Default: 3)
--retry-max-wait:: maximum wait time between retries (Default: 3s)
--show-policy-docs-link:: Show link to policy documentation in output when there are violations or warnings (Default: false)
--show-successes::  (Default: false)
--show-warnings::  (Default: true)
--timeout:: max overall execution duration (Default: 5m0s)
--trace:: enable trace logging, set one or more comma separated values: none,all,perf,cpu,mem,opa,log (Default: none)
--verbose:: more verbose output (Default: false)

== See also

 * xref:ec_validate.adoc[ec validate - Validate conformance with the provided policies]
