# Installation Guide

CxArchive is the SAST archiving service that allows customers to export data from their CxSAST database reducing the load on the database. For further information and instructions on installing CxArchive, refer to the instructions below.

## Prerequisites

CxArchive installs as a Windows service and requires the following pre-requisites:

• The host with CxArchive installed must have connectivity to the CxSAST database host.

• The service is compatible with versions greater than 9.2.

• Elasticsearch must be installed and connectivity to the CxArchive host must be guaranteed at all times.

## As a Windows Service

Follow the instructions below to install CxArchive:

1. Create a folder called CxArchive on your local host.

2. Download the CxArchive zip archive and extract its content into the newly created CxArchive folder on your local host.

3. Move the CxArchive folder with its content into the C:\Program Files\Checkmarx folder. The path is going to be C:\Program Files\Checkmarx\CxArchive.

4. Create a folder where to host the exported scan source code folders. This folder can be a local folder on the CxArchive host or a network folder. In this example, the folder name and path is “C:\CxSrcArch

5. Run the SQL setup script (cxarchive-setup.sql) in the extracted CxArchive setup folder from the archive in the CxSAST database that you wish to export.

6. Define the feature flags defined in the environment variables listed below according to your own environment.

### Configuring the Feature Flags

After running the SQL setup script, the following set of feature flags/configuration values for the CxArchive system in your SAST database table CxComponentConfiguration becomes available:

• SAST_ENVIRONMENT_ID - an auto generated guid that identifies your SAST system

• CXARCHIVE_IS_ENABLE - defines if the CxArchive system is active or not

• CXARCHIVE_SOURCES_FOLDER - the path where you want your exported scans source code folders

• CXARCHIVE_SOURCES_ENABLE - a boolean flag that defines if the source code folder of the exported scans is going to be exported or not

### Danger

Do not modify the SAST_ENVIRONMENT_ID configuration value. Modifying this value may cause data inconsistency problems.

### Notice

Under CXARCHIVE_SOURCES_FOLDER, enter the path that you created in step 4. In the example used, it was “C:\CxSrcArch“.

### Warning

If some source code folders are missing in the system and the flag CXARCHIVE_SOURCES_ENABLE is enabled (true), the corresponding scans export will fail.

### Configuring the CxArchive Settings

After configuring the CxArchive feature flags, you have to configure the settings in appsettings.json. The appsettings file contains the connections to the SAST database, the Elasticsearch connection and the export criteria that define the scans that are going to be exported from your SAST system. The file has the following structure:

{
"Database": {
"CxDBClient": {
"ConnectionString": "Data Source= ;Initial Catalog=CxDB;Integrated Security=False;User ID= ;Password= ;Pooling=True;", // ConnectionString for the CxSAST DB instance to export
"EncryptionKey": "",
"EncryptionVector": ""
},
"ElasticSearch": {
"Host": "http://localhost:9200", // Elasticsearch data lake machine 'http(s)://<url>:<port>'
"IndexName": "scans_92", // Elasticsearch index where your scan documents will be stored
"AuthType": "None", // None, Basic or "ApiKey"
"Identifier": "", // username in basic or id in apikey
"Key": "" // Password in basic authentication or key in apiKey. For base64key only use Key field and leave Identifier empty.
},
"ExportToLogStash": { // Allows to export to a specified disk folder instead directly to Elastic Search
"Enabled": false, // Enable the feature, replacing the Elastic Search export
"PathToExport": "", // Folder to export files
"Host": "", // Logstash Http URL 'http(s)://<url>:<port>'
"AuthType": "None", //Basic or None
"Identifier": "", // Username used in basic authentication
"Key": "" // Password used in basic authentication
}
},
"ExportSettings": {
"NumberOfRetries": 3, // number of retries for the export of a scan in case of failure
"NumberOfResultsPerDocument": 5, // number of PathResults in each denormalized scan document
"NumberOfScansToProcessInParallel": 4, // number of scans exported in parallel to the data lake
"MaxBatchSize": 10000, // number of scans processed in each CxArchive export iteration
"ExportIntervalInMinutes": 60, // interval in minutes between the finish time of an export execution and the next one
"TimeOutPerScan": -1, //Max TimeOut in seconds for each scan export. If one scan takes more than the timeout it will fail and release the system resources to another scan.
"ExportCriteria": { // defines the criteria conditions to export
"Type": "Scans", // defines the comparison entity by which we filter SelectedIds. Possible values are 'Scans' or 'Projects'
"SelectedIds": [], // specific ids to export. if empty list all scans between mentioned date in ScansAgeRange will be exported
"ExcludeZeroResultsScans": false, // defines if scans with zero results are included or not on exporting process
"ScansAgeRange": { // determine the age range window of scans to archive. set values as empty string or remove field if no filter is required
"MinScanAgeInDays": 1,
"MaxScanAgeInDays": 100
},
"ExportPresetInfo": false, // Determine if the preset of each task scan should be exported as well
"ExportZeroResultsQueries": true // Determine if the queries with zero results should be exported on Path Results section
}
}
}

