CIS-CAT Pro Dashboard Deployment Guide for Windows


Introduction

CIS-CAT Pro Dashboard is a web application built using the Grails Framework. The grails framework uses a hibernate data model, which allows CIS-CAT Pro Dashboard to be database management system (DBMS) agnostic. Grails code compiles into java byte code and runs on the Java virtual machine (JVM). Although CIS-CAT Pro dashboard is database agnostic, CIS only tests and supports use of the listed databases below. The documentation below describes how to deploy CIS-CAT Pro Dashboard on the CIS-preferred, officially supported components.

CIS Supported Relational Database Management Systems (RDBMS)

  • MySQL until version 5.7 (MariaDB 10.2)
  • MS SQL Server
  • Oracle

CIS Preferred Component Installation
The preferred component installation instructions are included in this documentation. Any operating system can host the application server provided the platform can utilize software capable of hosting a Java web application archive (.war file).

  • 2 Windows Server 2016 servers*
  • MS SQL Server 2017 (Server #1)
  • Tomcat 8.5 (Server #2)
  • IIS 10.0 Web Server (Server #2)

*Separate servers are recommended to contain the identified components above for security and performance purposes.

System Recommendations

There are no strict requirements associated with our Dashboard application. Any OS will be suitable so long as it can run Tomcat. Disk space will be minimal on the application server, but will require more space on your database server depending upon the size of your organization and the amount of endpoints you have.

Our test environment uses an AWS t2.large instance (designed for burst processing), which has:

  • 8GB RAM
  • 2 vCPU’s with 4 cores each
  • Microsoft Windows Server 2016 Base

The application is fairly lightweight on processor and memory use. However, when importing results, the usage will spike. Our recommendation would be to conduct importing off hours and then the functionality of the application will not be hindered during business hours.

**Please be advised that it is a necessity for port 1433 and 8080 to be included as inbound rules**

Component Deployment

The following sections describe the installation and configuration of all components necessary to deploy CIS-CAT Pro Dashboard.

Database

SQL Server 2017

Downloaded SQL Server 2017 from the official website.

Install the database following the important steps described below, for more details regarding the installation, please follow the official guide or this unofficial website.

Chose "Custom" type installation and a target location to download.

Once "SQL Server Installation Center" starts, click on "New SQL Server installation or add features to an existing installation"

During the SQL Server installation wizard, make sure that you follow those important steps:

  • In "Install Rules" step, you might have a warning regarding Windows firewall ports which needs to be opened for TCP/IP, as following. Please ignore the warning, the firewall configuration will be set up during the next section.

  • In "Instance Configuration" step, make sure that you select default instance instead of "named instance". The default instance will listen on a static port (1433). The "named instance" will listen on a dynamic port which changes every time the server restarts.

  • In "Database Engine Configuration" step, select Mixed Mode for the authentication. This allows the username and password to be added later to CIS-CAT Pro Dashboard configuration file (ccpd-config.yml). You also need to set the password of the "sa" user.

Please note the following information in order to configure later SQL Server client as well as CIS-CAT Pro Dashboard application:
- hostname/IP of database server (machine which hosts the database)
- port for connecting, by default this is 1433
- username/password for connecting to the database. This will need to be a SQL user, Domain users are not currently supported.

Windows Firewall Configuration for SQL Server

To access an instance of the SQL Server through a firewall, Windows firewall ports needs to be opened for TCP/IP port 1433.

Open Windows Firewall with Advanced Security application. Then in the left pane, right-clicked Inbound Rules, and click New Rule. In the Rule Type dialog box, select Port, then click Next. In the Protocol and Ports dialog box, select TCP. In Specific local ports, put 1433 (default instance SQL Server port), see screenshot. Then in the Action dialog box, select Allow the connection, then click Next.
For more information, please follow the official website

Notes: Your network must also allow traffic on TCP/IP 1433, (If deployed to AWS) your security group in AWS must allow traffic on TCP/IP 1433.

Enable TCP/IP in SQL Server Configuration Manager

Open "SQL Server Configuration Manager" tool and enable TCP/IP as following in "SQL Server Network Configuration/Protocols for ":

Make sure that you restart the database service after, as following:

At this point, you can verify that "sqlservr.exe" process is listening to TCP 1433 port by executing the following command in a Command prompt:

netstat -a -b

SQL Server Management Studio 17 (client)

A SQL Server client should be installed in the distant server (the second server which aims to deploy the application) in order to test connectivity with the database and create the schema for CIS-CAT Pro Dashboard.

Download the client from the official website.

Connected to the distant SQL server using as following:


For "Server name", use the hostname/IP of the database server (machine which hosts the database)

Then click right on "Databases" folder on the left panel (I.E. Object Explorer) then click on "New Database". Set the Database Name to ccpd.

Java 8

Because CIS-CAT Pro Dashboard is a java-based application, members will need to ensure that java is installed. On a Command Prompt, type the following command:

# Ensure Java is installed at the proper version level
java -version

Ensure that the Java version displayed starts with 1.8.***. If it's not the case, please install the JDK/JRE 1.8. Version 8.251+ of Java is NOT supported.

Oracle 1.8 can be downloaded from the official website.

OpenJDK can be used in addition to the Oracle version. OpenJDK 1.8 can be downloaded from the official website.

Application Server

Download tomcat 8.5 32-bit/64-bit Windows Service Installer from the official website.

Install the application server as following, for more details, please follow the official guide.

Required Tomcat Configurations:

  • UTF 8 default character encoding
  • Set Service Startup option
  • maxPostSize attribute
  • Set memory pool
  • Remove default applications

Check "Service startup" during the installation, so Tomcat service will start automatically when the computer starts.
I also suggest to keep "Start Menu Items" checked.

The default tomcat location can be changed during the installation, for the purposes of this User's Guide, assume the tomcat location is set to "C:\tomcat" directory.

To configure Tomcat Options, click right on system tray tomcat icon then click Configure, see screenshot. If the system tray tomcat icon is not present, go to "Start Menu/Apache Tomcat" and click on "Monitor Tomcat"
For example, I added -XX:MaxPermSize=2048m in java option and set up initial Initial memory pool to 1024 and Maximum memory pool to 2048.

The application requires tomcat to use UTF-8 as a default character encoding.
If you receive the following error during an import, that means your system uses another character encoding:

Invalid byte 1 of 1-byte UTF-8 sequence

To change the tomcat default character encoding to UTF-8, please add -Dfile.encoding=UTF-8 option as following:

Tomcat service can be started/stopped from the system tray tomcat monitoring icon or from the windows services screen.

Open C:\tomcat\conf\server.xml and find this line:

<Connector port="8080" protocol="HTTP/1.1"
       connectionTimeout="20000"
       redirectPort="8443"/>

and add the maxPostSize attribute:

<Connector port="8080" protocol="HTTP/1.1"
       connectionTimeout="20000"
       redirectPort="8443"
       maxPostSize="35728640"/>

This will increase the max allowable file size for upload. Many CIS-CAT Pro Assessor ARF reports will be larger than the default size.

Note: During an import, if you receive an exception related to the maxPostSize limitation, make sure that you use CIS-CAT Pro Dashboard 1.1.9+ and CIS-CAT Pro Assessor V4 4.0.12+ with the property set to compress result XML reports. For more details, please refer to the options that are set in the config\assessor-cli.properties.

Security Considerations:
As a final step we want to remove the default applications available from the Tomcat install, including the examples and management applications. These default sites can and will give away information about the environment and present an information security risk.
Please delete every directory inside C:\tomcat\webapps\* to help reduce the attack surface of the application server.

Web Browser

The CIS-CAT Pro Dashboard officially supports Google Chrome web browser. Other browsers may also work but may produce unexpected behavior.

Configuration and Deployment - Installer

This section describes how to configure and deploy the Dashboard using the Installer. For instructions on how to configure and deploy the Dashboard manually, see Configuration and Deployment - Manual.

CIS-CAT Pro Dashboard Runtime Configuration File

Locate the latest version of CIS-CAT Pro Dashboard, pinned at the top of the Downloads section, from CIS WorkBench. Download the CIS-CAT Pro Dashboard bundle that corresponds to your Java installation (32-bit or 64-bit) from CIS WorkBench. Place and extract the bundle on your tomcat instance.

After the CIS-CAT Pro Dashboard bundle has been extracted, please confirm that its contents look similar to the following image (64-bit Java version example shown):

We recommend that the Tomcat application server has been stopped before continuing. Additionally, ensure that component installation including installation of Java8, Tomcat 8.5 and a Database (MySQL, SQL Server or Oracle) has been completed before continuing.

Execute the CIS-CAT Pro Dashboard Installer (CIS-CAT_Pro_Dashboard_Installer-x64.exe in this example).

Welcome (First-time user)

First-time users of the CIS-CAT Pro Dashboard Installer tool will be presented with the below screen.

Welcome (From previous installation)

Users with previous successful use of CIS-CAT Pro Dashboard Installer tool will be presented with the below screen.

Installation Actions

As part of Installation Actions, at least one action must be selected in order to navigate to the next step. As an option, the actions can also be completed together. Both actions must be completed successfully (together or separately) as part of the overall CIS-CAT Pro Dashboard Deployment Guide. The screens will navigate only to the information required to be collected for the installation actions selected.

Configuration File Location

If this is a new installation and “Create/update CIS-CAT Pro Dashboard configuration File” was previously selected, the Configuration File Location screen will be presented. This is the location where CIS-CAT Pro Dashboard configuration file (ccpd-config.yml) will be created.

Application Server Location

For users performing the Installation Action, “Install/update CIS-CAT Pro Dashboard application”, use the below screen to specify the application server home directory. The default value appearing in the field is the recommended location for the application server. However, each environment may vary. For example, if the Tomcat home directory is C:\tomcat, then the CCPD.war will be created under C:\tomcat\webapps\CCPD.war.

Import Directory

It is required to setup processing folders that the Dashboard will use while importing files.Example report folder structure is shown within the CIS-CAT Pro Dashboard Installer.

Environment Variables

Specify the Windows environment variables needed by the CIS-CAT Pro Dashboard. CCPD_CONFIG_FILE points to CIS-CAT Pro Dashboard runtime configuration file (ccpd-config.yml). CCPD_LOG_DIR is the logs directory for CIS-CAT Pro Dashboard.

Application Server URL

Specifies the application URL of the CIS-CAT Pro Dashboard application. Example formats are shown within the CIS-CAT Pro Dashboard Installer.

Email Configuration

The email configuration information is optional and is intended for users that want to send email messages such as password reset requests. CIS-CAT Pro Dashboard must be able to connect to and utilize a valid SMTP server in order to send email messages. CIS-CAT Pro Dashboard utilizes the Grails mail plugin for email communication.

Along with the default sender email address, CIS-CAT Pro Dashboard's mailing configuration must also include connection to a valid SMTP server in order to correctly distribute the "forgot password" messages. Numerous SMTP services exist, such as Gmail, Hotmail, Amazon SES, or in-house SMTP services available through corporate emailing technologies, such as Exchange. CIS-CAT Pro Dashboard can support these SMTP servers, as long as the connection information entered below is correct. By default, the plugin assumes an unsecured mail server configured at localhost on port 25. However, this can be modified in the email configuration screen.

Database Configuration

The primary purpose of this screen is to assist in establishing a connection to the database for the CIS-CAT Pro Dashboard. Three types of databases are currently supported: MySQL, SQL Server and Oracle. Optional functions are available in this screen:

  • Create a Schema: Enter correct Hostname/IP, Port, Username, Password and select the “Create Schema” button. This process currently applies only to MySQL and SQL Server databases.
  • Test Database Connection: Enter correct Hostname/IP, Port, Username, Password, and Schema name and select the “Test Database Connection” button. A message will indicate if the connection was successful.

Summary

The Summary screen is intended for a final review of all information provided in previous screens. If any information is incorrect, the back button can be used to navigate to the appropriate screen and make a correction.

Installation

The system may ask for permission to create a backup of the current configuration file (ccpd-config.yml) and/or a backup of the current CCPD.war file. This is a recommended procedure.

The installer does not preserve or setup LDAP configuration. This is done manually using the backup file to merge any existing LDAP settings to the latest ccpd-config.yml

Complete

If the installer process was successful, the Complete screen will be presented. Select Finish to complete the selected Installer actions. The tomcat application server can now be started if it was previously stopped.

Installer Logs

During the installation, the Installer will create logs. The logs will be created in a directory within the temporary directory of the operating system. Each installation attempt will create an individual log with a timestamp. For Windows, this location would be C:\Users\loggedinUser\AppData\Local\Temp. If you have trouble with the installation, please provide this log file to support@cisecurity.org. To view the log at any time, select the button that says Get Installation log.

Configuration and Deployment - Manual

This section describes how to configure and deploy the Dashboard manually. For instructions on how to configure and deploy the Dashboard using the Installer, see Configuration and Deployment - Installer.

CIS-CAT Pro Dashboard Runtime Configuration File

Download the CIS-CAT Pro Dashboard bundle from CIS WorkBench and place the bundle on the tomcat instance. The latest version of CIS-CAT Pro Dashboard will be pinned at the top of the Downloads section.

Create the CIS-CAT Pro Dashboard runtime configuration file (configured by default for MySQL database): C:\tomcat\ccpd-config.yml, and add to the file the following lines:

environments:
    production:
        grails:
                serverURL: 'http://<url_of_apache_or_tomcat>:8080/CCPD' #if apache is not set up, only tomcat
                #serverURL: 'http://<url_of_apache_or_tomcat>/CCPD' #if apache is set up use
                #serverURL: 'https://<url_of_apache_or_tomcat>/CCPD' #if HTTPS is set up use
        server:
            'contextPath': '/CCPD'
        dataSource:
            dbCreate: update

            #MySQL DB Settings

            driverClassName: org.mariadb.jdbc.Driver
            dialect: org.hibernate.dialect.MySQL5InnoDBDialect
            url: jdbc:mysql://<path_to_mysql_database_server>:3306/<schema_name_of_mysql_database>
            username: <db_user>
            password: <db_password>

            #SQL Server DB Setting

            #driverClassName: com.microsoft.sqlserver.jdbc.SQLServerDriver
            #dialect: org.hibernate.dialect.SQLServer2008Dialect
            #url: jdbc:sqlserver://<path_to_mysql_database_server>:1433;databaseName=<schema_name_of_database>
            #username: <db_user>
            #password: <db_password>

            #Oracle DB Settings

            #driverClassName: oracle.jdbc.OracleDriver
            #dialect: org.hibernate.dialect.Oracle10Dialect
            #url: jdbc:oracle:thin:@<path_to_mysql_database_server>:1521:<schema_name_of_database>
            #username: <db_user>
            #password: <db_password>

            properties:
                  jmxEnabled: true
                  initialSize: 5
                  maxActive: 50
                  minIdle: 5
                  maxIdle: 25
                  maxWait: 10000
                  maxAge: 600000
                  #validationQuery: SELECT 1 from DUAL #ORACLE
                  validationQuery: SELECT 1 #Non-Oracle
                  validationQueryTimeout: 3
                  validationInterval: 15000
                  defaultTransactionIsolation: 2 # ORACLE AND MYSQL
                  #defaultTransactionIsolation: 1 #SQL SERVER ONLY
                  dbProperties:
                        autoReconnect: true

grails:
    mail:
        host: <smtp server host name>
        port: 465
        username: <username>
        password: <password>
        props:
            mail.transport.protocol: "smtps"
            mail.smtp.port: "465"
            mail.smtp.auth: "true"
            mail.smtp.starttls.enable: "true"
            mail.smtp.starttls.required: "true"

database: MySQL
#database: SQLServer
#database: Oracle

Replace the pertinent information, marked with <>, with the specifics of your environment.

This file is also available in the CIS-CAT-Pro-Dashboard bundle.

NOTE: This file is configured for MySQL database by default. If you want to use SQL Server or Oracle, please follow the instructions in Database Configuration section.

NOTE 2: To create a new schema called ccpd for MySQL database using UTF-8 Character set (required), please run the following command:

CREATE DATABASE ccpd CHARACTER SET utf8 COLLATE utf8_general_ci;

MySQL Timezone setting: It is important for the timezone on the application server and the database server to be the same. If this is not the case in your environment you can set the timezone of the database connection using a jdbc option:

jdbc:mysql://<path_to_mysql_database_server>:3306/<schema_name_of_mysql_database>?useLegacyDatetimeCode=false&serverTimezone=<3-letter-timezone>

MySQL 5.7 specific: If you use MySQL 5.7, you need to replace:

database: MySQL

by:

database: MySQL.5.7

Database Configuration

By default the ccpd-config.yml is configured to utilize a MySQL database. Starting with version v1.0.3 you will be able to use MS SQL Server and Oracle Databases as well. In the ccpd-config.yml, there are several settings you need to make to utilize these other DBMS:

SQL Server

You will need to comment out the MySQL configuration and uncomment the SQL Server Section:

#MySQL DB Settings

#driverClassName: org.mariadb.jdbc.Driver
#dialect: org.hibernate.dialect.MySQL5InnoDBDialect
#url: jdbc:mysql://<path_to_mysql_database_server>:3306/<schema_name_of_mysql_database>
#username: <db_user>
#password: <db_password>

#SQL Server DB Setting

driverClassName: com.microsoft.sqlserver.jdbc.SQLServerDriver
dialect: org.hibernate.dialect.SQLServer2008Dialect
url: jdbc:sqlserver://<path_to_mysql_database_server>:1433;databaseName=<schema_name_of_database>
username: <db_user>
password: <db_password>

Then enter the connection information appropriate to your SQL Server database.

In the database properties section, comment out the following property for SQL Server:

#defaultTransactionIsolation: 2 # ORACLE AND MYSQL
defaultTransactionIsolation: 1 #SQL SERVER ONLY

At the very bottom of the file comment out the database entry for MySQL and uncomment the entry for SQL Server:

#database: MySQL
database: SQLServer
#database: Oracle

Oracle

You will need to comment out the MySQL configuration and uncomment the SQL Server Section:

#MySQL DB Settings

#driverClassName: org.mariadb.jdbc.Driver
#dialect: org.hibernate.dialect.MySQL5InnoDBDialect
#url: jdbc:mysql://<path_to_mysql_database_server>:3306/<schema_name_of_mysql_database>
#username: <db_user>
#password: <db_password>

#Oracle DB Settings

driverClassName: oracle.jdbc.OracleDriver
dialect: org.hibernate.dialect.Oracle10Dialect
url: jdbc:oracle:thin:@<path_to_mysql_database_server>:1521:<schema_name_of_database>
username: <db_user>
password: <db_password>

Then enter the connection information appropriate to your Oracle database.

At the very bottom of the file comment out the database entry for MySQL and uncomment the entry for Oracle:

#database: MySQL
#database: SQLServer
database: Oracle

You will also need to comment out the validationQuery in the dataSource properties, and replace it with the one appropriate to Oracle:

validationQuery: SELECT 1 from DUAL #ORACLE
#validationQuery: SELECT 1 #Non-Oracle

Mail Configuration

CIS-CAT Pro Dashboard utilizes the Grails mail plugin in order to send email messages from time to time, including password reset requests. CIS-CAT Pro Dashboard must be able to connect to and utilize a valid SMTP server in order to send these email messages.

Configuration of the mail plugin will be member-specific, and those configuration items will also be added to the C:\tomcat\ccpd-config.yml file, noted above.

Default Sender Email Address

CIS-CAT Pro Dashboard can be configured with a default "sender" email address, indicating that the application has sent a "forgot password" message, allowing users to enter new logon credentials. In the C:\tomcat\ccpd-config.yml file (noted above), add the following section:

---
grails:
    plugin:
        springsecurity:
            ui:
                forgotPassword:
                    emailFrom: "your-email@member-organization.com"

SMTP Configuration

Coupled with the default sender email address, CIS-CAT Pro Dashboard's mailing configuration must also include connection to a valid SMTP server, in order to correctly distribute the "forgot password" messages. Numerous SMTP services exist, such as Gmail, Hotmail, Amazon SES, or in-house SMTP services available through corporate emailing technologies, such as Exchange. CIS-CAT Pro Dashboard can support these SMTP servers, as long as the connection information is correct in the configuration file (the C:\tomcat\ccpd-config.yml noted above).

By default the plugin assumes an unsecured mail server configured at localhost on port 25. However you can change this via the application configuration file (the C:\tomcat\ccpd-config.yml noted above).

For example here is how you would configure the default sender to send with a Gmail account:

Mail Configuration - Gmail

---
grails:
    mail:
        host: "smtp.gmail.com"
        port: 465
        username: "youracount@gmail.com"
        password: "yourpassword"
        props:
            mail.smtp.auth: "true"
            mail.smtp.socketFactory.port: "465"
            mail.smtp.socketFactory.class: "javax.net.ssl.SSLSocketFactory"
            mail.smtp.socketFactory.fallback: "false"

And the configuration for sending via a Hotmail/Live account:

Mail Configuration - Hotmail/Live

---
grails:
    mail:
        host: "smtp.live.com"
        port: 587
        username: "youracount@live.com"
        password: "yourpassword"
        props:
            mail.smtp.starttls.enable: "true"
            mail.smtp.port: "587"

And the configuration for sending via a Outlook account:

Mail Configuration - Outlook

---
grails:
    mail:
        host: "smtp-mail.outlook.com"
        port: 587
        username: "youracount@outlook.com"
        password: "yourpassword"
        props:
            mail.smtp.starttls.enable: "true"
            mail.smtp.port: "587"

And the configuration for sending via a Yahoo account:

Mail Configuration - Yahoo

---
grails:
    mail:
        host: "smtp.correo.yahoo.es"
        port: 465
        username: "myuser"
        password: "mypassword"
        props:
            mail.smtp.auth: "true"
            mail.smtp.socketFactory.port: "465"
            mail.smtp.socketFactory.class: "javax.net.ssl.SSLSocketFactory"
            mail.smtp.socketFactory.fallback: "false"

Environment Variables

Create the following Windows Environment variables:

CCPD_CONFIG_FILE points to CIS-CAT Pro Dashboard runtime configuration file (ccpd-config.yml).
CCPD_LOG_DIR is the logs directory for CIS-CAT Pro Dashboard.

Note: The values of these environment variables can be configured to any location the administrator wishes, and must be to file system locations to which the Tomcat application server can access on startup.

Initial War Deployment

The CCPD.war file can be deployed by utilizing the CIS-CAT Pro Dashboard Installer or it can be done manually. Refer to the below instructions to deploy the CCPD.war file manually.

At this point, it is prudent to deploy the CIS-CAT Pro Dashboard application (the "war") included in the downloadable bundle. The initial deployment of the web application can then be tested via direct connection to the application server on port 8080, without the web server (IIS). This can help identify any application or application server misconfigurations prior to web server (IIS) installation/configuration.

Connect to the application server and transfer the CCPD.war to the c:\tomcat\webapps directory. If Tomcat is running, it should automatically deploy the application. If Tomcat is not running, starting it will deploy the application.

Either way, after the deployment of the CCPD.war file you should keep following these instructions below:

Once Tomcat is done with its deployment you should be able to access the application by entering http://<public url of application server>:8080/CCPD/, into a browser.

You may need to restart tomcat in order to complete the deployment.

CIS-CAT Pro Dashboard will bootstrap in a user with:

username: admin 
password: @admin123

Notes: Your network must allow traffic on 8080. Add an inbound rule in Windows firewall on TCP 8080 (if needed). If deployed to AWS, your security group in AWS must allow traffic on 8080.

Notes 2: If you see this message in the logs: "LegacyImport - Source folder does NOT exist", please ignore it, Import folder will be set up in the next section (Set up Import Folders).

Set up Import Folders

In order to import files into the Dashboard, you need to set up the temp folders that it uses for processing.

Create the three following directories:

c:\tomcat\legacy\source
c:\tomcat\legacy\processed
c:\tomcat\legacy\error

Then login to the system as a user with ROLE_ADMIN, go to the settings menu (gear icon) and click on "System Settings". Set the three following settings:

legacy.sourceDir = c:\tomcat\legacy\source
legacy.processedDir = c:\tomcat\legacy\processed
legacy.errorDir = c:\tomcat\legacy\error

You can also set legacy.processedRetentionNumber setting, which determines how many processed xml files are saved in the process directory after being imported into the Dashboard.

Web Server and Securing Web Traffic

The final configuration is for a web server to proxy the Tomcat instance and to answer traffic on port 80/443.

IIS Web Server Installation

For the purposes of this User's Guide, IIS 10.0 will be installed in Windows Server 2016.

Install IIS 10.0 using Server Manager application as following:

Open Server Manager from the start menu and click on “Add roles and features”:

On "Installation type", select "Role-Based" as following:

In "Server Selection", select your local server that you want to install IIS.

In "Server Roles". check "Web Server (IIS)" as following:

Click "Next" until "Confirmation" then click "Install".
Once installed, IIS server will appear in Server Manager Dashboard.

As a final test, open a web browser and type http://localhost/, you should see the default IIS page.

For more details, please follow "Install IIS Through GUI" from this website.

Initial Site Configuration

Access Internet Information Service (IIS) Manager tool as following:

On the left panel expend the Sites directory and rename "Default Web Site" to "CCPD" as following.

The advantage of using the Default Web Site is that it will work "out-of-the-box" with all definitions and permissions already taken care of.

Note: As a security concern, delete default documents inside C:\inetpub\wwwroot directory, it should contain only iisstart.html and iisstart.png files.

Configure IIS Reverse Proxy to connect to Tomcat

In order to configure IIS Reverse Proxy, two IIS modules need to be installed first:
Download and install "URL Rewrite" module from this website.
Download and install Application Request Routing module from this website.

In Internet Information Service (IIS) Manager tool, click on "CCPD" site on the left panel. Then double click on "URL Rewrite" icon on the right panel:

On URL Rewrite screen, click right and select "Add Rule(s)".

On the rule template, select "Reverse Proxy":

Create the following Reverse Proxy rule:

Note: Public url should use the default http port (80), so no need specify a port in the url.
If your serverURL is http://www.example.com/CCPD, then set www.example.com to "To" field.

For more details regarding URL Rewrite, please follow this website.

The IIS web server should now be configured to serve requests to CIS-CAT Pro Dashboard.

Modify your ccpd-config.yml in order to use your public url http://<public url of web server>/CCPD instead of http://<url_of_apache_or_tomcat>:8080/CCPD, then restart tomcat.
Open a web browser and type http://<public url of web server>/CCPD, you should be redirected to CIS-CAT Pro Dashboard login page.

Note 2: Your network should now block traffic on 8080. Disable the inbound rule in Windows firewall on TCP 8080 (if needed).

Set Application Request Routing

In order to integrate with and establish authentication with CIS WorkBench, certain proxy settings must be configured. Configure the following:

  1. Navigate to the ARR proxy settings under IIS --> Application Request Routing Cache --> Server Proxy Settings
  2. Uncheck Reverse rewrite host in response headers

Securing Web Traffic

The steps above will have the CIS-CAT Pro Dashboard application running over normal HTTP on port 80. This presents a risk as data, including user credentials, will be transmitted in clear text. It is recommended that traffic be secured using HTTPS.

Creating a Self-Signed Certificate using Windows Powershell

The following steps describe how to create a Self Signed Certificate. To request and use a certificate signed by a trusted third-party, please follow this article.

Note : The Self-Signed certificate can be created from IIS but it doesn't allow to set the domain (common name), so a warning message will show up on the web browser when you access the website using https (i.e. "NET::ERR_CERT_COMMON_NAME_INVALID" error in Chrome).

Open Windows Powershell program (start menu/Windows Powershell) then execute the following commands one at a time:

#Create Root Certificate
New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "My Lab Root Certificate Authority" -KeyUsage DigitalSignature,CertSign

#Replacing <> by the thumbprint returned by the previous command
#This command will export the root certificate to c:\safeDirectory
Export-Certificate -Cert cert:\localMachine\my\<Thumprint of Root Certificate> -FilePath "c:\rootCertificate.crt"

#Load the root authority certificate    
$rootcert = ( Get-ChildItem -Path cert:\LocalMachine\My\<Thumprint of Root Certificate>)

#Create Self-Signed certificate ccpd
#If your serverURL is https://www.example.com/CCPD, then the DnsName (common name) must be www.example.com  
New-SelfSignedCertificate -DnsName "<Common name of the web server>"  -CertStoreLocation "cert:\LocalMachine\My" -FriendlyName "ccpd cert" -Signer $rootcert -KeyUsage KeyEncipherment,DigitalSignature

For more details regarding New-SelfSignedCertificate Powershell commands, here is the official website.

Binding website certificate to IIS site

Open IIS manager, click on CCPD site on the left panel then click on "Bindings..." on the right panel.

Click "Add" and add the following Site Binding, using "ccpd cert" certification created previously:

Once created, remove the other binding for port 80, so the application will be accessible only in https.

In ccpd.conf, modify the serverURL so the url should start by https instead of http.

Restart the application server and the web server.

Now if you open a web browser and access the application using https, a message will show up regarding a problem with the website’s security certificate. This issue will be solved in the next section. (i.e. Importing Root Certificate into Trusted Root Certification Authorities)

Importing Root Certificate into Trusted Root Certification Authorities

After completing "Creating a Self-Signed Certificate using Windows Powershell" section, the Root Certificate should be located in c:\rootCertificate.crt.

Open Microsoft Management Console (type "mmc" on Windows search). If "Certificates" folder doesn't show up on the left panel, click on File/"Add Remove Snap-in...":

Double click on "Certificates" then click "Ok".

Now Click right on Certificates/Trusted Root Certification Authorities folder then select "All Tasks/Import":

Click "Next", Browse c:\rootCertificate.crt file, Click "Next" then "Next" then "Finish". Verify that the certificate got imported inside "Trusted Root Certification Authorities" folder:

Before opening a web browser, close every opened web browser first. If you use chrome click on 3 points/Exit or Ctr+Shift+Q instead of the cross icon.
Now if you access the application using https, the web browser will indicate that the connection is secure and the certificate is valid.

Please repeat every step of this section for each client who wants to access the application.

Importing the certificate into the java trust store

This step is required if you want to use the "POST Reports to URL" with https in order to upload an Asset Report Format (ARF) results from CIS-CAT Pro Assessor to CIS-CAT Pro Dashboard. For more details about the integration between the Assessor and the Dashboard, please read the "Importing CIS-CAT Assessor Results" section from CIS-CAT Pro Dashboard User's Guide.

Find the location of the java executable being used to launch Tomcat and host CIS-CAT Pro Dashboard. For the purposes of this guide, assume the location of java can be found at C:\Program Files\Java\jdk1.8.0_144. When using Java 8, the required cacerts file will be located in your JRE directory, here it's at C:\Program Files\Java\jdk1.8.0_144\jre\lib\security\cacerts. The location of the cacerts file should be noted before importing the certificate using keytool.

Finally, using the java keytool application, import the certificate:

# Navigate to the $JAVA_HOME folder's bin directory.
cd C:\Program Files\Java\jdk1.8.0_144\jre\bin

# Execute keytool
keytool -import -alias ccpd -keystore ../lib/security/cacerts -file c:\rootCertificate.crt

The user should be prompted to enter the keystore credentials. By default, this credential is changeit.

# The user will be asked for confirmation
Trust this certificate? [no]:

Answering yes to this confirmation prompt will import the certificate into the trust store.

NOTE: If the application server is currently running, it must be restarted in order to incorporate the trust store.

Upgrading from a previous version

To upgrade from an earlier version of CCPD:

There are two ways to upgrade your current CCPD version.

You can follow the instructions given above and do so by using the CIS-CAT Pro Dashboard Installer or you can follow the manual instructions provided below:

1) Stop your application server. If you followed the deployment guide that would be tomcat.
Tomcat service can be stopped from the system tray tomcat monitoring icon or from the windows services screen:

2) Copy the new CCPD.war into the c:/tomcat/webapps directory.

3) Start the application server, the service can be started from the system tray tomcat monitoring icon or from the windows services screen:

