Installation Guide

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:

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
      "SourcePaths": [], // optional extra source paths to search and export scan
      "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.

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.

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

-SQLServer <String>
    The address of the SQL Server. The default value is localhost\SQLEXPRESS.
    
-SQLUsername <String>
    Username for the SQL Server. Set the username if required by your SQL Server.
    
-SQLPassword <String>
    Password for the SQL Server. Set the password if required by your SQL Server.
    
-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,
    OutBuffer, PipelineVariable, and OutVariable. For more information, see 
    about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). 

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".

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.