Set Up Configuration XML File¶

Introduction¶

A configuration XML file allows you to configure sessions, assessments, interactive values, user properties, and reporting options in one file. You can then run assessments based on the contents of the file in the GUI or CLI. The configuration XML file is the best option for those who want to run multiple assessments against multiple endpoints.

This guide covers:

Editing the configuration XML file
Using special characters in XML elements
The configuration root element
The sessions element
The assessments element
The reports element

Edit Configuration File¶

An XML schema (assessor-config.xsd) and sample configuration file (assessor-config-sample.xml) are included in the CIS-CAT Pro Assessor download.

1. Go to <path>\Assessor\config.
2. Open assessor-config-sample.xml or create and open a copy of it in a text editor.

Tip

You can generate a configuration XML file after setting up an assessment in the GUI.

3. Edit the file as necessary.
4. Save the file.

Using Special Characters in XML Elements¶

Some user-entered characters in the configuration file may need to be replaced with their numeric character reference equivalent to work properly.

For example, an ampersand (&) character used in a password for the credentials element should be replaced with the decimal character reference &.

Tip

View a full list of decimal character references here.

`configuration` Root Element¶

The root element of the configuration XML file is configuration, and utilizes a default namespace URI of http://cisecurity.org/ccpa/config. You must specify the namespace URI or else validation of the configuration XML file will fail.

The root of any XML configuration file should appear as follows:

<configuration xmlns="http://cisecurity.org/ccpa/config">

Note

All other elements must be contained within the configuration element.

`sessions` Element¶

The sessions element configures each individual session to assess local host or remote endpoints. Depending on the session type, the required elements differ.

<!-- Session configurations referenced by the assessments -->
<sessions test="(true|false)">

    <!-- A "connection" to the local host -->
    <session id="local">
        <type>local</type>
    </session>

    <!-- A connection to a remote Ubuntu instance using a private key file -->
    <session id="aws-ubuntu">
        <type>ssh</type>
        <host>11.22.33.44</host>
        <port>22</port>
        <user>ubuntu</user>
        <identity>C:\Path\To\aws-ubuntu.ppk</identity>
    </session>

    <!-- A connection to a remote CentOS instance using a private key file secured with a passphrase -->
    <session id="aws-centos">
        <type>ssh</type>
        <host>1.2.3.4</host>
        <port>22</port>
        <user>centos</user>
        <identity>C:\Path\To\aws-centos.ppk</identity>
        <identity_passphrase>P@55phr@s3!</identity_passphrase>
    </session>

    <!-- A connection to a remote Windows instance using credentials -->
    <session id="aws-2012r2">
        <type>windows</type>
        <host>AWS-WIN2012R2-AMI</host>
        <port>5986</port>
        <user>Administrator</user>
        <credentials>P@ssw0rd12345</credentials>
    </session>

    <!-- A connection to a Cisco IOS configuration file  -->
    <session id="cisco">
        <type>networktxt</type>
        <networkDeviceConfigFile>C:\example\networkdevice_config.txt</networkDeviceConfigFile>
    </session>
</sessions>

`test` attribute¶

Indicates whether the configuration file is meant to test the connectivity of each session.

Enter true to test for connectivity only and then exit the sessions.
```
<sessions test="true">
```

Local Sessions¶

For host-based assessments. Standalone or command-line applications (such as CIS-CAT Pro Assessor CLI) may use local sessions to conduct host-based assessments of Benchmarks and/or OVAL definitions.

Required Elements¶

Element	Description	Value
`id`	The unique identifier of the session. Each session must have one.	`example-assessment-local`
`type`	The type of connection to the endpoint to be assessed.	`local`

SSH Sessions¶

For connections to a remote Unix, Linux, or Apple OSX endpoint via SSH.

Required Elements¶

Element	Description	Value
`id`	The unique identifier of the session. Each session must have one.	`example-assessment-ssh`
`type`	The type of connection to the endpoint to be assessed.	`ssh`
`host`	Hostname or IP address (v4 or v6)	`linux.example.org` or `1.2.3.4`
`port`	The port number on which communication takes place.	`22` (default value)

SSH connections can be authenticated in numerous ways. Depending on the authentication method, use the relevant properties:

username + cred
username + identity
username + identity + identity_passphrase if private key file is encrypted
username + identity + cred for sudo privileges

Element	Description	Value
`user`	Username of the account used to log in to the remote endpoint	`root` or user with `sudo` privileges
`cred`	Password of the account used to log in to the remote endpoint	`examplepassword`
`identity`	The full filepath to a private key file to be used for authenticating the `user` to the remote endpoint.	`/home/example/privatekeyfile.ppk`
`identity_passphrase`	The credentials required to complete authentication if using an encrypted private key file	`exampleppkpassword`

