Import Configuration Assessment Results from CIS-CAT Pro Assessor with API¶
Introduction¶
The CIS SecureSuite Platform allows you to import configuration assessment results generated from CIS-CAT Pro Assessor either manually or via a REST API.
This guide explains how to use the REST API to import your configuration assessment results into the CIS SecureSuite Platform:
Set Up Authentication for API Import¶
Authentication must be established with CIS-CAT Pro Assessor to enable automatic imports via API. Authentication is established with a generated authentication token from the CIS SecureSuite Platform.
1. Log in to the CIS SecureSuite Platform.
2. Go to My Profile.
3. Select Generate Token.
4. Copy the token.
5. Open the assessor-cli.properties file for the Assessor that will POST to the CIS SecureSuite Platform.
Info
This file is located in the config folder of CIS-CAT Pro Assessor.
6. Paste the token as the ciscat.post.parameter.ccpd.token property value.
ciscat.post.parameter.ccpd.token=m9i0o2lrqno60dlq49qlln6gqrj2l7kt
7. (Optional but recommended) Update the ciscat.zip.post.files property value to true to compress the reports imported to the CIS SecureSuite Platform.
ciscat.zip.post.files=true
8. Save the file.
The reports can now be sent as POST requests. Utilize this CIS-CAT Pro Assessor to import the reports to the CIS SecureSuite Platform via the GUI, CLI, or Centralized method (Windows or Linux).
Example Command to Import Configuration Assessment Results into the CIS SecureSuite Platform
Use the -u option to import the configuration assessment into the CIS SecureSuite Platform. Those using SecureSuit with a self-signed certificate must ignore SSL warnings with the -ui option.
-b benchmarks\CIS_Microsoft_Windows_10_Enterprise_Benchmark_v1.12.0-xccdf.xml -u https://123.4567.78.901/SecureSuite/api/reports/upload -ui
Be aware that "SecureSuite" must be capitalized exactly as shown in the example above; otherwise, you will encounter an error.
Ignore SSL Warnings¶
If you are utilizing a self-signed certificate for HTTPS configuration, SSL warnings must be ignored. Refer below for options to ignore SSL warnings.
- When running an assessment from the Assessor GUI, select the Ignore SSL Warnings checkbox.
- For CLI commands, utilize
-ui. Refer to Reporting Options in the CIS-CAT Pro Assessor Guide. - For centralized setups, refer to Centralized - Windows or Centralized - Linux for more information.
Use the API for Assessor Results Import¶
The API for importing assessor results utilizes POST_URL. You can call the API using a script (Python, PowerShell, etc.).
API Definition¶
The API definition can assist you in building scripts to automate importing assessment results to the CIS SecureSuite Platform.
URL¶
https://<host or server address>/SecureSuite/api/reports/upload
Example URLs
- https://123.456.78.901/SecureSuite/api/reports/upload
- https://myapp.example.org/SecureSuite/api/reports/upload
Method¶
POST
Headers¶
Header |
Description | Value |
Notes |
|---|---|---|---|
Authorization |
The authentication token, which allows POST requests to CIS-CAT Pro Dashboard or the CIS SecureSuite Platform. |
Bearer=<YOUR_DASHBOARD_AUTHENTICATION_TOKEN> |
|
Content-type |
The format of the uploaded reports. | multipart/form-data | Automatically generated, so no need to specify this header in API requests. |
POST Data Parameters¶
| Parameter | Description | Type |
|---|---|---|
ciscat-report |
The content of the XML report generated by the Assessor. | string |
report-name |
The given name of the report | string |
Response Codes¶
| Code | Description | Notes |
|---|---|---|
200 |
OK | Assessment report successfully uploaded. |
400 |
Bad Request | Unexpected failure with details on response status message. |
401 |
Unauthorized | Assessment failed to upload because of an Authentication Failure. Ensure authentication token is correct. |
500 |
Internal Server Error | Assessment failed to upload with details on response status message. |
Python Script Example¶
The script example was created under the following assumptions:
| Assumption | Value |
|---|---|
| Report Name | Hostname_CIS_Microsoft_Windows_Server_2022_Benchmark_v3.0.0.xml |
| Report Location | ./reports |
| Authentication Token | eertaa2pg2h7vb3ms97kdjebakr22v15 |
| CIS SecureSuite Platform URL | https://111.111.11.111/SecureSuite/api/reports/upload |
import sys
import json
import requests
import http
import datetime
print(str(datetime.datetime.today()) + " *********************** Start securesuite upload script ***********************")
apiHeaders = {'Authorization': 'Bearer=eertaa2pg2h7vb3ms97kdjebakr22v15'}
with open('./reports/Hostname_CIS_Microsoft_Windows_Server_2022_Benchmark_v3.0.0-xccdf.xml', 'rb') as f:
filecontent = f.read()
requests.post("https://111.111.11.111/SecureSuite/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 securesuite upload script ***********************")
Tip
To troubleshoot issues, SSL certificate verification can be ignored using requests.post(...,verify=False).