Overview

Overview and CLI Configuration

The RegScale Command Line Interface (CLI) is available for Enterprise Edition (EE) customers to perform advanced automations and to scale-out integrations for bulk data processing. The CLI is published as a Python library that can be installed via PIP which is the standard methodology for installing Python Packages. The CLI consists of several components:

RegScale Python PIP Package - the RegScale CLI for executing commands
init.yaml file - configuration file supporting the CLI
RegScale CLI Container - a containerized version of the CLI that contains all dependencies that are pre-installed and configured.

CLI Libraries

The CLI will continue to expand and evolve over time to support additional automations both with RegScale and with popular commercial and government tools. Each library below has its own documentation which details the list of CLI commands available for each library. The current list is shown below (broken out between internal RegScale CLI functions, government integrations, and commercial integrations):

Command	Type	Description
About	internal	displays version and other information about the CLI
Azure AD SSO	commercial	performs directory and user synchronization functions
Admin Actions	internal	perform administrative actions in RegScale via like send_reminders and update_compliance_history
alienvault	commercial	loads AlienVault OTX pulses as threats
Assessment	internal	build, edit, and load assessments from Excel
aws	commercial	AWS Security Hub integration
azure	commercial	Microsoft Intune integration
catalog	internal	Diagnostic tool for comparing and managing catalogs
change_passkey	internal	changes the passkey for encryption/decryption
cisa	public	syncs DHS CISA alerts and Known Exploitable Vulnerabilities (KEV)
compare	internal	file comparison tool for audit support
config	internal	manage parameters and configuration for the CLI
control-editor	internal	build, edit, and load control implementations from Excel
decrypt	internal	decrypts config file during runtime
defender	commercial	syncs Microsoft Defender alerts and recommendations for both devices and cloud
emass	public	generates eMASS templates and populates with data
encrypt	internal	encrypts config file to protec secrets
env_info	internal	displays information about the environment and the RegScale CLI
evidence	internal	downloads evidence files and zips them to create an audit package
fedramp	public	loads FedRAMP SSP Word document or OSCAL into RegScale
healthcheck	internal	performs healthcheck to ensure RegScale application and database are online
init	internal	creates a new init.yaml configuration file for the CLI
jira	commercial	syncs issues from RegScale into JIRA tickets
login	internal	logs into the RegScale application via the CLI
migrations	internal	utility for migrating legacy data to new schema
nist	public	utilities for sorting NIST controls
okta	commercial	performs directory and user synchronization functions
oscal	public	processes and loads OSCAL catalog, profiles, and components into RegScale
qualys	commercial	syncs scan data from Qualys into RegScale
servicenow	commercial	syncs issues from RegScale into ServiceNow incidents
stig	public	processes STIG files and loads as asset checks in RegScale
tenable	commercial	syncs scan data from Tenable into RegScale
validate_token	internal	ensures JWT token is valid in RegScale
wiz	commercial	syncs scan data, inventory, issues, threats, and vulnerabilities into RegScale

Pre-Requisites

You must ensure the latest version of Python is installed on the machine ( >= 3.9.0 & <=3.11)
- On Ubuntu, you can install with sudo apt install python3.9
Ensure that pip is installed for the OS you are using on the sidecar
NOTE: If you receive a path error on Linux, you may need to logout of the session and back in to make the path available for the user (common issue on Ubuntu)

Using the CLI

The CLI is available on PyPi under the RegScale CLI Project. To install the CLI on your machine, make sure Python is available ( >= 3.9.0 & <=3.11), pip is installed for package management, and then run the following commands:

# Install CLI from PyPi
python3 -m pip install regscale-cli

for Windows:

# Install CLI from PyPi
python.exe -m pip install regscale-cli

These commands will install the RegScale CLI, manually update GraphQL dependencies, create a directory for processing artifacts/logs, and then pull down a template for the init.yaml file for you to edit as shown in the next section.

NOTE: If you see any warnings during the install about the PATH for RegScale, make sure you update the path with your directory.

For Linux/Mac, example here: export PYTHONPATH=$PYTHONPATH:/home/howieavp76/.local/bin.

For a Windows installation, you should update the system or user environment variables to bring in the Python scripts folder:
add C:\Users\YOURUSER\AppData\Local\Programs\Python\Python310\Scripts to the Python Path, where Python310 denotes your version number and YOURUSER is your user name.

Using the CLI in a Container

A common use case for the CLI is to spin up jobs at some frequency for bulk data processing. Many customers are now using containers to spin up the RegScale CLI to perform a job and then tear it self down to keep costs low in a cloud-native style architecture for data processing. To access the container, you can pull from the RegScale CLI Docker Hub:

docker pull regscale/regscale-cli:latest

Further instructions for using the CLI will be made available in the Docker Hub README.

Initialization

Initialize your CLI environment with the init command:

regscale init

The CLI will generate a default init.yaml file and prompt you for RegScale domain and to log in:

Initializing your RegScale CLI environment...
Would you like to change your RegScale domain from https://regscale.yourcompany.com/? (Y/n): y