Windows Sessions¶

For connections to a remote Microsoft Windows environment via WinRM.

Both workstations and servers are supported with this connection type and can currently be established using username/password authentication.

Required Elements¶

Element	Description	Value
`id`	The unique identifier of the session. Each session must have one.	`example-session-windows`
`type`	The type of connection to the endpoint to be assessed.	`windows`
`host`	The hostname or IP address (v4 or v6) of the endpoint to which this session will assess	`windows.example.org` or `1.2.3.4`
`port`	The port number on which communication takes place	HTTP: `5985` HTTPS:`5986`
`user`	Username of the account used to login in to the remote endpoint.	Administrator or member of the Administrators group
`cred`	Password of the account used to log in to the remote endpoint.	`examplepassword`

Network Device Sessions¶

For assessments of network devices (e.g., Cisco IOS, NX-OS, Palo Alto, etc.).

CIS-CAT Pro Assessor will create a local session, collecting information from an exported text or xml file.

Required Properties¶

Property	Description	Value
`id`	The unique identifier of the session. Each session must have one.	`example-session-nd`
`type`	The type of connection to the endpoint to be assessed.	`networktxt` or `networkxml`
`networkDeviceConfigFile`	The full filepath to the exported configuration text file. Used in conjunction with the `networktxt` session type.	`C:\example\networkdevice_config.txt`
`networkDeviceConfigXmlFile`	The full filepath to the exported configuration xml file. Used in conjunction with the `networkxml` session type.	`C:\example\networkdevice_config.xml`

Optional `tmp_path` Property¶

tmp_path designates a custom temporary directory location for creating the ephemeral directory on the target endpoint. You can use this property with any of the session types.

The ephemeral directory is named ccpa-temp-TIMESTAMP and is created as a sub-folder in the specified directory. For example, if tmp_path is specified as C:\Temp, the ephemeral directory will be created at C:\Temp\ccpa-temp-TIMESTAMP.

If you have entered a value for tmp_path, the directory must already exist on the target endpoint and have write privileges; otherwise, the assessment will exit.

If this property is left blank or excluded, the Assessor will use the default temp folder as defined for the operating system, such as /tmp or C:\Windows\Temp.

`assessments` Element¶

The assessments element configures which assessment content will be evaluated, against which session that content will be assessed, any user properties specific to that assessment, and any interactive values to be applied to that assessment.

<assessments quiet="(true|false)">
    <!-- XCCDF COLLECTIONS -->
    <benchmark xccdf="benchmarks\CIS_Ubuntu_Linux_16.04_LTS_Benchmark_v1.0.0-xccdf.xml" profile="Level 1 - Workstation" session-ref="aws-ubuntu"/>
    <benchmark xccdf="benchmarks\CIS_Ubuntu_Linux_16.04_LTS_Benchmark_v1.0.0-xccdf.xml" profile="Level 1 - Server" session-ref="aws-ubuntu"/>

    <benchmark xccdf="benchmarks\CIS_Microsoft_Windows_Server_2012_R2_Benchmark_v2.2.1-xccdf.xml" profile="Level 1 - Member Server" session-ref="aws-2012r2">
        <properties>
            <property name="ignore.platform.mismatch">true</property>
        </properties>
    </benchmark>

    <benchmark xccdf="benchmarks\CIS_Oracle_Database_11g_R2_Benchmark_v2.2.0-xccdf.xml" profile="Level 1" session-ref="aws-ubuntu">
        <interactive_values>
            <value id="xccdf_org.cisecurity_value_jdbc.url">jdbc:oracle:thin:sys/passw0rd1@DB-SERVER:1521:ORCL</value>
            <value id="xccdf_org.cisecurity_value_listener.ora">/opt/oracle/product/oracle11g/network/admin/listener.ora</value>
        </interactive_values>
    </benchmark>

    <!-- DATA-STREAM COLLECTIONS -->
    <data-stream-collection collection="collections\CIS_Microsoft_Windows_Server_2012_R2_Benchmark_v2.2.1-collection-xccdf.xml" 
    data-stream="scap_org.cisecurity_datastream_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark" checklist="scap_org.cisecurity_cref_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark-xccdf" profile="xccdf_org.cisecurity.benchmarks_profile_Level_1_-_Domain_Controller" 
    session-ref="local"/>

</assessments>

`quiet` attribute¶

Denotes whether assessment status information is displayed or not.

Enter true to display assessment status information.
```
<assessments quiet="true">
```

XCCDF Collections¶

