Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Checking policy compliance

You can use the roxctl CLI to check deployment YAML files and images for policy compliance.

4.1. Prerequisites

  • You have configured the ROX_ENDPOINT environment variable using the following command: 

    $ export ROX_ENDPOINT=<host:port>
    1
    Copy to Clipboard
    1
    The host and port information that you want to store in the ROX_ENDPOINT environment variable.

4.2. Configuring output format

When you check policy compliance by using the roxctl deployment check or roxctl image check commands, you can specify the output format by using the -o option to the command and specifying the format as json, table, csv, or junit. This option determines how the output of a command is displayed in the terminal.

For example, the following command checks a deployment and then displays the result in csv format: 

$ roxctl deployment check --file =<yaml_filename> -o csv
Copy to Clipboard
Note

When you do not specify the -o option for the output format, the following default behavior is used:

  • The format for the deployment check and the image check commands is table.
  • The default output format for the image scan command is json. This is the old JSON format output for compatibility with older versions of the CLI. To get the output in the new JSON format, specify the option with format, as -o json. Use the old JSON format output when gathering data for troubleshooting purposes.

Different options are available to configure the output. The following table lists the options and the format in which they are available.

OptionDescriptionFormats

--compact-output

Use this option to display the JSON output in a compact format.

json

--headers

Use this option to specify custom headers.

table and csv

--no-header

Use this option to omit the header row from the output.

table and csv

--row-jsonpath-expressions

Use this option to specify GJSON paths to select specific items from the output. For example, to get the Policy name and Severity for a deployment check, use the following command: 

$ roxctl deployment check --file=<yaml_filename> \
  -o table --headers POLICY-NAME,SEVERITY \
  --row-jsonpath-expressions="{results..violatedPolicies..name,results..violatedPolicies..severity}"
Copy to Clipboard

table and csv

--merge-output

Use this options to merge table cells that have the same value.

table

headers-as-comment

Use this option to include the header row as a comment in the output.

csv

--junit-suite-name

Use this option to specify the name of the JUnit test suite.

junit

4.3. Checking deployment YAML files

Procedure

  • Run the following command to check the build-time and deploy-time violations of your security policies in YAML deployment files: 

    $ roxctl deployment check --file=<yaml_filename>
    Copy to Clipboard

    The format is defined in the API reference. To cause Red Hat Advanced Cluster Security for Kubernetes (RHACS) to re-pull image metadata and image scan results from the associated registry and scanner, add the --force option.

    Note

    To check specific image scan results, you must have a token with both read and write permissions for the Image resource. The default Continuous Integration system role already has the required permissions.

    This command validates the following items:

    • Configuration options in a YAML file, such as resource limits or privilege options
    • Aspects of the images used in a YAML file, such as components or vulnerabilities

4.4. Checking images

Procedure

  • Run the following command to check the build-time violations of your security policies in images: 

    $ roxctl image check --image=<image_name>
    Copy to Clipboard

    The format is defined in the API reference. To cause Red Hat Advanced Cluster Security for Kubernetes (RHACS) to re-pull image metadata and image scan results from the associated registry and scanner, add the --force option.

    Note

    To check specific image scan results, you must have a token with both read and write permissions for the Image resource. The default Continuous Integration system role already has the required permissions.

4.5. Checking image scan results

You can also check the scan results for specific images.

Procedure

  • Run the following command to return the components and vulnerabilities found in the image in JSON format: 

    $ roxctl image scan --image <image_name>
    Copy to Clipboard

    The format is defined in the API reference. To cause Red Hat Advanced Cluster Security for Kubernetes (RHACS) to re-pull image metadata and image scan results from the associated registry and scanner, add the --force option.

    Note

    To check specific image scan results, you must have a token with both read and write permissions for the Image resource. The default Continuous Integration system role already has the required permissions.

4.6. roxctl image command overview

Commands that you can run on a specific image.

Usage

$ roxctl image [command] [flags]
Copy to Clipboard

Table 4.1. Available commands
CommandDescription

check

Check images for build time policy violations, and report them.

scan

Scan the specified image, and return the scan results.

Table 4.2. Options
OptionDescription

-t, --timeout duration

Set the timeout for API requests representing the maximum duration of a request. The default value is 10m0s.

4.6.1. roxctl image command options inherited from the parent command

The roxctl image command supports the following options inherited from the parent roxctl command:

OptionDescription

--ca string

Specify a custom CA certificate file path for secure connections. Alternatively, you can specify the file path by using the ROX_CA_CERT_FILE environment variable.

--direct-grpc

