Command-Line Interface (CLI)¶
Introduction¶
The CIS-CAT Pro Assessor Command-Line Interface (CLI) is the standard application to run Benchmark assessments. The CLI is the best option for those looking to automate assessments or using headless or server environments. The CLI is included with all installations of CIS-CAT Pro Assessor v4.
This guide covers:
Note
The example commands in this guide utilize the Microsoft Windows batch script. Ensure you edit them for Unix/Linux usage.
Run CLI¶
The CIS-CAT application scripts (Assessor-CLI.bat or .sh) must be executed from the command line using root, Administrator, or an equivalently privileged principal.
Windows¶
1. Open Command Prompt and navigate to the location where Assessor v4 was extracted (C:\<folder>\Assessor).
Note
For local scans, Command Prompt must be run as an Administrator or user with administrator privileges.
2. Enter Assessor-CLI.bat to run the Assessor CLI.
Linux/Mac¶
1. Open Terminal and navigate to the location where Assessor v4 was extracted (<folder>/Assessor).
Note
For local scans, Terminal must be run as a sudo user or user with root privileges.
2. Enter ./Assessor-CLI.sh to run the Assessor CLI.
Assessment Modes¶
There are three modes or methods to run assessments in Assessor CLI. Use the method best fit for your needs at any given time.
| Mode | Description |
|---|---|
| Interactive Mode | Walk through steps to configure and run a local or remote scan |
| Manual Mode | Use a session.properties file to assess multiple local or remote target systems against a Benchmark. |
| Automatic Mode | Use a configuration XML file to run a fully automated scan of any combination of local or remote endpoints against multiple Benchmark assessments. |
For further details and examples of all the available CLI options, refer to the Command-Line Options section.
Interactive Mode¶
Interactive Mode is the most basic way to run Assessor CLI. The application will walk you through each step to set up and run a local or remote scan.
1. Execute the following command:
Assessor-CLI.bat -i.
2. Select a remote or local scan.
3. Enter the number of the Benchmark against which to assess the target system.
4. Enter the number of the profile.
5. Enter the number of the report type for the output.
Once all inputs are entered the Assessor will create a profile and run Inspec.
The assessment is complete the results will be shown to screen. The report files will be written to the Assessor/reporting/output folder.
Manual Mode¶
Manual Mode allows you to use a session.properties file to assess one or more target systems against a Benchmark.
Tip
Learn how to configure a session properties file.
Run Assessor with session.properties File¶
Note
If the sessions.properties file is not specified in the command, CIS-CAT Pro Assessor will use the default one located in the Assessor root folder.
-
Execute this command:
Assessor-CLI.bat -b benchmarks/
-xccdf.xml
Run Assessment with Renamed or Relocated sessions.properties File¶
If you are using a renamed sessions.properties file or a file that is not in the Assessor root folder, execute the command with the -sessions flag:
Assessor-CLI.bat -b benchmarks/<benchmark_name>-xccdf.xml -sessions <file_location>
Example
Run Assessment with Encrypted session.properties File¶
If you are using an encrypted session.properties file, execute the command with the -sessions and fp options:
Assessor-CLI.bat -b benchmarks/<benchmark_name>-xccdf.xml -sessions <session_file> -fp <password>.
Example
Automatic Mode¶
Automatic Mode allows you to use a configuration XML file to run a fully automated scan of any combination of local or remote endpoints against multiple Benchmarks.
Tip
Learn how to configure a configuration XML file.
Run Assessor with Configuration XML File¶
Execute the following command:
Assessor-CLI.bat -cfg <config XML file>.
Run Assessment with Encrypted Configuration XML File¶
If you are using an encrypted configuration file, execute the command with the fp or --filepassword option:
Assessor-CLI.bat -cfg <config XML file> -fp <password>.
Command-Line Options¶
The Assessor CLI performs functions associated with Benchmark configuration assessments.
Any file references made in command-line options may utilize either absolute or relative paths. Relative paths will be parsed from the application's "base" directory, which is set on application start-up to be the directory containing the Assessor-CLI.jar file.
Basic Options¶
Basic operation of CIS-CAT Pro Assessor CLI allows a user to get help, list available content, or step through the selection of Benchmarks and profiles prior to running a configuration assessment.
Options¶
The following table summarizes a number of options controlling which reports to generate, naming of reports, and functionality allowing users to upload reports to a URL.
| Short Option | Long Option | Argument | Description |
|---|---|---|---|
-h |
--help |
N/A | Display CIS-CAT Pro Assessor help output. |
-l |
--list |
N/A | List the Benchmarks available for assessment. |
-lv |
--list-verbose |
N/A | Combine with the -l option to display the full file path to the Benchmark, for later assessment using the -b option. |
-i |
--interactive |
N/A | Execute the Assessor in Interactive mode specifically for Benchmark assessments, allowing the user to manually select a Benchmark and profile for assessment. |
-cfg |
--config-xml |
<CONFIGURATION XML FILE> |
Execute the Assessor using configuration information found in the configuration XML file. This file allows users to override user properties, configure interactive values, set up sessions, and define the various assessments to perform. View Set Up Configuration XML file for more information. |
Examples¶
Display the CIS-CAT Pro Assessor help information:
Assessor-CLI.bat -h
List all available Benchmarks:
Assessor-CLI.bat -l
List all available Benchmarks (including path information for use with the -b option)
Assessor-CLI.bat -l -v
Execute an assessment of a Benchmark/data-stream in Interactive mode:
Assessor-CLI.bat -i
Execute an assessment of an OVAL Definitions file in Interactive mode:
Assessor-CLI.bat -i -o
Execute an assessment or set of assessments using information found in a saved configuration XML file:
Assessor-CLI.bat -cfg C:\CIS\assessment-configuration.xml
Benchmark/Data Stream Collection Options¶
The Benchmark and Data Stream collection options provide users the ability to select Benchmarks, Data Streams, and the relevant profile for assessment.
Options¶
The following table summarizes a number of options controlling which reports to generate, naming of reports, and functionality allowing users to upload reports to a URL.
| Short Option | Long Option | Argument | Description |
|---|---|---|---|
-b |
--benchmark |
<BMK-OR-DSC> |
Specify either an absolute path to the Benchmark file or a path relative to the Assessor's base directory. The <BMK-OR-DSC> argument represents either a Benchmark XCCDF file, or the SCAP 1.2-formatted data stream collection file. If the file name contains a parentheses, then the Benchmark name must be enclosed in double quotes. |
-dm |
--data-stream |
<DATA-STREAM> |
Used only when the -b option selects a Data Stream Collection file, the -dm option specifies, within the collection, the ID of the data stream to be assessed. |
-cl |
--checklist |
<CHECKLIST> |
Used only in conjunction with the -dm option, the -cl option specifies, within the data stream, the ID of the checklist (Benchmark) to be assessed. |
-p |
--profile |
<PROFILE> |
Specify either a profile name (e.g., Level-1) or the profile ID (e.g., xccdf_org.cisecurity.benchmarks_profile_Level_1).Note: If there are spaces in the profile name, it must be wrapped in double quotes, such as "Level 2" |
-bi |
--benchmark-info |
N/A | When used with the -b option, this option displays information about the selected content, including (for data stream collections) data streams, checklists, and (for all content) profile information.When used by itself, this option creates a text file listing all of the Benchmarks available in the benchmarks folder along with the profiles available for each Benchmark. This list is generated in the folder where the Assessor is installed. |
Examples¶
Execute an assessment against the CIS Microsoft Windows 10 Benchmark, using the relative path to the Benchmark file and automatically selecting the first profile:
Assessor-CLI.bat -b "benchmarks\CIS_Microsoft_Windows_Server_2016_RTM_(Release_1607)_Benchmark_v1.3.0-xccdf.xml"
Note
The CIS Benchmark name contains parentheses. In this case, the entire path must be enclosed with double quotes or the assessment will not execute.
Execute an assessment against the CIS Microsoft Windows 10 Benchmark, using the relative path to the benchmark file, selecting a specific profile by name:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml -p "Level 1 + BitLocker"
Execute an assessment against the CIS Microsoft Windows 10 Benchmark, using an absolute path to the benchmark file, automatically selecting the first profile:
Assessor-CLI.bat -b C:\CIS\MyBenchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml
Execute an assessment against the CIS Microsoft Windows Server 2016 data stream collection, using the first defaults for data stream, checklist, and profile:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_Server_2016_Benchmark_v1.0.0-datastream.xml
Execute an assessment against the CIS Microsoft Windows Server 2016 data stream collection, using a specific data stream and the first defaults for checklist and profile:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_Server_2016_Benchmark_v1.0.0-datastream.xml -dm scap_org.cisecurity_datastream_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark
Execute an assessment against the CIS Microsoft Windows Server 2016 data stream collection, using a specific data stream and checklist but the default-first profile:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_Server_2016_Benchmark_v1.0.0-datastream.xml -dm scap_org.cisecurity_datastream_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark -cl xccdf_org.cisecurity.benchmarks_benchmark_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark
Execute an assessment against the CIS Microsoft Windows Server 2016 data-stream collection, using a specific data-stream, checklist, and profile:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_Server_2016_Benchmark_v1.0.0-datastream.xml -dm scap_org.cisecurity_datastream_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark -cl xccdf_org.cisecurity.benchmarks_benchmark_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark -p "Level 1 - Member Server"
Display extensive information about a specific benchmark:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_Server_2016_Benchmark_v1.0.0-datastream.xml -bi
Create a text file listing all available Benchmarks and their profiles:
Assessor-CLI.bat -bi
Reporting Options¶
The Assessor can generate assessment results in any of these report formats:
- HTML
- CSV
- TXT
- JSON
By default, the Assessor also generates XML documents that can be uploaded directly to the CIS SecureSuite Platform, or transformed into more human-readable formats (HTML, CSV, or TXT).
- Asset Reporting Format (ARF)
Contains asset information for the assessed endpoint, Benchmark/Data Stream that was assessed, system characteristics, and assessment results.
- OVAL results with system characteristics
Only generated when OVAL definitions are assessed, this report shows the OVAL results and your target system's characteristics.
Options¶
The following table summarizes a number of options controlling which reports to generate, naming of reports, and functionality allowing users to upload reports to a URL.
| Short Option | Long Option | Argument | Description |
|---|---|---|---|
-rd |
--reports-dir |
<DIRECTORY> |
Configure the location where result reports are written. |
-rp |
--report-prefix |
<PREFIX> |
Configure the first part of the report name generated by the tool. Report names are formatted: [report-prefix]-[timestamp].[extension] (e.g., CIS-CAT-TEST-Windows10-20171218T173220Z.xml.) |
-nts |
--no-timestamp |
N/A | Exclude timestamp in generated report names. |
-html |
N/A | N/A | Generate an HTML report. |
-csv |
N/A | N/A | Generate a CSV report. |
-txt |
N/A | N/A | Generate a plain text report. |
-json |
N/A | N/A | Generate a full JSON report for all configuration assessment results. |
-npr |
N/A | N/A | Generate a JSON report for non-pass configuration assessment results. The report name is formatted: [report-prefix]-[timestamp]-[NonPassing].json |
-u |
--url |
<REPORTS-URL> |
Specify a URL to which Assessor results are uploaded, using HTTP(S) POST. |
-ui |
--ignore-warnings |
N/A | When uploading results to a URL via the -u option, ignore SSL certificate warnings. |
-narf |
--no-arf |
N/A | Disable the generation of the default ARF XML results report. |
-nrf |
--no-report-file |
N/A | Disable the generation of a results report file. Note: When utilizing the -u option, Assessor results are uploaded to the supplied URL, so report files are generally not needed. |
Examples¶
Execute CIS-CAT Pro Assessor CLI interactively, generating an ARF report (by default) and HTML report, saving them to the default reports folder:
Assessor-CLI.bat -i -html
Execute an assessment against the CIS Microsoft Windows 10 Benchmark, using the relative path to the benchmark file, automatically selecting the first profile. Generate both the Asset Reporting Format (ARF) by default and an HTML report. Save the reports to a specific reports folder:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml -html -rd C:\CIS\custom\reports
Execute an assessment against the CIS Microsoft Windows 10 benchmark, using the relative path to the Benchmark file, automatically selecting the first profile. Generate both the Asset Reporting Format (ARF) by default and an HTML report. Save the reports to the default reports folder, but name the reports in a custom format:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml -html -rp "CCPA-Windows10"
Execute an assessment against the CIS Microsoft Windows 10 Benchmark, using the relative path to the Benchmark file, automatically selecting the first profile. Configure the application to not generate any physical report files, but to upload the results to the CIS SecureSuite Platform, ignoring any SSL certificate warnings:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml -nrf -u https://securesuite.example.org/securesuite/api/reports/upload -ui
Logging Options¶
The Assessor CLI can generate log files to provide insights into assessments.
Options¶
The following table describes the various options to control log file generation. By default, the Assessor-CLI application is configured to log at the WARN level.
| Short Option | Long Option | Argument | Description |
|---|---|---|---|
-nl |
--no-logging | N/A | Disable all logging. |
-v |
--error |
N/A | Only write log messages with a level of ERROR. |
-vv |
--warn |
N/A | Write log messages with a level of WARN or ERROR. |
-vvv |
--info |
N/A | Write log messages with a level of WARN, ERROR, or INFO. |
-vvvv |
--debug |
N/A | Write log messages with a level of WARN, ERROR, INFO, or DEBUG. |
-vvvvv |
--trace |
N/A | Write log messages with a level of WARN, ERROR, INFO, DEBUG, or TRACE. |
-vvvvvv |
--all |
N/A | Write all log messages. |
Examples¶
Execute an assessment in Interactive mode with logging at the INFO log level:
Assessor-CLI.bat -i -vvv
Execute an assessment against the CIS Microsoft Windows 10 Benchmark, using the Level 2 profile, writing log messages at the DEBUG log level:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml -p "Level 2" -vvvv
Miscellaneous Options¶
Options¶
| Short Option | Long Option | Argument | Description |
|---|---|---|---|
-sessions |
--sessions |
<SESSIONS.PROPERTIES> |
Use a session properties file to assess multiple endpoints against a Benchmark. The file allows you to specify remote hosts, ports, and credentials which CIS-CAT Pro Assessor uses for connection, collection, and evaluation of Benchmark recommendations. Note: If no session properties file exists or no connections are configured in the file, the Assessor will scan the local machine. |
-props |
--properties |
<PROPERTIES-FILE> |
Customize defaults in an assessor properties file for various runtime properties used during the assessment process. These properties may be customized per assessment or endpoint, by creating individual properties files, and specifying either the full filepath or a path relative to the working directory. If this option is not specified, the CIS-CAT Pro Assessor will load a the default assessor-cli.properties file located C:\Assessor\config |
-D |
N/A | <Property=Value> |
Instead of creating a new assessor properties file for unique assessments, individual user properties may be specified using the -D option together with a property=value pair. This option allows an assessment to override only specific user properties when just a small number differ from the defaults. |
-test |
--test |
N/A | Test connections on any sessions configured to execute during the assessments. These sessions may be loaded from a configuration XML file (-cfg) or from a sessions.properties file (-sessions). When specified, connectivity tests are performed and reported to the user on the Assessor console. Once completed, CIS-CAT Pro Assessor exits. When the -test option is supplied, no assessments take place; only the connectivity tests. |
-q |
--quiet |
N/A | Enable the Assessor to execute without writing any assessment status information to the console. |
Examples¶
Execute an assessment against the CIS Microsoft Windows 10 Benchmark, using the relative path to the benchmark file, automatically selecting the first profile, assessing a number of remote machines, configured in a specific session configuration file:
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml -sessions C:\CIS\sessions\windows_10_machines.properties
Execute an assessment against the CIS Oracle Database 11g R2 benchmark, selecting the Windows Server Host OS profile, and configuring the required interactive values:
Assessor-CLI.bat -b benchmarks\CIS_Oracle_Database_11g_R2_Benchmark_v2.2.0-xccdf.xml -p "Level 1 - Windows Server Host OS" -D xccdf_org.cisecurity_value_jdbc.url=jdbc:oracle:thin:user/s3cr3t@DBHOST:1521:devdb -D xccdf_org.cisecurity_value_listener.ora=C:\product\oracle\network\admin\listener.ora
Using a customized properties file defining session connections, test the connectivity of each session and exit:
Assessor-CLI.bat -sessions config\test-sessions.properties -test
Execute the Assessor in quiet mode, assessing against the CIS Microsoft Windows 10 Benchmark
Assessor-CLI.bat -b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark_v1.3.0-xccdf.xml -q
File Encryption Options¶
To help protect sensitive data (e.g., target system login credentials, configuration XML files and sessions.properties) you can encrypt files with passwords. To use encrypted files, users will have to enter the encryption password.
An encrypted copy of the source file is created and written to the C:\Assessor\config, preserving the source file for any future updates and as a backup if the encryption password is forgotten or lost. The name of the encrypted file will be enc_ followed by the source file's name (e.g., enc_config.xml).
Warning
Store the source files in a secure location after creating an encrypted copy.
Passwords with Special Characters¶
Encryption passwords can include special characters. Many special characters do not need to be escaped when they are used within a quoted string, but certain characters (e.g., %) may cause unanticipated consequences.
To help ensure passwords are processed appropriately, enclose passwords in quotes when encrypting a file and when using an encrypted file in the assessment process. The quotes handle most special characters without having to escape those characters and are necessary to preserve any blank spaces in a password.
- For Windows Command-Line, use double quotes.
- For Unix/Linux Terminal, use single quotes.
Options¶
| Short Option | Long Option | Argument | Description |
|---|---|---|---|
-e |
--encrypt |
<FILE TO ENCRYPT> |
Encrypt file with the full path to the sessions.properties file or configuration.xml file to be encrypted, including the file name and its extension. |
-ep |
--encryption-password |
<ENCRYPTION PASSWORD> |
Set the password that will be used to encrypt a sessions.properties file or configuration.xml file. We recommend enclosing this password in quotes. |
-fp |
--file-password |
<FILE PASSWORD> |
Enter the password originally used to encrypt a sessions.properties file or configuration.xml file. This command line option is used in conjunction with the -cfg and -sessions options when utilizing an encrypted configuration XML file or sessions.properties file. We recommended to enclosing this password in quotes. |
Examples¶
Encrypt a configuration XML file:
Assessor-CLI.bat -e C:\Test\config_file.xml -ep "MyP@ssword$@!*&"
Use an encrypted configuration XML file in the assessment process:
Assessor-CLI.bat -cfg C:\Test\enc_config_file.xml -fp "MyP@ssword$@!*&"