Elements	Description	Value
`xccdf`	The path (relative to the `starting_dir` or absolute) to the XCCDF file being assessed.	benchmarks\CIS_Oracle_Database_11g_R2_Benchmark_v2.2.0.xml
`profile`	The configuration profile, within the XCCDF, selected for assessment. The value of this attribute may be either the profile `<title>` or `id` specified in the Benchmark XCCDF. If a value is not entered, the first profile in the checklist will be selected.	Level 1 - Member Server
`session-ref`	The `id` of the session from the `sessions` element configuration	local-assessment
`properties`	A container for individual `property` elements, which can be used to override user properties defined in the assessor-cli.properties file. A `properties` element must contain at least one `property` element.
`property`	Defines a name/value pair, configuring a single user property named by the value of the `name` attribute. The `property` value is the content of the element. An individual `property` is the equivalent of using the `-D name=value` command-line option or a property defined in the assessor-cli.properties file.	`<property name="ignore.platform.mismatch">true</property>`
`interactive_values`	A container for individual `value` elements, which can be used to configure interactive values, such as JDBC connection strings. An `interactive_values` element must contain at least one `value` element.
`value`	Defines an id/value pair, configuring a single interactive value identified by the `id` attribute. The `id` attribute must match the `id` of a `<value>` element in the XCCDF noted as `interactive="true"`. The `property` value is the content of the element. An individual `property` is the equivalent of using the `-D name=value` command-line option or a property defined in the assessor-cli.properties file.	`<value id="xccdf_org.cisecurity_value_listener.ora">/opt/oracle/product/oracle11g/network/admin/listener.ora</value>`

Data-Stream Collections¶

Elements	Description	Value
`collection`	The path (relative to the `starting_dir` or absolute) to the SCAP 1.2 data-stream collection file being assessed.	`collections\CIS_Microsoft_Windows_Server_2012_R2_Benchmark_v2.2.1-collection.xml`
`data-stream`	The data-stream's ID in the collection. If not present, the first data-stream in the collection will be selected.	`scap_org.cisecurity_datastream_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark`
`checklist`	The checklist's ID in the data-stream. A checklist is a component in the data-stream collection representing an XCCDF `<Benchmark>`. If not present, the first checklist in the data-stream will be selected.	`scap_org.cisecurity_cref_1.0.0_CIS_Microsoft_Windows_Server_2016_Benchmark-xccdf`
`profile`	The configuration profile, within the XCCDF, selected for assessment. The value of this attribute may be either the profile `<title>` or `id` specified in the Benchmark XCCDF. If a value is not entered, the first profile in the checklist will be selected.	`Level 1 - Member Server`
`session-ref`	The `id` of the session from the `sessions` element configuration.	`local-assessment`
`properties`	A container for individual `property` elements. A `properties` element must contain at least one `property` element.
`property`	Defines a name/value pair, configuring a single user property named by the value of the `name` attribute. The `property` value is the content of the element. An individual `property` is the equivalent of using the `-D name=value` command-line option or a property defined in the assessor-cli.properties file.
`interactive_values`	A container for individual `value` elements. An `interactive_values` element must contain at least one `value` element.
`value`	Defines an id/value pair, configuring a single interactive value identified by the `id` attribute. The `id` attribute must match the `id` of a `<value>` element in the XCCDF noted as `interactive="true"`. The `property` value is the content of the element. An individual `property` is the equivalent of using the `-D name=value` command-line option or a property defined in the assessor-cli.properties file.

Additional Examples¶

Assess an XCCDF <Benchmark>, selecting the first profile:

<benchmark xccdf="benchmarks\CIS_Ubuntu_Linux_16.04_LTS_Benchmark_v1.0.0-xccdf.xml" session-ref="aws-ubuntu"/>

Assess an XCCDF <Benchmark>, selecting a named profile:

<benchmark xccdf="benchmarks\CIS_Ubuntu_Linux_16.04_LTS_Benchmark_v1.0.0-xccdf.xml" profile="Level 1 Workstation" session-ref="aws-ubuntu"/>

Assess an XCCDF <Benchmark>, selecting a named profile and configuring specific assessment properties:

<benchmark xccdf="benchmarks\CIS_Microsoft_Windows_Server_2012_R2_Benchmark_v2.2.1-xccdf.xml" profile="Level 1 Member Server" session-ref="aws-2012r2">
    <properties>
        <property name="ignore.platform.mismatch">true</property>
    </properties>
</benchmark>

Assess an XCCDF <Benchmark>, selecting a named profile, configuring specific values normally requested from the user:

<benchmark xccdf="benchmarks\CIS_Oracle_Database_11g_R2_Benchmark_v2.2.0-xccdf.xml" profile="Level 1" session-ref="aws-ubuntu">
    <interactive_values>
        <value id="xccdf_org.cisecurity_value_jdbc.url">jdbc:oracle:thin:sys/passw0rd1@DB-SERVER:1521:ORCL</value>
        <value id="xccdf_org.cisecurity_value_listener.ora">/opt/oracle/product/oracle11g/network/admin/listener.ora</value>
    </interactive_values>
</benchmark>

Assess a SCAP <data-stream-collection>, selecting the first data stream, checklist, and profile:

<data-stream-collection collection="collections\collection.xml" session-ref="local"/>

Assess a SCAP <data-stream-collection>, selecting a named data stream, the first checklist, and first profile:

<data-stream-collection collection="collections\collection.xml" data-stream="ds-id" checklist="benchmark-id" profile="profile-id-or-name" session-ref="local"/>

Assess a SCAP <data-stream-collection>, selecting a named data-stream, a named checklist, and the first profile:

<data-stream-collection collection="collections\collection.xml" data-stream="ds-id" checklist="benchmark-id" profile="profile-id-or-name" session-ref="local"/>

Assess a SCAP <data-stream-collection>, selecting a named data stream, a named checklist, and a named profile:

<data-stream-collection collection="collections\collection.xml" data-stream="ds-id" checklist="benchmark-id" profile="profile-id-or-name" session-ref="local"/>

`reports` Element¶

The reports element contains a number of attributes controlling the output report formats, and sub-elements controlling report output directory, POST URL, and report naming.

<reports html="(true|false)" csv="(true|false)" txt="(true|false)" no-arf="(true|false)" no-report-file="(true|false)">

    <!-- Customize the folder to which CIS-CAT reports are saved.  If not present, CIS-CAT will use the default reports location. -->
    <reports_dir>C:\Projects\CIS\reports</reports_dir>

    <!-- POST the Asset Reporting Format or OVAL Results XML to a URL, ignoring SSL certificate warnings if specified -->
    <reports_url ignore_certificate_warnings="true">https://example.cisecurity.org/securesuite/api/reports/upload</reports_url>

    <!-- Override the default report name.  Timestamp information will always be appended to the report_prefix -->
    <reports_prefix>CIS-CAT-DEV</reports_prefix>
</reports>

Attributes¶

|Attribute|Description|

Value

| |---|---|---| |html|Controls the generation of the HTML report.|true/false| |csv|Controls the generation of CSV reports|true/false| |txt|Controls the generation of plain-text reports|true/false| |no-arf|When true, disables the generation of the Asset Reporting Format XML results. |true/false| |no-report-file|When true, overrides the html, csv, and txt attributes and disables the generation of any report files.

This attribute is useful when used in conjunction with the reports_url element, which identifies a URL to POST the reports. In this case, you might not want to save reports as they will be uploaded to the URL.|true/false| |ignore_certificate_warnings|When true, ignores SSL certificate warnings. This attribute is the equivalent to the -ui command-line option.|true/false|

Elements¶

Element	Description	Value
`reports_dir`	The directory to which reports are saved. This element is optional and equivalent to the `-rd` command-line option	`<reports_dir>C:\Projects\CIS\reports</reports_dir>`
`reports_url`	The URL to which the Assessor POSTs results. This element is optional and the equivalent to the `-u` command-line option.
`reports_prefix`	Defines the prefix added to the automatically generated report names. When reports are generated, the name of the report is created by concatenating the reports prefix, the report type (such as ARF or OVALResults) and the timestamp of report generation. If this element is not present, the default reports prefix is the assessment target's hostname plus the benchmark's title, such as CIS-CAT-DEV-CIS_Microsoft_Windows_10_Enterprise_Release_1703_Benchmark.	`<reports_prefix>CIS-CAT-DEV</reports_prefix>`

Set Up Configuration XML File¶

Introduction¶

Edit Configuration File¶

Using Special Characters in XML Elements¶

configuration Root Element¶

sessions Element¶

test attribute¶

Local Sessions¶

Required Elements¶

SSH Sessions¶

Required Elements¶

Windows Sessions¶

Required Elements¶

Network Device Sessions¶

Required Properties¶

Optional tmp_path Property¶

assessments Element¶

quiet attribute¶

XCCDF Collections¶

Data-Stream Collections¶

Additional Examples¶

reports Element¶

Attributes¶

Elements¶

`configuration` Root Element¶

`sessions` Element¶

`test` attribute¶

Optional `tmp_path` Property¶

`assessments` Element¶

`quiet` attribute¶

`reports` Element¶