Set --direct-grpc for improved connection performance. Alternatively, by setting the ROX_DIRECT_GRPC_CLIENT environment variable to true, you can enable direct gRPC . The default value is false.

-e, --endpoint string

Set the endpoint for the service to contact. Alternatively, you can set the endpoint by using the ROX_ENDPOINT environment variable. The default value is localhost:8443.

--force-http1

Force the use of HTTP/1 for all connections. Alternatively, by setting the ROX_CLIENT_FORCE_HTTP1 environment variable to true, you can force the use of HTTP/1. The default value is false.

--insecure

Enable insecure connection options. Alternatively, by setting the ROX_INSECURE_CLIENT environment variable to true, you can enable insecure connection options. The default value is false.

--insecure-skip-tls-verify

Skip the TLS certificate validation. Alternatively, by setting the ROX_INSECURE_CLIENT_SKIP_TLS_VERIFY environment variable to true, you can skip the TLS certificate validation. The default value is false.

--no-color

Disable the color output. Alternatively, by setting the ROX_NO_COLOR environment variable to true, you can disable the color output. The default value is false.

-p, --password string

Specify the password for basic authentication. Alternatively, you can set the password by using the ROX_ADMIN_PASSWORD environment variable.

--plaintext

Use an unencrypted connection. Alternatively, by setting the ROX_PLAINTEXT environment variable to true, you can enable an unencrypted connection. The default value is false.

-s, --server-name string

Set the TLS server name to use for SNI. Alternatively, you can set the server name by using the ROX_SERVER_NAME environment variable.

--token-file string

Use the API token provided in the specified file for authentication. Alternatively, you can set the token by using the ROX_API_TOKEN environment variable.

Note

These options are applicable to all the sub-commands of the roxctl image command.

4.6.2. roxctl image scan

Scan the specified image, and return the scan results.

Usage

$ roxctl image scan [flags]
Copy to Clipboard

Table 4.3. Options
OptionDescription

--cluster string

Specify the cluster name or ID to which you want to delegate the image scan.

--compact-output

Print JSON output in a compact format. The default value is false.

-f, --force

Ignore Central’s cache and force a fresh re-pull from Scanner. The default value is false.

--headers strings

Specify the headers to print in a tabular output. The default values include COMPONENT, VERSION,CVE,SEVERITY, and LINK.

--headers-as-comments

Print headers as comments in a CSV tabular output. The default value is false.

-i, --image string

Specify the image name and reference to scan. For example, nginx:latest or nginx@sha256:…​.

-a, --include-snoozed

Include snoozed and unsnoozed CVEs in the scan results. The default value is false.

--merge-output

Merge duplicate cells in a tabular output. The default value is true.

--no-header

Do not print headers for a tabular output. The default value is false.

-o, --output string

Specify the output format. Output formats include table, csv, json, and sarif.

-r, --retries int

Specify the number of retries before exiting as an error. The default value is 3.

-d, --retry-delay int

Set the time to wait between retries in seconds. The default value is 3.

--row-jsonpath-expressions string

Specify JSON path expressions to create a row from the JSON object. For more details, run the roxctl image scan --help command.

4.6.3. roxctl image check

Check images for build time policy violations, and report them.

Usage

$ roxctl image check [flags]
Copy to Clipboard

Table 4.4. Options
OptionDescription

-c, --categories strings

List of the policy categories that you want to execute. By default, all the policy categories are used.

--cluster string

Define the cluster name or ID that you want to use as the context for evaluation.

--compact-output

Print JSON output in a compact format. The default value is false.

-f, --force

Bypass the Central cache for the image and force a new pull from the Scanner. The default value is false.

--headers strings

Define headers to print in a tabular output. The default values include POLICY, SEVERITY, BREAKS BUILD, DESCRIPTION, VIOLATION, and REMEDIATION.

--headers-as-comments

Print headers as comments in a CSV tabular output. The default value is false.

-i, --image string

Specify the image name and reference. For example, nginx:latest or nginx@sha256:…​).

--junit-suite-name string

Set the name of the JUnit test suite. Default value is image-check.

--merge-output

Merge duplicate cells in a tabular output. The default value is false.

--no-header

Do not print headers for a tabular output. The default value is false.

-o, --output string

Choose the output format. Output formats include junit, sarif, table, csv, and json. The default value is table.

-r, --retries int

Set the number of retries before exiting as an error. The default value is 3.

-d, --retry-delay int

Set the time to wait between retries in seconds. The default value is 3.

--row-jsonpath-expressions string

Create a row from the JSON object by using JSON path expression. For more details, run the roxctl image check --help command.

--send-notifications

Define whether you want to send notifications in the event of violations. The default value is false.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat