Chapter 2. Using the roxctl CLI
Chapter 2. Using the roxctl CLI 2.1. Prerequisites You have configured the ROX_ENDPOINT environment variable using the following command: USD export ROX_ENDPOINT= <host:port> 1 1 The host and port information that you want to store in the ROX_ENDPOINT environment variable. 2.2. Getting authentication information The following procedure describes how to use the roxctl central whoami command to retrieve information about your authentication status and user profile in Central. The example output illustrates the data you can expect to see, including user roles, access permissions, and various administrative functions. This step allows you to review your access and roles within Central. Procedure Run the following command to get information about your current authentication status and user information in Central: USD roxctl central whoami Example output UserID: <redacted> User name: <redacted> Roles: APIToken creator, Admin, Analyst, Continuous Integration, Network Graph Viewer, None, Sensor Creator, Vulnerability Management Approver, Vulnerability Management Requester, Vulnerability Manager, Vulnerability Report Creator Access: rw Access rw Administration rw Alert rw CVE rw Cluster rw Compliance rw Deployment rw DeploymentExtension rw Detection rw Image rw Integration rw K8sRole rw K8sRoleBinding rw K8sSubject rw Namespace rw NetworkGraph rw NetworkPolicy rw Node rw Secret rw ServiceAccount rw VulnerabilityManagementApprovals rw VulnerabilityManagementRequests rw WatchedImage rw WorkflowAdministration Review the output to ensure that the authentication and user details are as expected. 2.3. Authenticating by using the roxctl CLI For authentication, you can use an API token, your administrator password, or the roxctl central login command. Follow these guidelines for the effective use of API tokens: Use an API token in a production environment with continuous integration (CI). Each token is assigned specific access permissions, providing control over the actions it can perform. In addition, API tokens do not require interactive processes, such as browser-based logins, making them ideal for automated processes. These tokens have a time-to-live (TTL) value of 1 year, providing a longer validity period for seamless integration and operational efficiency. Use your administrator password only for testing purposes. Do not use it in the production environment. Use the roxctl central login command only for interactive, local uses. Note To prevent privilege escalation, when you create a new token, your role's permissions limit the permission you can assign to that token. For example, if you only have read permission for the Integration resource, you cannot create a token with write permission. If you want a custom role to create tokens for other users to use, you must assign the required permissions to that custom role. Use short-lived tokens for machine-to-machine communication, such as CI/CD pipelines, scripts, and other automation. Also, use the roxctl central login command for human-to-machine communication, such as roxctl CLI or API access. The majority of cloud service providers support OIDC identity tokens, for example, Microsoft Entra ID, Google Cloud Identity Platform, and AWS Cognito. OIDC identity tokens issued by these services can be used for RHACS short-lived access. Additional resources Using Azure Entra ID service principals for machine to machine auth with RHACS Configuring API tokens Configuring short-lived access 2.3.1. Creating an API token Procedure In the RHACS portal, go to Platform Configuration Integrations . Scroll to the Authentication Tokens category, and then click API Token . Click Generate Token . Enter a name for the token and select a role that provides the required level of access (for example, Continuous Integration or Sensor Creator ). Click Generate . Important Copy the generated token and securely store it. You will not be able to view it again. 2.3.2. Exporting and saving the API token Procedure After you have generated the authentication token, export it as the ROX_API_TOKEN variable by entering the following command: USD export ROX_API_TOKEN=<api_token> (Optional): You can also save the token in a file and use it with the --token-file option by entering the following command: USD roxctl central debug dump --token-file <token_file> Note the following guidelines: You cannot use both the -password ( -p ) and the --token-file options simultaneously. If you have already set the ROX_API_TOKEN variable, and specify the --token-file option, the roxctl CLI uses the specified token file for authentication. If you have already set the ROX_API_TOKEN variable, and specify the --password option, the roxctl CLI uses the specified password for authentication. 2.3.3. Using an authentication provider to authenticate with roxctl You can configure an authentication provider in Central and initiate the login process with the roxctl CLI. Set the ROX_ENDPOINT variable, initiate the login process with the roxctl central login command, select the authentication provider in a browser window, and retrieve the token information from the roxctl CLI as described in the following procedure. Prerequisite You selected an authentication provider of your choice, such as OpenID Connect (OIDC) with fragment or query mode. Procedure Run the following command to set the ROX_ENDPOINT variable to Central hostname and port: export ROX_ENDPOINT= <central_hostname:port> Run the following command to initiate the login process to Central: USD roxctl central login Within the roxctl CLI, a URL is printed as output and you are redirected to a browser window where you can select the authentication provider you want to use. Log in with your authentication provider. After you have successfully logged in, the browser window indicates that authentication was successful and you can close the browser window. The roxctl CLI displays your token information including details such as the access token, the expiration time of the access token, the refresh token if one has been issued, and notification that these values are stored locally. Example output Please complete the authorization flow in the browser with an auth provider of your choice. If no browser window opens, please click on the following URL: http://127.0.0.1:xxxxx/login INFO: Received the following after the authorization flow from Central: INFO: Access token: <redacted> 1 INFO: Access token expiration: 2023-04-19 13:58:43 +0000 UTC 2 INFO: Refresh token: <redacted> 3 INFO: Storing these values under USDHOME/.roxctl/login... 4 1 The access token. 2 The expiration time of the access token. 3 The refresh token. 4 The directory where values of the access token, the access token expiration time, and the refresh token are stored locally. Important Ensure that you set the environment to determine the directory where the configuration is stored. By default, the configuration is stored in the USDHOME/.roxctl/roxctl-config directory. If you set the USDROX_CONFIG_DIR environment variable, the configuration is stored in the USDROX_CONFIG_DIR/roxctl-config directory. This option has the highest priority. If you set the USDXDG_RUNTIME_DIR environment variable and the USDROX_CONFIG_DIR variable is not set, the configuration is stored in the USDXDG_RUNTIME_DIR /roxctl-config directory. If you do not set the USDROX_CONFIG_DIR or USDXDG_RUNTIME_DIR environment variable, the configuration is stored in the USDHOME/.roxctl/roxctl-config directory. 2.4. Configuring and using the roxctl CLI in RHACS Cloud Service Procedure Export the ROX_API_TOKEN by running the following command: USD export ROX_API_TOKEN=<api_token> Export the ROX_ENDPOINT by running the following command: USD export ROX_ENDPOINT=<address>:<port_number> You can use the --help option to get more information about the commands. In Red Hat Advanced Cluster Security Cloud Service (RHACS Cloud Service), when using roxctl commands that require the Central address, use the Central instance address as displayed in the Instance Details section of the Red Hat Hybrid Cloud Console. For example, use acs-ABCD12345.acs.rhcloud.com instead of acs-data-ABCD12345.acs.rhcloud.com .
export ROX_ENDPOINT= <host:port> 1 roxctl central whoami UserID: <redacted> User name: <redacted> Roles: APIToken creator, Admin, Analyst, Continuous Integration, Network Graph Viewer, None, Sensor Creator, Vulnerability Management Approver, Vulnerability Management Requester, Vulnerability Manager, Vulnerability Report Creator Access: rw Access rw Administration rw Alert rw CVE rw Cluster rw Compliance rw Deployment rw DeploymentExtension rw Detection rw Image rw Integration rw K8sRole rw K8sRoleBinding rw K8sSubject rw Namespace rw NetworkGraph rw NetworkPolicy rw Node rw Secret rw ServiceAccount rw VulnerabilityManagementApprovals rw VulnerabilityManagementRequests rw WatchedImage rw WorkflowAdministration export ROX_API_TOKEN=<api_token> roxctl central debug dump --token-file <token_file> export ROX_ENDPOINT= <central_hostname:port> roxctl central login Please complete the authorization flow in the browser with an auth provider of your choice. If no browser window opens, please click on the following URL: http://127.0.0.1:xxxxx/login INFO: Received the following after the authorization flow from Central: INFO: Access token: <redacted> 1 INFO: Access token expiration: 2023-04-19 13:58:43 +0000 UTC 2 INFO: Refresh token: <redacted> 3 INFO: Storing these values under USDHOME/.roxctl/login... 4 export ROX_API_TOKEN=<api_token> export ROX_ENDPOINT=<address>:<port_number>