That will redeploy the new war over the old application. CCPD has a bootstrap initialization script that will run on its first deployment that will make necessary data changes.

If there are any additional upgrading steps specific to a release version, information about those steps will be included in that versions README.txt

LDAP/Active Directory Integration (Optional)

With this integration, LDAP/Active Directory will be used to manage user authentication and permissions within CCPD.

Users will use their LDAP/AD credentials to log into the application. LDAP/AD roles and user properties such firstname, lastname and email will be imported. If the user doesn't exist in CCPD, he will be created when he logs in, and granted with basic user roles (ROLE_BASIC_USER and ROLE_USER) by default, plus additional LDAP Roles.

LDAP Configuration

Here is an example of LDAP structure in OpenLDAP:

Based on the above structure, add the following section in the /opt/tomcat/ccpd-config.yml file (noted above):

---
grails:
    plugin:
        springsecurity:
            providerNames: ['ldapAuthProvider','rememberMeAuthenticationProvider','restAuthenticationProvider','anonymousAuthenticationProvider']
            ldap:
                active: true
                context:
                    managerDn: 'cn=Manager,dc=cisecurity,dc=org'
                    managerPassword: 'my_manager_password'
                    server: 'ldap://127.0.0.1:389'
                authorities:
                    retrieveDatabaseRoles: false                   
                    retrieveGroupRoles: true
                    groupSearchBase: 'ou=Groups,dc=cisecurity,dc=org'                  
                    groupSearchFilter: 'uniquemember={0}'
                    groupRoleAttribute: 'cn'        
                    clean:
                        prefix: 'CCPD_'
                search:
                    base: 'dc=cisecurity,dc=org' 
                    filter: '(uid={0})'
                authenticator:
                    passwordAttributeName: 'userPassword'
                mapper:
                    passwordAttributeName: 'userPassword'               
                useRememberMe: true  
            rememberMe:
                persistent: true