For details about the validation rules required for the system to operate, see AppSettings customization.

## Limitations and Recommendations

For details about the limitations and recommendations, see here.

## Using the WinService Installation Script

The manual installation of CxArchive as a WinService, is described above. This section describes how to use the WinService Installation Script: cx-archive-installer.ps1

### Prerequisites

In addition to the prerequisites described here, the connection string of appsettings.json (Database.CxDBClient.ConnectionString), must match the SQL connection parameters given to this script.

Given the artifact, extract it and open a PowerShell session on the Setup directory.

### Notice

The script can be called from anywhere, but it is assumed here that your current working directory is the Setup directory of the extracted CxArchive artifact.

### Syntax

.\cx-archive-installer.ps1
[[-SQLServer] <String>]
[[-InstallationPath] <DirectoryInfo>]
[-EnableCxArchiveSources]
[[-ExportDirectoryPath] <DirectoryInfo>]
[[-ServiceLogonUser] <String>]
[<CommonParameters>]

### Parameters

-SQLServer <String>
The address of the SQL Server. The default value is localhost\SQLEXPRESS.

-InstallationPath <DirectoryInfo>
Path to the CxArchive installation directory. The default value is 'C:\Checkmarx'.

-EnableCxArchiveSources [<SwitchParameter>]
Flag for whether CxArchive will archive sources or not. The default value is False.

-ExportDirectoryPath <DirectoryInfo>
Path to the archived scans source code directory. Requires '-EnableCxArchiveSources'.
The default value is 'C:\CxSrcArch'.

-ServiceLogonUser <String>
CxArchive Windows Service logon target.
If ommitted, the logon user for the running Checkmarx services,
on the current host, will be used by default.

<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). 

### Examples

#### Quickstart

To install CxArchive in the host where you have your CxSAST AIO installation, using the default parameters, run the following command:

PS> cx-archive-installer.ps1

#### With a remote SQL server

If your SQL server is on a different host, include the following parameters to connect to it:

PS> cx-archive-installer.ps1 -SQLServer somewhere-else\SQLEXPRESS -SQLUsername MyUser -SQLPassword MyPassword

#### Custom installation path

To have a customized CxArchive installation path, point to the custom path, using the following command:

PS> cx-archive-installer.ps1 -InstallationPath C:\Somewhere\Else\Checkmarx

#### Enable exports of the scanned source code

To enable exporting scanned source code:

PS> cx-archive-installer.ps1 -EnableCxArchiveSources

To choose a different directory for its destination:

PS> cx-archive-installer.ps1 -EnableCxArchiveSources -ExportDirectoryPath C:\Somewhere\Else\Sources

#### Custom logon user for the Windows service

If CxSAST isn't running on the same host, specify the logon user for the Windows service, using the following command:

PS> cx-archive-installer.ps1 -ServiceLogonUser DOMAIN\username

#### Verbose flag

PS> cx-archive-installer.ps1 -Verbose

If you want to copy the logs to the clipboard, for example, to report an issue, you can simply pipe it to clip and Ctrl-V in any text area:

PS> cx-archive-installer.ps1 -Verbose | clip

### Remarks

To see the examples, type: "get-help cx-archive-installer.ps1 -examples".

For more information, type: "get-help cx-archive-installer.ps1 -detailed".

For technical information, type: "get-help cx-archive-installer.ps1 -full".

### Limitations

If the ExportDirectoryPath parameter is pointing to a remote directory, the installer won't be able to configure the proper permissions. A warning will be issued, with instructions on how to configure it manually.