Install the RoxCtl CLI
You can install the roxctl CLI to interact with RHACS from a command-line interface. You can install roxctl on Linux, Windows, or macOS.
Installing the roxctl CLI on Windows
You can install the roxctl CLI binary on Windows by using the following procedure.
Download the latest version of the roxctl CLI:
curl -O https://mirror.openshift.com/pub/rhacs/assets/latest/bin/windows/roxctl.exe
Verify the roxctl version you have installed.
PS C:\Users\suyash.sambhare> roxctl version
4.2.2
Set the Environment Variables:
PS C:\Users\suyash.sambhare> set ROX_ENDPOINT=central-stackrox.apps.ocpcl.suyash.local:443
Create an Auth Provider
RoxCtl login auth does not authenticate with basic RedHat OpenShift Authentication. You need to create an Auth Provider.
- If you already have an existing Auth provider such as IBM Verify, Microsoft Active Directory, etc, you can choose to integrate with it.
- Else navigate to ACM > Platform Configuration > Access Control > Auth Providers > Create auth provider > OpenShift Auth
- Create a basic auth provider
Login to roxctl
PS C:\Users\suyash.sambhare> 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:61396/login
INFO: Received the following after the authorization flow from Central:
INFO: Access token: eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3dGswIiwidHlwIjoiSldUIn0.eyJhdWQiOlsiYmE1MmZmMzAtMTgzYy00ZmRjLWE1NWItYzVlZGQ3YjQ3ZmZmIl0sImV4cCI6MTY5ODgyMDU1NCwiZXh0ZXJuYWxfdXrgQPpiZRdO0577t1-2I6WDRvY4DyjNGkifWVAIOLqAyMvoUv60qp2SQvaW7JG1ICl4CGgm6l3hOJQpjSHnWCpWeLDOVjPvCenKlgd6kDy5VYCbkLUywegS0-GhZT3PQ7Lonubr-szu_6yASv4oMviY5EnVMGfF2nNAEZOuuG1SzvQD0xhOKgXl-uLt2G9ZQ8Cpi3iLq8P-YY_NT1U
INFO: Access token expiration: 2023-11-01 06:35:54 +0000 UTC
INFO: Refresh token: providerId=ba52ff30-183c-4fdc-a55b-c5edd7b47fff&providerType=openshift&refreshToken=%7B%22access_token%22%3A%22sha256~qlg7nK72OIlRLrb5vo0owlopiRsgLjX6GzE-mpJFaXM%22%2C%22token_type%22%3A%22Bearer%22%2C%22expiry%22%3A%222023-11-02T06%3A30%3A54.479565394Z%22%7D
INFO: Successfully persisted the authentication information for central central-stackrox.apps.ocpcl.suyash.local:443.
You can now use the retrieved access token for all other roxctl commands!
In case the access token is expired and cannot be refreshed, you have to run "roxctl central login" again.
You will still get a Certificate error in the case of self-signed certificates.
PS C:\Users\suyash.sambhare> roxctl central whoami
WARN: The remote endpoint failed TLS validation. This will be a fatal error in future releases.
Please do one of the following at your earliest convenience:
1. Obtain a valid certificate for your Central instance/Load Balancer.
2. Use the --ca option to specify a custom CA certificate (PEM format). This Certificate can be obtained by
running "roxctl central cert".
3. Update all your roxctl usages to pass the --insecure-skip-tls-verify option, to
suppress this warning and retain the old behavior of not validating TLS certificates in
the future (NOT RECOMMENDED).
WARN: Certificate validation error: x509: certificate signed by unknown authority
ERROR: rpc error: code = Unauthenticated desc = credentials not found: token validation failed
Fetch the CA Certificate
Use the CA Certificate in subsequent commands to avoid the error.
PS C:\Users\suyash.sambhare> roxctl central cert
ERROR: tls: failed to verify certificate: x509: certificate signed by unknown authority
PS C:\Users\suyash.sambhare> roxctl central cert --insecure-skip-tls-verify
INFO: Issuer: SERIALNUMBER=2285948372658301323,CN=StackRox Certificate Authority
INFO: Issuer: SERIALNUMBER=2260987654321301323,CN=StackRox Certificate Authority
INFO: Subject: SERIALNUMBER=1883746501924761665,CN=CENTRAL_SERVICE: Central,OU=CENTRAL_SERVICE
INFO: Not valid before: 2023-07-27 14:50:00 +0000 UTC
INFO: Not valid after: 2024-07-26 15:50:00 +0000 UTC
-----BEGIN CERTIFICATE-----
MIICTTCCAfKgAwIBAgIIGXbfQFwEl8EwCgYIKoZIzj0EAwIwRzEnMCUGA1UEAxMe
U3RhY2tSb3ggQ2VydGlmaWNhdGUgQXV0aG9yaXR5MRwwGgYDVQQFExMyMjYyMTYz
OTgxNjc4MzAxMzIzMB4XDTIzMDcyNzE0NTAwMFoXDTI0MDcyNjE1NTAwMFowWzEY
MBYGA1UECwwPQ0VOVFJBTF9TRVJWSUNFMSEwHwYDVQQDDBhDRU5UUkFMX1NFUlZJ
Q0U6IENlbnRyYWwxHDAaBgNVBAUTEzE4MzQ4OTkzNjU3MTQ3NjE2NjUwWTATBgcq
U3RhY2tSb3ggQ2VydGlmaWNhdGUgQXV0aG9yaXR5MRwwGgYDVQQFExMyMjYyMTYz
OTgxNjc4MzAxMzIzMB4XDTIzMDcyNzE0NTAwMFoXDTI0MDcyNjE1NTAwMFowWzEY
MBYGA1UECwwPQ0VOVFJBTF9TRVJWSUNFMSEwHwYDVQQDDBhDRU5UUkFMX1NFUlZJ
Q0U6IENlbnRyYWwxHDAaBgNVBAUTEzE4MzQ4OTkzNjU3MTQ3NjE2NjUwWTATBgcq
Q0U6IENlbnRyYWwxHDAaBgNVBAUTEzE4MzQ4OTkzNjU3MTQ3NjE2NjUwWTATBgcq
U3RhY2tSb3ggQ2VydGlmaWNhdGUgQXV0aG9yaXR5MRwwGgYDVQQFExMyMjYyMTYz
OTgxNjc4MzAxMzIzMB4XDTIzMDcyNzE0NTAwMFoXDTI0MDcyNjE1NTAwMFowWzEY
G15YV5rwPHJr23C5FXYoAEE=
-----END CERTIFICATE-----
Save the Begin Certificate to End Certificate text in a pem file.
Use this Pem file each time to validate the certificate.
PS C:\Users\suyash.sambhare> roxctl central login --ca .\Downloads\roxctl.pem
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:61719/login
INFO: Received the following after the authorization flow from Central:
INFO: Access token: eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3dGswIiwidHlwIjoiSldUIn0.eyJhdWQiOlsiYmE1MmZmMzAtMTgzYy00ZmRjLWE1NWItYzVlZGQ3YjQ3ZmZmIl0sImV4cCI6MTY5ODgyMDc5NywiZXh0ZXJuYWxfdXNhwhjS1_6_p1KjA8lXZs8LAPauDIB59TbefmjLy8qAEwo_sfvMoW6pT9qBw497WaBQo7ioV8pzDRm0qnjko3TaLOeEyJ1JzKXw_IjyV5iXNrk-b3YViulLMTTayi-UN6uBcRdwWN6bWsuuT_m-sIkU_bst1TPybL8rASuD2elxMcX0iqTJ8IdeMTv2actqEfDe5Ont8dllNpzCQpeFagZSnqYW0gPxN7p1DHQRDBjeVdaB6ORjCt_vCnRcK4ZzYgj4mKgbBWwDzW7Co8kG6a6SPvNRaTPZkilWY
INFO: Access token expiration: 2023-11-01 06:39:57 +0000 UTC
INFO: Refresh token: providerId=ba52ff30-183c-4fdc-a55b-c5edd7b47fff&providerType=openshift&refreshToken=%7B%22access_token%22%3A%22sha256~P7lxbF_upU2zbCSTkyxljorxq7ihwsD9z-2WtqrdAj8%22%2C%22token_type%22%3A%22Bearer%22%2C%22expiry%22%3A%222023-11-02T06%3A34%3A57.398377433Z%22%7D
INFO: Successfully persisted the authentication information for central central-stackrox.apps.ocpcl.suyash.local:443.
You can now use the retrieved access token for all other roxctl commands!
In the browser windows authenticate the OpenShift Auth created.
You should see the message:
Roxctl authorization is successful!
You may now close this window.
You can now run roxctl commands.
PS C:\Users\suyash.sambhare> roxctl central whoami --ca .\Downloads\roxctl.pem
UserID:
sso:ba52ff30-183c-4fdc-a55b-c5edd7b47fff:kube:admin
User name:
kube:admin
Roles:
Admin, Analyst, Continuous Integration, Network Graph Viewer, None, Sensor Creator, Vulnerability Management Approver, Vulnerability Management Requester, Vulnerability Report Creator
Access:
rw Access
rw Administration
rw Alert
rw CVE
rw Cluster
rw VulnerabilityManagementApprovals
rw VulnerabilityManagementRequests
rw WatchedImage
rw WorkflowAdministration
PS C:\Users\suyash.sambhare>
Login using API Token
- Login to ACS UI and navigate to Platform Configuration > Integrations > Authentication Tokens > API Token > Generate Token
- Provide a token name and Role for the user.
- Create the Token and copy the token string to a text file.
- In Windows Settings navigate to Environment Variables > and set the ROX_API_TOKEN to the token string copied earlier.
- You can now use roxctl using the token directly.
PS C:\Users\suyash.sambhare> roxctl central whoami
WARN: The remote endpoint failed TLS validation. This will be a fatal error in future releases.
Please do one of the following at your earliest convenience:
1. Obtain a valid certificate for your Central instance/Load Balancer.
2. Use the --ca option to specify a custom CA certificate (PEM format). This Certificate can be obtained by
running "roxctl central cert".
3. Update all your roxctl usages to pass the --insecure-skip-tls-verify option, to
suppress this warning and retain the old behavior of not validating TLS certificates in
the future (NOT RECOMMENDED).
WARN: Certificate validation error: x509: certificate signed by unknown authority
UserID:
auth-token:382660f2-7cf6-4a60-9967-a52afcedffe3
User name:
anonymous bearer token "SuyashToken" with roles [Admin] (jti: 382660f2-7cf6-4a60-9967-a52afcedffe3, expires: 2024-10-26T06:06:06Z)
Roles:
Admin, Analyst, Continuous Integration, Network Graph Viewer, None, Sensor Creator, Vulnerability Management Approver, Vulnerability Management Requester, Vulnerability Report Creator
Access:
rw Access
rw Administration
rw Alert
rw CVE
rw Cluster
rw ServiceAccount
rw VulnerabilityManagementApprovals
rw VulnerabilityManagementRequests
rw WatchedImage
rw WorkflowAdministration
PS C:\Users\suyash.sambhare>
To avoid the CA Certificate error provide the previously downloaded pem as a reference to the --ca switch
PS C:\Users\suyash.sambhare\Downloads> roxctl central whoami --ca .\roxctl.pem
UserID:
auth-token:382660f2-7cf6-4a60-9967-a52afcedffe3
User name:
anonymous bearer token "SuyashToken" with roles [Admin] (jti: 382660f2-7cf6-4a60-9967-a52afcedffe3, expires: 2024-10-26T06:06:06Z)
Roles:
Admin, Analyst, Continuous Integration, Network Graph Viewer, None, Sensor Creator, Vulnerability Management Approver, Vulnerability Management Requester, Vulnerability Report Creator
Access:
rw Access
rw Administration
rw Alert
rw CVE
rw Cluster
rw Secret
rw ServiceAccount
rw VulnerabilityManagementApprovals
rw VulnerabilityManagementRequests
rw WatchedImage
rw WorkflowAdministration
PS C:\Users\suyash.sambhare\Downloads>
Congratulations! 🤩🎀🩶
You have successfully installed and authenticated RoxCtl.
Top comments (0)