Note: If you have previously configured the application to connect to a SMTP server, you need to remove grails: from the above section. So the section will start with plugin: instead.

Active Directory Configuration

Here is an example of Active Directory structure in Windows server 2016:

Based on the above structure, add the following section in the /opt/tomcat/ccpd-config.yml file (noted above):

---
grails:
    plugin:
        springsecurity:
            providerNames: ['ldapAuthProvider','rememberMeAuthenticationProvider','restAuthenticationProvider','anonymousAuthenticationProvider']
            ldap:
                active: true
                context:
                    managerDn: 'CN=Administrator,CN=Users,DC=corp,DC=cisecuritytest,DC=org'
                    managerPassword: 'my_manager_password'
                    server: 'ldap://127.0.0.1:389'
                authorities:
                    ignorePartialResultException: true
                    retrieveDatabaseRoles: false                   
                    retrieveGroupRoles: true
                    groupSearchBase: 'DC=corp,DC=cisecuritytest,DC=org'                  
                    groupSearchFilter: 'member={0}'
                    groupRoleAttribute: 'CN'     
                    clean:
                        prefix: 'CCPD_'                 
                search:
                    base: 'DC=corp,DC=cisecuritytest,DC=org' 
                    filter: 'sAMAccountName={0}'
                auth:
                    hideUserNotFoundExceptions: false
                authenticator:
                    passwordAttributeName: 'userPassword'
                mapper:
                    passwordAttributeName: 'userPassword'               
                useRememberMe: true                                 
            rememberMe:
                persistent: true

