Getting Started

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
burp	commercial	Performs actions on Burp Scanner artifacts
change_passkey	internal	changes the passkey for encryption/decryption
catalog	internal	Diagnostic tool for comparing and managing catalogs
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
crowdstrike	commercial	CrowdStrike Integration to load threat
decrypt	internal	decrypts config file during runtime
defender	commercial	syncs Microsoft Defender alerts and recommendations for both devices and cloud
dependabot	commercial	Create an assessment and child issues
emass	public	generates eMASS templates and populates with data
encrypt	internal	encrypts config file to protect 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
gcp	commercial	GCP Integrations
gitlab	commercial	GitLab integration to pull issues
healthcheck	internal	performs healthcheck to ensure RegScale application and database are online
init	internal	creates a new init.yaml configuration file for the CLI
issues	public	Performs actions on POAM CLI Feature to update issues
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
nexpose	commercial	Performs actions on Nexpose files
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
salesforce	commercial	Sync data between Salesforce Cases & RegScale Issues
servicenow	commercial	syncs issues from RegScale into ServiceNow incidents
sicura	commercial	Sicura integration
snyk	commercial	Performs actions on Snyk export files.
sonarcloud	commercial	Create an assessment and child issues
stig	public	processes STIG files and loads as asset checks in RegScale
tenable - io	commercial	Performs actions on the Tenable.io
tenble - nessus	commercial	Import Nessus scans and assets to RegScale
tenable - sc	commercial	Performs actions on the Tenable.sc API
validate_token	internal	ensures JWT token is valid in RegScale
version	internal	Display the version information and exit
wiz	commercial	syncs scan data, inventory, issues, threats, and vulnerabilities into RegScale

Installing the CLI

Prerequisites

• You must ensure a supported version of Python is installed on the machine ( >= 3.9.0 & <=3.11)
  • Python Download
• Ensure that pip is installed
  • Pip: Download
• The machine running the CLI needs to be able to access Pypi.org
  • If using a proxy, set the proxy for pip pip config set global.proxy http(s)://<proxy>:<port>
• 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\Python311\Scripts to the Python Path, where Python311 denotes your version number and YOURUSER is your user name.
• NOTE: Windows users require the Visual Studio C++ Build Tools available here

Recommended Run environment - virtual python

We strongly recommend you use a python virtual environment to run the regscale-cli to ensure isolation from other python instances on your machine. To set up a virtual environment, change to a working directory where you plan to install regscale-cli and then:

• Ensure you are calling the python install version between 3.9 and 3.11

Linux / Mac OS

python --version

Windows

c:\>Python.exe --version

• Create the virtual environment

Linux / Mac OS

python -m venv venv

Windows

c:\>Python.exe -m venv venv

• Activate the virtual environment

Linux / Mac OS

source venv/bin/activate

Windows Cmd

.\venv\Scripts\activate.bat

Windows PowerShell

.\venv\Scripts\Activate.ps1

• To deactivate after you're done running the CLI:

deactivate

NOTE: Repeat the activation step above each time you run the CLI.

Install the CLI

The CLI is available on PyPi under the RegScale CLI Project. To install the CLI on your machine run the following commands:

Linux / MacOs

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

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.

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:

console

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:

Text

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.

A sample of init.yaml file is shown below:

