#title: Checking Policies with roxctl description: Learn how to evaluate deployments and images against policies by using roxctl in Alauda Security Service. weight: 10

#Checking Policies with roxctl

Alauda Security Service provides the roxctl CLI to help you evaluate deployment YAML files and container images against the current policy set in Central. Use these commands in CI, pre-deployment checks, and troubleshooting workflows when you want results without navigating the web console.

#Prerequisites

• Set the ROX_ENDPOINT environment variable:

  export ROX_ENDPOINT=<host:port>

  Replace <host:port> with the address of your Alauda Security Service Central instance.

#Output Formats

When running roxctl deployment check or roxctl image check, you can specify the output format using the -o option. Supported formats are json, table, csv, and junit. If not specified, the default is table for deployment and image checks, and json for image scans.

#Example

roxctl deployment check --file=<yaml_filename> -o csv

#Output Options

The following table summarizes the available output options:

#Example: Custom Headers and JSONPath

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

#Checking Policies for Deployments

To check build-time and deploy-time policy violations in your deployment YAML files, run:

roxctl deployment check --file=<yaml_filename> \
  --namespace=<cluster_namespace> \
  --cluster=<cluster_name_or_id> \
  --verbose

• <yaml_filename>: Path to the deployment YAML file(s). You can specify multiple files by repeating the --file flag.
• <cluster_namespace>: (Optional) Namespace for context. Default is default.
• <cluster_name_or_id>: (Optional) Cluster name or ID for context.
• --verbose: (Optional) Show additional information, such as RBAC permissions and network policies.

Note: Additional deployment information is included in JSON output, regardless of the --verbose flag.

To force Alauda Security Service to re-pull image metadata and scan results, add the --force option.

Permission Requirement:
To check specific image scan results, your token must have both read and write permissions for the Image resource. The default Continuous Integration system role includes these permissions.

The deployment check evaluates:

• Configuration options in the YAML file (e.g., resource limits, privilege settings)
• Image aspects (e.g., components, vulnerabilities)

#Checking Policies for Images

To check build-time policy violations in images, run:

roxctl image check --image=<image_name>

To force Alauda Security Service to re-pull image metadata and scan results, add the --force option.

Permission Requirement:
To check specific image scan results, your token must have both read and write permissions for the Image resource. The default Continuous Integration system role includes these permissions.

#Viewing Image Scan Results

To view the components and vulnerabilities found in an image in JSON format, run:

roxctl image scan --image=<image_name>

To force Alauda Security Service to re-pull image metadata and scan results, add the --force option.

Permission Requirement:
To check specific image scan results, your token must have both read and write permissions for the Image resource. The default Continuous Integration system role includes these permissions.