Note: If you have previously configured the application to connect to a SMTP server, you need to remove grails: from the above section. So the section will start with plugin: instead.

Configuration Options

Here is a description of some configuration options used for LDAP/AD integration:

  • managerDn/managerPassword: manager credential to access to LDAP server.

  • server: URL of the LDAP server.

  • groupSearchBase: the base directory to start the group search. Note: if we don't want to retrieve groups (roles) from LDAP, set retrieveGroupRoles to false.

  • groupSearchFilter: the pattern to be used for the user search. {0} is the user’s DN.

  • groupRoleAttribute: the ID of the attribute which contains the role name for a group.

  • clean.prefix: an optional string prefix to strip from the beginning of LDAP group names. For example, 'CCPD_' will convert CCPD_ADMIN to ROLE_ADMIN

  • base: the base directory to start the search.

  • filter: the filter expression used in the user search. For LDAP, uid field is typically used as username for the filter. In Active Directory, sAMAccountName (also called "User logon name") is typically used.

  • passwordAttributeName: the name of the password attribute to use.

LDAP/AD Requirements

The email address is a required field, make sure that LDAP/AD user email field is set properly.

The entire group name needs to be in uppercase in LDAP/AD.

If some users were previously created in CCPD before the LDAP integration, make sure the username matches with the one in LDAP (uid) or AD (sAMAccountName, also called "User logon name").

The api user needs to be created in LDAP/AD in order to generate an authentication token to import Asset Report Format (ARF) results from CIS-CAT Assessor.

Once LDAP/AD authentication is integrated to CCPD, the database authentication will be automatically disabled.

CIS-CAT Pro Assessor Integration

Introduction

The CIS-CAT Pro Dashboard has the ability to automatically import assessment results from CIS-CAT Pro Assessor. There are a few possible methods to configure the integration of CIS-CAT Pro Assessor and CIS-CAT Pro Dashboard to enable the upload of assessment results to the CIS-CAT Pro Dashboard database. From CIS-CAT Pro Assessor v3 and v4, results reports can be uploaded from a single CIS-CAT assessment (using either the graphical user interface in v3 or command-line user interface in v3 or v4). Additionally, users scanning with the “centralized” method to assess multiple Windows or Unix/Linux targets in v3 or v4 can modify the supporting files to automatically upload the results to CIS-CAT Pro Dashboard.

In order for the CIS-CAT Pro Dashboard and CIS-CAT Pro Assessor to communicate and share assessment results, authentication/authorization must be configured. Once the CIS-CAT Pro Dashboard has been installed, follow the instructions to generate an Authentication Token that will be used to validate the authentication in supporting CIS-CAT Pro Assessor files.

