HomeGuidesAPI ReferenceChangelog
Log In
Guides

Getting Started

Suggest Edits

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):

CommandTypeDescription
Aboutinternaldisplays version and other information about the CLI
Azure AD SSOcommercialperforms directory and user synchronization functions
Admin Actionsinternalperform administrative actions in RegScale via like send_reminders and update_compliance_history
alienvaultcommercialloads AlienVault OTX pulses as threats
aquacommercialperforms actions on Aqua Scanner artifacts
Assessmentinternalbuild, edit, and load assessments from Excel
awscommercialAWS Security Hub integration
azurecommercialMicrosoft Intune integration
burpcommercialPerforms actions on Burp Scanner artifacts
change_passkeyinternalchanges the passkey for encryption/decryption
cataloginternalDiagnostic tool for comparing and managing catalogs
cisapublicsyncs DHS CISA alerts and Known Exploitable Vulnerabilities (KEV)
compareinternalfile comparison tool for audit support
configinternalmanage parameters and configuration for the CLI
control-editorinternalbuild, edit, and load control implementations from Excel
crowdstrikecommercialCrowdStrike Integration to load threat
decryptinternaldecrypts config file during runtime
defendercommercialsyncs Microsoft Defender alerts and recommendations for both devices and cloud
dependabotcommercialCreate an assessment and child issues
emasspublicgenerates eMASS templates and populates with data
encryptinternalencrypts config file to protect secrets
env_infointernaldisplays information about the environment and the RegScale CLI
evidenceinternaldownloads evidence files and zips them to create an audit package
fedramppublicloads FedRAMP SSP Word document or OSCAL into RegScale
gcpcommercialGCP Integrations
gitlabcommercialGitLab integration to pull issues
healthcheckinternalperforms healthcheck to ensure RegScale application and database are online
initinternalcreates a new init.yaml configuration file for the CLI
issuespublicPerforms actions on POAM CLI Feature to update issues
jiracommercialsyncs issues from RegScale into JIRA tickets
logininternallogs into the RegScale application via the CLI
migrationsinternalutility for migrating legacy data to new schema
nexposecommercialPerforms actions on Nexpose files
nistpublicutilities for sorting NIST controls
oktacommercialperforms directory and user synchronization functions
oscalpublicprocesses and loads OSCAL catalog, profiles, and components into RegScale
qualyscommercialsyncs scan data from Qualys into RegScale
salesforcecommercialSync data between Salesforce Cases & RegScale Issues
servicenowcommercialsyncs issues from RegScale into ServiceNow incidents
sicuracommercialSicura integration
snykcommercialPerforms actions on Snyk export files.
sonarcloudcommercialCreate an assessment and child issues
stigpublicprocesses STIG files and loads as asset checks in RegScale
tenable - iocommercialPerforms actions on the Tenable.io
tenble - nessuscommercialImport Nessus scans and assets to RegScale
tenable - sccommercialPerforms actions on the Tenable.sc API
validate_tokeninternalensures JWT token is valid in RegScale
versioninternalDisplay the version information and exit
wizcommercialsyncs scan data, inventory, issues, threats, and vulnerabilities into RegScale
xraycommericalperforms actions on xray files

Installing the CLI

Prerequisites

  • You must ensure a supported version of Python is installed on the machine ( >= 3.9.0 & <=3.12)
  • Ensure that pip is installed
  • 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.12
python --version

c:\>Python.exe --version
  • Create the virtual environment
python -m venv venv

c:\>Python.exe -m venv venv
  • Activate the virtual environment
source venv/bin/activate

.\venv\Scripts\activate.bat

.\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:

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

# 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:

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.

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:

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

Updated 3 months ago