Please enter your RegScale domain.
Example: https://mydomain.regscale.com/
Domain: https://regscale.mycomapny.com
[2023/01/20 04:32;41] INFO     [2023/01/20 04:32;41] [INFO ]  Valid URL provided, regscale.py:349
                               init.yaml has been updated.                                       
Would you like to log in to your RegScale instance? (Y/n): y
Please enter your username: rross
Please enter your password:

In Infrastructure as Code scenarios, you can initialize your CLI environment and pass parameters inline:

regscale init --domain https://regscale.mycompany.com --username rross --password <yourpassword>

Alternatively, initialize your CLI environment and skip prompts with the --skip-prompts flag:

regscale init --skip-prompts

The CLI is driven by a set of configurations that are specified in the init.yaml file.

The structure of init.yaml file is shown below:

###################################################################
#  REGSCALE CONFIG
###################################################################
domain: https://regscale.yourcompany.com/
token: Bearer <my JWT here>
assessmentDays: 10
userId: 8d8d5468-74f9-499d-976c-bca671e19b15
maxThreads: 1000
###################################################################
#  WIZ CONFIG
###################################################################
wizAccessToken: <createdProgrammatically>
wizClientId: <myClientIdGoesHere>
wizClientSecret: <mySecretGoesHere>
wizScope: <filled out programmatically after authenticating to Wiz>
wizUrl: <my Wiz URL goes here>
wizAuthUrl: https://auth.wiz.io/oauth/token
wizExcludes: My things to exclude here
###################################################################
#  ACTIVE DIRECTORY CONFIG
###################################################################
adAuthUrl: https://login.microsoftonline.com/
adGraphUrl: https://graph.microsoft.com/.default
adAccessToken: <createdProgrammatically>
adClientId: <myClientIdGoesHere>
adSecret: <mySecretGoesHere>
adTenantId: <myTenantIdGoesHere>
###################################################################
#   AZURE MICROSOFT DEFENDER 365 CONFIG
###################################################################
azure365AccessToken: <createdProgrammatically>
azure365ClientId: <myClientIdGoesHere>
azure365Secret: <mySecretGoesHere>
azure365TenantId: <myTenantIdGoesHere>
###################################################################
#   AZURE MICROSOFT DEFENDER FOR CLOUD CONFIG
###################################################################
azureCloudAccessToken: <createdProgrammatically>
azureCloudClientId: <myClientIdGoesHere>
azureCloudSecret: <mySecretGoesHere>
azureCloudTenantId: <myTenantIdGoesHere>
azureCloudSubscriptionId: <mySubscriptionIdGoesHere>
###################################################################
#   JIRA CONFIG
###################################################################
jiraUrl: <myJiraUrl>
jiraUserName: <jiraUserName>
jiraApiToken: <jiraAPIToken>
###################################################################
#   SERVICENOW CONFIG
###################################################################
snowUrl: <mySnowUrl>
snowUserName: <snowUserName>
snowPassword: <snowPassword>
###################################################################
#   OKTA CONFIG
###################################################################
oktaUrl: https://mycompany.okta.com/
oktaApiToken: Can be a SSWS token from Okta or created programmatically
oktaClientId: <oktaClientIdGoesHere>
oktaScopes: okta.users.read okta.roles.read
oktaSecretKey: 
	d: get from Okta,
	p: get from Okta,
	q: get from Okta,
	dp: get from Okta,
	dq: get from Okta,
	qi: get from Okta,
	kty: get from Okta,
	e: get from Okta,
	kid: get from Okta,
	n: get from Okta
###################################################################
#   OSCAL CONFIG
###################################################################
oscalCliPath: /home/myuser/OSCAL

The YAML file is read during the execution of commands and must be set properly for the CLI to execute. Each of the fields in the configuration file are described below:

domain - the URL for your instance of RegScale
token - the JWT bearer token for authenticating requests. This can be set one of three ways:
- Paste from your user profile after logging into RegScale
- Use the RegScale login CLI to authenticate which will automatically set the token in the YAML file (good for 24 hours)
- Using Administrator privileges in RegScale, create a service account which can generate a long-running token that can be used for API access. Paste this token into the YAML file.
assessmentDays - Number of days to add to today's date for new assessments created in RegScale created via RegScale CLI
userId - your RegScale user ID which is a GUID value (NOTE: This is programmatically set when logging in.)
maxThreads - The total number of threads the application is allowed to use. (NOTE: Changing this number can have a negative or positive impact on performance.)

NOTE: The init.yaml file contains sensitive keys and secrets and should be stored securely. Non-RegScale configuration is described on the CLI page for each specific integration we support.

Upgrading the CLI

If you are ready to upgrade to the latest version of the CLI, run the following command:

pip install regscale-cli --upgrade

Manually force a specific version upgrade as follows:

pip install -i regscale-cli==1.1.8

Uninstall the CLI

To uninstall, run the following command:

pip uninstall regscale-cli