In support of SCAP 1.2, CIS-CAT Pro Dashboard can generate assessment results in Asset Reporting Format (ARF). The ARF report supports assessed content created as SCAP 1.2 data-stream collection or XCCDF 1.2-based data streams. CIS Benchmark content is created as XCCDF 1.2-based data streams.

Establish authentication with Assessor

The setting for Authentication Token is a key piece of the integrations between CIS-CAT "Assessor" and CIS-CAT Pro Dashboard. Once a user has been configured in the CIS-CAT Pro Dashboard application to be assigned to the API Role (ROLE_API in the application), that user can generate an authentication token to be used in CIS-CAT. This token verifies the user's privileges in CIS-CAT Pro Dashboard when attempting to upload CIS-CAT results into the application's database.

Once the authentication token is generated in CIS-CAT Pro Dashboard, it MUST be copied into CIS-CAT Pro Assessor setting in order for the upload functionality to work.

NOTE: By default there is a user named apiuser which has ROLE_API. The default password for this user is @apiuser123. In order to generate the token correctly, you must:

  1. Login once as the apiuser and reset the temporary default password.
  2. Login as an administrator and navigate to the user management page for the apiuser.
  3. Generate the token using the new password you assigned to the apiuser.

Assessor Centralized deployment Dashboard Integration

CIS-CAT Pro Dashboard-specific scripts have been developed to allow for reports to be generated in the correct format and uploaded to the CIS-CAT Pro Dashboard database.

Assessor V4:

Microsoft Windows Environments: cis-cat-centralized-ccpd.bat

To use cis-cat-centralized-ccpd.bat script, please follow Assessing Multiple Windows Targets from Assessor V4 Configuration guide.

Unix/Linux Environments: cis-cat-centralized-ccpd.sh

To use cis-cat-centralized-ccpd.sh script, please follow Assessing Multiple Unix/Linux Targets from Assessor V4 Configuration guide.

Assessor V3:

Microsoft Windows Environments: cis-cat-centralized-ccpd.bat

The Windows batch script has been developed to allow users to quickly enter the information necessary to execute the standard CIS-CAT "centralized" workflow, and automatically transmit the results to CIS-CAT Pro Dashboard. The CIS-CAT User's Guide contains setup instructions for Windows environments under the "Assessing Multiple Windows Targets" section.

Create CIS Share on the CIS Hosting Server

The instructions in the CIS-CAT User's Guide should be followed, except for Step 5. When configuring uploads to the Dashboard, move the CIS\cis-cat-full\misc\cis-cat-centralized-ccpd.bat script to the root of the CIS folder.

Security Considerations

Ensure the "Execute" permission is granted to "Authenticated Users" on the CIS\cis-cat-centralized-ccpd.bat script.

Update cis-cat-centralized-ccpd.bat

The following information describes various configurable items contained inside the script, which must be set appropriately for CIS-CAT results to be uploaded to CIS-CAT Pro Dashboard. If you want to use the CIS-CAT.bat/sh file you can set many of these properties in the misc/ciscat.properties file.

Line 27:

SET DEBUG=0

This option enables (1) or disables (0) debugging during the execution of this script.

Line 36:

SET AUTODETECT=1

This option enables (1) or disables (0) automatic detection of the user's operating system, as well as the appropriate selection of benchmark for assessment.

