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
- 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
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 theimage check
commands istable
. -
The default output format for the
image scan
command isjson
. 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.
Option | Description | Formats |
---|---|---|
| Use this option to display the JSON output in a compact format. |
|
| Use this option to specify custom headers. |
|
| Use this option to omit the header row from the output. |
|
| 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}" |
|
| Use this options to merge table cells that have the same value. |
|
| Use this option to include the header row as a comment in the output. |
|
| Use this option to specify the name of the JUnit test suite. |
|
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> \1 --namespace=<cluster_namespace> \2 --cluster=<cluster_name_or_id> \3 --verbose 4
- 1
- For the
<yaml_filename>
, specify the YAML file with one or more deployments to send to Central for policy evaluation. You can also specify multiple YAML files to send to Central for policy evaluation by using the--file
flag, for example--file=<yaml_filename1>
,--file=<yaml_filename2>
, and so on. - 2
- For the
<cluster_namespace>
, specify a namespace to enhance deployments with context information such as network policies, role-based access controls (RBACs) and services for deployments that do not have a namespace in their specification. The namespace defined in the specification is not changed. The default value isdefault
. - 3
- For the
<cluster_name_or_id>
, specify the cluster name or ID that you want to use as the context for the evaluation to enable extended deployments with cluster-specific information. - 4
- By enabling the
--verbose
flag, you receive additional information for each deployment during the policy check. The extended information includes the RBAC permission level and a comprehensive list of network policies that is applied.NoteYou can see the additional information for each deployment in your JSON output, regardless of whether you enable the
--verbose
flag or not.
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.NoteTo check specific image scan results, you must have a token with both
read
andwrite
permissions for theImage
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>
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.NoteTo check specific image scan results, you must have a token with both
read
andwrite
permissions for theImage
resource. The default Continuous Integration system role already has the required permissions.
Additional resources
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>
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.NoteTo check specific image scan results, you must have a token with both
read
andwrite
permissions for theImage
resource. The default Continuous Integration system role already has the required permissions.
Additional resources