adAccessToken: <createdProgrammatically>
adAuthUrl: https://login.microsoftonline.com/
adClientId: <myClientIdGoesHere>
adClientSecret: <mySecretGoesHere>
adGraphUrl: https://graph.microsoft.com/.default
adTenantId: <myTenantIdGoesHere>
assessmentDays: 10
azure365AccessToken: <createdProgrammatically>
azure365ClientId: <myClientIdGoesHere>
azure365Secret: <mySecretGoesHere>
azure365TenantId: <myTenantIdGoesHere>
azureCloudAccessToken: <createdProgrammatically>
azureCloudClientId: <myClientIdGoesHere>
azureCloudSecret: <mySecretGoesHere>
azureCloudSubscriptionId: <mySubscriptionIdGoesHere>
azureCloudTenantId: <myTenantIdGoesHere>
cisaKev: https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json
crowdstrikeBaseUrl: <crowdstrikeApiUrl>
crowdstrikeClientId: <myClientIdGoesHere>
crowdstrikeClientSecret: <mySecretGoesHere>
dependabotId: <myGithubUserIdGoesHere>
dependabotOwner: <myGithubRepoOwnerGoesHere>
dependabotRepo: <myGithubRepoNameGoesHere>
dependabotToken: <myGithubPersonalAccessTokenGoesHere>
domain: <<filled out programmatically after logging in to RegScale>
evidenceFolder: ./evidence
failScore: 30
gcpCredentials: <path/to/credentials.json>
gcpOrganizationId: <000000000000>
gcpProjectId: <000000000000>
gcpScanType: <organization | project>
githubDomain: api.github.com
issues:
  amazon:
    high: 30
    low: 365
    minimumSeverity: low
    moderate: 90
    status: Open
    useKev: true
  aqua:
    critical: 30
    high: 30
    low: 180
    minimumSeverity: low
    moderate: 90
    status: Open
    useKev: true
  aws:
    high: 30
    low: 365
    moderate: 90
    status: Open
  defender365:
    high: 30
    low: 365
    moderate: 90
    status: Open
  defenderCloud:
    high: 30
    low: 365
    moderate: 90
    status: Open
  ecr:
    critical: 30
    high: 30
    low: 180
    minimumSeverity: low
    moderate: 90
    status: Open
    useKev: true
  jira:
    high: 30
    highest: 7
    low: 180
    lowest: 365
    medium: 90
    status: Open
  nexpose:
    critical: 30
    high: 30
    low: 180
    minimumSeverity: low
    moderate: 90
    status: Open
    useKev: true
  prisma:
    critical: 30
    high: 30
    low: 180
    minimumSeverity: low
    moderate: 90
    status: Open
    useKev: true
  qualys:
    high: 30
    low: 365
    moderate: 90
    status: Open
  salesforce:
    critical: 7
    high: 30
    low: 365
    medium: 90
    status: Open
  snyk:
    critical: 30
    high: 30
    low: 180
    minimumSeverity: low
    moderate: 90
    status: Open
    useKev: true
  tenable:
    critical: 3
    high: 5
    low: 180
    minimumSeverity: low
    moderate: 30
    status: Draft
    useKev: false
  wiz:
    critical: 30
    high: 90
    low: 365
    medium: 90
    status: Open
  xray:
    critical: 30
    high: 30
    low: 180
    minimumSeverity: low
    moderate: 90
    status: Open
    useKev: true
jiraApiToken: <jiraApiToken>
jiraUrl: <jiraUrl>
jiraUserName: [email protected]
maxThreads: 1000
nistCpeApiKey: <myNistCpeApiKey>
oktaApiToken: Can be a SSWS token from Okta or created programmatically
oktaClientId: <oktaClientIdGoesHere>
oktaUrl: <oktaUrlGoesHere>
oscalLocation: /opt/OSCAL
otx: enter AlienVault API key here
passScore: 80
pwshPath: /opt/microsoft/powershell/7/pwsh
qualysPassword: <qualysPassword>
qualysUrl: https://yourcompany.qualys.com/api/2.0/fo/scan/
qualysUserName: <qualysUserName>
salesforcePassword: <salesforcePassword>
salesforceToken: <salesforceSecurityToken>
salesforceUserName: <salesforceUserName>
sicuraToken: <mySicuraToken>
sicuraUrl: <mySicuraUrl>
snowPassword: <snowPassword>
snowUrl: <mySnowUrl>
snowUserName: <snowUserName>
sonarToken: <mySonarToken>
stigBatchSize: 100
tenableAccessKey: <tenableAccessKey>
tenableMinimumSeverityFilter: low
tenableSecretKey: <tenableSecretKey>
tenableUrl: https://cloud.tenable.com
timeout: 60
token: <filled out programmatically after logging in to RegScale>
userId: <filled out programmatically after logging in to RegScale>
wizAccessToken: <createdProgrammatically>
wizAuthUrl: https://auth.wiz.io/oauth/token
wizExcludes: My things to exclude here
wizInventoryFilterBy: <wizInventoryFilterBy>
wizIssueFilterBy: <wizIssueFilterBy>
wizLastInventoryPull: <wizLastInventoryPull>
wizMaxConnectionPoolWorkers: 10
wizReportAge: 15
wizScope: <filled out programmatically after authenticating to Wiz>
wizUrl: <my Wiz URL goes here>

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.

Supporting Internally Issued Certificate

Three options to allow the RegScale CLI to connect over SSL to the RegScale platform that is using a certificate signed by an internally self-signed CA.

Append to Existing CA Trust File

If the RegSale platform was deployed with a certificate from an internally self-signed CA, the CA pem encoded certificate needs to be appended to the cacert.pem file

cat ca.pem >> .local/python3.10/site-packages/certifi/cacert.pem

Using a Custom CA Bundle to Trust an Internal Signed CA

Place the CA Certificate pem file in a known location and export REQUESTS_CA_BUNDLE=/path/ca.pem

export REQUESTS_CA_BUNDLE=/path/ca.pem

Note: This will only trust certificates signed by the CA or CA root certificates in the ca.pem file.

Disabling Certificate Verification

To disable the SSL certificate verification by add ssl_verify=false to the init.yaml file

Upgrading or Uninstalling the CLI

Upgrade the CLI

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

console

pip install regscale-cli --upgrade

• Manually force a specific version upgrade as follows:

console

pip install -i regscale-cli==1.1.8

Uninstall the CLI

To uninstall, run the following command:

console

pip uninstall regscale-cli