Line 45:

SET SSLF=0

This option enables (1) or disables (0) the execution of the "higher security" profile of the selected benchmark. Typically, the disabled setting will select the "Level 1" profile for assessment, and the enabled setting will select the "Level 2" profile, if available for the selected benchmark.

Line 51:

SET NetworkShare=\\\[NETWORK_SHARE]\CIS

The NetworkShare setting configures the UNC path to the folder containing the script to be executed. This value should be configured to the UNC path of the folder which contains the "cis-cat-full" CIS-CAT installation folder. Consider the following screen shot:

When shared on a user's network, the folder to be shared is the "CIS-CAT-AUTODETECT" folder. Assume the folder is shared as \CIS-CAT-SERVER\CIS-CAT-AUTODETECT. This would become the value of the NetworkShare variable in the cis-cat-centralized-ccpd.bat script:

SET NetworkShare=\\CIS-CAT-SERVER\CIS-CAT-AUTODETECT

Line 65:

SET JavaPath=Java\jre

This setting determines the path, relative to the path indicated by the NetworkShare, to a 32-bit Java Runtime Environment to be used to execute CIS-CAT.

Line 71:

SET JavaPath64=Java64\jre

This setting determines the path, relative to the path indicated by the NetworkShare, to a 64-bit Java Runtime Environment to be used to execute CIS-CAT. Technically, this path can also be configured to reference a 32-bit JRE as well, and could be configured to the same value as line 65 above, if only a 32-bit JRE is used.

Line 77:

SET JavaMaxMemoryMB=768

This setting indicates the maximum heap size, in megabytes, to be allocated by the JRE during CIS-CAT execution.

Line 83:

SET CisCatPath=cis-cat-full

This setting indicates the path, relative to the path indicated by the NetworkShare, to the folder containing the CIS-CAT application (the CISCAT.jar file)

Line 92:

SET CCPDUrl=http://\[YOUR-SERVER\]/CCPD/api/reports/upload

This setting indicates the web application's resource URL, based on the member's installation of the CIS-CAT Pro Dashboard application. The value of [YOUR-SERVER] should be configured to the location of the web/application server (including any port values, if needed) on which CIS-CAT Pro Dashboard is installed. Because the report upload process is "resource-oriented", the /api/reports/upload path MUST be part of the CCPDUrl value, otherwise CIS-CAT will not invoke the appropriate CIS-CAT Pro Dashboardresource, for example:

SET CCPDUrl=http://ccpd.example.org/CCPD/api/reports/upload

Line 102:

SET CISCAT_OPTS=-arf -ui –n

This setting configures the reporting options for CIS-CAT's interactions with the Dashboard. This value SHOULD remain fixed as –arf –ui –n. These options configure the following:

Option Description
-arf This option indicates that CIS-CAT generates the Asset Reporting Format (ARF) report. This is the standardized reporting format which is accepted by CIS-CAT Pro Dashboard and imported into the application's database.
-ui This (optional) command-line option indicates that CIS-CAT should ignore any SSL certificate warnings/errors when uploading the generated ARF report.
-n This option explicitly disables the creation of the CIS-CAT HTML report. Only the ARF results can be automatically uploaded to CIS-CAT Pro Dashboard, so the HTML report must be disabled from being generated.

Line 107:

SET AUTHENTICATION_TOKEN=[Generate_An_Authentication_Token_In_CCPD]

Please follow the instructions from Establish authentication with Assessor section in order to generate a token.

Line 118:

SET Benchmark=CIS_Microsoft_Windows_Server_2003_Benchmark_v3.1.0-xccdf.xml

This setting configures a specific benchmark for evaluation. This setting only applies if the AUTODETECT setting from line 36 is disabled (0).

Line 129:

SET Profiles=xccdf_org.cisecurity.benchmarks_profile_Level_1_Domain_Controller xccdf_org.cisecurity.benchmarks_profile_Level_1_Member_Server

This setting configures the specific profiles for evaluation. This setting only applies if the AUTODETECT setting from line 36 is disabled (0).

Validate the Install

To test the setup, log into one of the target systems as a user capable of executing commands from an elevated command prompt, such as a domain admin. Execute the following command from an elevated command prompt:

Note that the "CIS-CAT-SERVER" value should be substituted with the actual name or IP of the machine configured as the [NETWORK_SHARE] on line 51 of the script, above. If successful, the above command will detect the operating system, select the appropriate benchmark and profile, execute the CIS-CAT assessment, and transmit the generated reports to CIS-CAT Pro Dashboard:

Because the import process to CIS-CAT Pro Dashboard must validate the uploaded report and process it into the application database, reports may not be visible through the CIS-CAT Pro Dashboard application for a few minutes.

Configuring the Scheduled Task via Group Policy

The scheduled task configuration information can be followed from the CIS-CAT User's Guide. The only difference arises in Step 7, when entering information into the Actions tab of the task configuration. Instead of executing the cis-cat-centralized.bat script, configure the task to execute the cis-cat-centralized-ccpd.bat script.

Unix/Linux Environments: cis-cat-centralized-ccpd.sh

Implementing the CIS-CAT Pro Dashboard workflow in a "centralized" Unix/Linux environment only requires that the CIS-CAT Pro Dashboard application URL be provided in the bundled cis-cat-centralized-ccpd.sh script. The CIS-CAT Pro Dashboard-specific script looks very similar to the standard cis-cat-centralized.sh script, except for line 89, which configures the URL of the CIS-CAT Pro Dashboard application resource:

#
# The URL for the CIS-CAT Pro Dashboard API to which CIS-CAT reports are POST'ed
# The resource for CIS-CAT Pro Dashboard upload is ALWAYS mapped to the /api/reports/upload location,
# so the path to the application is all that should be modified here,
# for example: http://applications.example.org/CCPD/api/reports/upload
#
CCPD_URL=http://[YOUR-SERVER]/CCPD/api/reports/upload

Similar to the configuration for Windows above, the CCPD_URL value must end with the /api/reports/upload pattern to correctly identify the resource handling CIS-CAT uploads:

CCPD_URL=http://applications.example.org/CCPD/api/reports/upload

All other configuration items in this script should be pre-configured out of the box. Once this script is saved and closed, the installation can be tested.

Validate the Install

In order to test the proper installation of the cis-cat-centralized-ccpd.sh script, log into one of the target systems in the environment as either a root user or a user capable of executing commands using sudo. Execute the following command, where /path/to/cis represents a file system path to the CIS Host Server:

> /path/to/cis/cis-cat-centralized-ccpd.sh

If configured correctly, the standard CIS-CAT assessment output will be displayed to the user, and a successful CIS-CAT Pro Dashboard upload message will be displayed at the conclusion of the assessment.

CIS-CAT Pro Assessor v4 Service Integration

CIS-CAT Pro Assessor v4 Service is a separate application that is available only to CIS SecureSuite members from the Download section of CIS WorkBench. CIS-CAT Pro Assessor v4 Service is designed to interact with the CIS-CAT Pro Dashboard v1.1.11+ to allow configuration assessments to be run from CIS-CAT Pro Dashboard against a specified target system. For installation instructions, please see the CIS-CAT Pro Assessor v4 documentation. Details on how to integrate a configured version CIS-CAT Pro Assessor v4 Service with CIS-CAT Pro Dashboard are provided below.

Enable Assessor v4 Service Features

Pre-Requisites:

  • CIS-CAT Pro v4 Service deployed. See the guide.
  • CIS-CAT Pro Dashboard v1.1.11+ installed

  1. Note location of Assessor v4 Service deployment
    • Separate host system
    • CIS-CAT Pro Dashboard's Tomcat host
  2. Configure CIS-CAT Pro Dashboard ccpd-yml file
    • Ensure spacing and tabbing matches the examples very closely as yml files are particular with information "lining up"
    • For Assessor v4 Service deployments on Tomcat host, avoid local port conflict by setting the assessor service to an open port
  3. Modify ccpd-config.yml in one of the examples based on current installation configuration

    • HTTP communication: when setting URL, use the port set in Assessor v4 Service server.conf file (http://localhost:2222)
    • HTTPS communication: set URL as set in Assessor v4 Service server.conf file (https://your_url)

    Installations configured with SMTP or LDAP:

    Installations without SMTP or LDAP configurations:

  4. Restart Tomcat

  5. Ensure assessor-service.properties in Assessor v4 Service has been configured
Property Description
active hides(false) or displays(true) features for orchestrating an assessment
url Mandatory value when active:true representing URL of the Assessor v4 Service web server.
ignoreSslCertErrors ignores(true) or allows(false) certificate errors

CIS WorkBench Integration

Introduction

This new feature is an optional service provided to members to receive automatic notifications on new CIS-CAT Pro releases.

Setting up the connection is an admin only ability. Additionally, the application requires a direct internet connection, a proxy will not work.

When the connection is active, inbox alerts will appear within CIS-CAT Pro Dashboard when a new CIS-CAT Pro release is available.

Retrieve the new release using links in the alert message from within CIS-CAT Pro Dashboard without logging directly into CIS WorkBench.

CIS utilizes OAuth 2.0 authorization framework to establish a connection between the two applications.

A one-way API is established from an instance of CIS-CAT Pro Dashboard to CIS WorkBench.

Each connection or integration is unique per Dashboard installation, which allows organizations with multiple instances of Dashboard to establish a communication between CIS-CAT Pro Dashboard and CIS WorkBench.

CIS-CAT Pro Dashboard will check CIS WorkBench daily for the availability of a new release of CIS-CAT Pro. Establishing this connection will not allow CIS to collect any assessment results from your organization.

Establish a connection with CIS WorkBench

Under the settings menu, an option called Systems Integrations is available to users with the admin role.

Select System Integrations menu item:

In System Integrations, select the Connect button:

Select Continue to CIS WorkBench:

Enter CIS WorkBench credentials and select Authorize:

Review the screen and Select Authorize:

Note: The switch button appears grayed out because "Downloads of new CIS-CAT Pro updates" is the only service offered so far. In the future, members will have the option to opt-in/out from multiple services.

The connection is successfully made:

Note: The switch button appeared grayed out because "Downloads of new CIS-CAT Pro updates" is the only service offered so far. In the future, members will have the option to opt-in/out from multiple services.

Test connection between CIS-CAT Pro Dashboard and CIS WorkBench

Test button is available to verify the connection between CIS-CAT Pro Dashboard and CIS WorkBench.

When a connection is active, test the connection by pressing Test button:

If successful, a message will show on the screen.

If not, instructions will be provided in an error message.

Disconnect from CIS WorkBench

Select Disconnect:

Select Disconnect again in the popup:

The disconnection is successfully made:

Now CIS-CAT Pro Dashboard and CIS WorkBench are disconnected.

Although your connection is no longer active between CIS-CAT Pro Dashboard and CIS WorkBench, an active API client exists on your organization’s profile on the CIS WorkBench. We keep this API client to allow you to reconnect easily.

However, if you no longer want to utilize the service, please contact CIS Support at support@cisecurity.org in order to delete the API client.

Dashboard API

Upload Report API

CIS-CAT Pro Dashboard utilizes an API to upload assessment reports (ARF,XML) generated by CIS-CAT Pro Assessor v3 and v4. The API utilizes a POST_URL feature. The API can also be called from a script (python, powershell etc...). The API definition can assist organizations, where necessary, in building their own, organization-approved scripts to upload reports into the Dashboard.

Description

  • Url: http(s)://[MY-DASHBOARD-SERVER]/CCPD/api/reports/upload
  • Method: POST
  • Header:
    'Authorization': 'Bearer=[MY_DASHBOARD_AUTHENTICATION_TOKEN]'
    Note: [MY_DASHBOARD_AUTHENTICATION_TOKEN] is the token generated from the Dashboard with the a user assigned with ROLE_API. For more details, please see Establish authentication with Assessor section.
    'Content-type': multipart/form-data
    Note: In the below example of the Python script, content-type is automatically generated. There is no need to specify it.
  • POST Data Params:
    'ciscat-report': String content of the XML report generated by the Assessor
    'report-name': A given name of the report. For example, the name can follow the Assessor naming convention as following: hostname_benchmark-timestamp-ARF.xml.
  • Responses code:
    200: Assessment report successfully uploaded
    400: Unexpected failure with details on response status message
    401: Assessment failed to upload because of an Authentication Failure. Please ensure your authentication token is correct.
    500: Assessment failed to upload with details on response status message

Example of Python script:

Below is a script to upload of a single report into the Dashboard:

Assuming Hostname_CIS_Microsoft_Windows_10_Enterprise_Release_1803_Benchmark-20190805T135433Z-ARF.xml is the name of the report file generated by CIS-CAT Pro Assessor and located in ./reports directory.
The generated token is eertaa2pg2h7vb3ms97kdjebakr22v15 and the Dashboard URL is https://mydashboard/CCPD/api/reports/upload

import sys
import json
import requests
import http
import datetime

print(str(datetime.datetime.today()) + " *********************** Start dashboard upload script ***********************")

apiHeaders = {'Authorization': 'Bearer=eertaa2pg2h7vb3ms97kdjebakr22v15'}

with open('./reports/Hostname_CIS_Microsoft_Windows_10_Enterprise_Release_1803_Benchmark-20190805T135433Z-ARF.xml', 'rb') as f:
    filecontent = f.read()
requests.post("https://mydashboard/CCPD/api/reports/upload", headers=apiHeaders,  data={'ciscat-report': filecontent ,'report-name':'Hostname_CIS_Microsoft_Windows_10_Enterprise_Release_1803_Benchmark-20190805T135433Z-ARF.xml'})

print(str(datetime.datetime.today()) + " *********************** End dashboard upload script ***********************")

Note: In order to troubleshoot authorization/upload issues, SSL certificate verification can be ignored using requests.post(...,verify=False)