Client Installation
CxSAST Reporting Windows Prerequisites
This page describes the list of prerequisites for the windows installation of the Cx Reporting Service components.
Authorization and Authentication
Notice
The Authorization Setup Script must be executed prior to the Client API Installation. The script and guide can be found in CxSAST Reporting Authorization Setup.
.NET Core Hosting Bundle
The CxSAST Reporting Service needs the following version of .net hosting bundle, depending of the version to be installed:
Version 1.x: ASP.NET Core 3.1.21 hosting bundle (download link) must be installed in the CxSASTReporting Service machine, which might require a restart.
Version from 2.x: ASP.NET Core 6.0.7 hosting bundle (download link) must be installed in the CxReportingService service machine, which might require a restart.
Both the service and client machines must have connectivity to the CxSAST’s database host and CxSAST’s manager host for Access Control connectivity.
IIS Deployment
The CxSAST Reporting Service Client API and CxSAST Reporting Wizard need to be deployed on a web server like IIS, so to be done, firstly IIS Server needs to be installed and running on the server.
To install the IIS server you need first to activate it on control panel, like explained on the following article: Enable IIS.
CxSAST Reporting Authorization Setup
This article describes how to install the CxReportingService authorization setup. The script must be executed prior to the Client API installation.
Authorization and Authentication
The CxReportingService client REST API integrates authentication and authorization with Checkmarx SAST Access Control. For that:
A new scope for the CxReportingService is created, named reporting_api
New permissions are created:
generate-project-report (for project template generation)
generate-team-report (for teams templates generation)
generate-application-report (for application template generation)
generate-executive-report (for executive template generation)
Available only in the authorization script from version 1.5.0
create-report-template (for new report templates creation)
Available only in the authorization script from version 2.0
update-report-template (for templates customization)
Available only in the authorization script from version 2.0
delete-report-template (for templates deletion)
Available only in the authorization script from version 2.0
edit-report (for configurations customization before generating a report)
Available only in the authorization script from version 2.0
create-template-schedule (for new report schedules creation)
Available only in the authorization script from version 3.0
edit-template-schedule (for schedule editing)
Available only in the authorization script from version 3.0
change-status-schedule (to change the state of schedule)
Available only in the authorization script from version 3.0
delete-template-schedule (to delete scheduled events)
Available only in the authorization script from version 3.0
Permissions available under Reports Category
No roles having the new permissions are created. Roles must be created and/or edited manually, in Access Control, to include the new permission.
As Swagger acts as a client of the CxReportiveService, a new client was created to authenticate through Swagger, named reporting_service_swagger.
From versions from 1.0.0 to 1.4.0, an implicit flow was implemented in the Swagger authentication.
In version 1.5.0, the authentication method was changed from implicit to PKCE to the swagger client.
Authorization Setup Script
For Versions from 1.0.0 to 1.4.0
A PowerShell script to setup the Access Control configuration, that includes the scope, the client and the permissions has been developed.
Execute the script in the CxSAST Manager host, after first stopping the SystemManager service. This will avoid conflicts in the filesystem access and apply the changes to the system when started.
The script can be found under the CxReportingClientFolder (CxReportingClient-XXXX.zip\CxReportingClient\cx-reporting-auth-setup.ps1)
Warning
The script must be executed in a PowerShell console in Administrator mode.
Script Parameters and Execution
The script has the following parameters:
Verbose
Required - To get details about the applied installation steps.Port
Default: 5555 - To configure of the IIS port where the CxReportingService Client API will be deployed.PortalPort
Default: 3000 - To configure of the IIS port where the CxReportingService Portal will be deployed.InstallationPath
Default: C:\Program Files\Checkmarx - To configure the CxSAST base installation folder.BaseAddress
Default: http://localhost - To configure the CxReportingService Client API Host IP or Name.
Examples
Default installation, using the default values:
.\cx-reporting-auth-setup.ps1 -Verbose
For an installation with custom values:
.\cx-reporting-auth-setup.ps1 -Verbose -Port 5555 -BaseAddress http://10.32.123.12 -InstallationPath "D:\Installations\Checkmarx"
System Requirements Starting with Version 1.5.0
Notice
Execute this script on all machines where SAST is installed.
If you have a High Availability environment you must run it on all machines where SAST is installed.
SqlCmd: This script executes a set of queries in the SAST database and uses the SqlCmd Utility to execute them. To execute this script, you must have SQL Server Management tools or SqlCmd Utility installed on your machine.
Warning
If your are getting the error: sqlcmd : The term 'sqlcmd' is not recognized as the name or cmdlet, function, script file or operable program. you need to install SqlCmd.
For instructions how to install SqlCmd, see sqlcmd Utility.
Notice
If you run a SQL command to clean the [accesscontrol].[Clients] table, you will need to run the Authorization Script again to insert CxReporting clients.
For Version 1.5.0
In version 1.5.0, the authentication method was changed from implicit to PKCE to the swagger client.
A PowerShell script to setup the Access Control configuration, that includes the scope and the permissions has been developed as well as a SQL query executed to create the needed clients.
Execute the script in the CxSAST Manager host, after first stopping the CxSystemManager windows service. This will avoid conflicts in the filesystem access and apply the changes to the system when started.
The script can be found under the CxReportingClientFolder (CxReportingClient-XXXX.zip\CxReportingClient\cx-reporting-auth-setup.ps1)
Warning
The script must be executed in a PowerShell console in Administrator mode.
Script Parameters and Execution
The script has the following parameters:
Verbose
Required - To get details about the applied installation steps.Port
Default: 5555 - To configure of the IIS/Docker port where the CxReportingService Client API will be deployed.InstallationPath
Default: C:\Program Files\Checkmarx - To configure the CxSAST base installation folder.BaseAddress
Default: http://localhost - To configure the CxReportingService Client API Host IP or Name.DatabaseHost
Default: empty string - To configure of the SQL Server host where the CxSAST database is deployed. Examples: localhost or 10.32.2.127,1433Username
Default: empty string - To configure of the SQL Server username for the CxSAST database.Password
Default: empty string - To configure of the SQL Server password for the CxSAST database.
Notice
If no Username and Password are set, the SQL Server will try to use Windows Authentication.
Example
Run the Script
Default installation, using the default values:
.\cx-reporting-auth-setup.ps1 -Verbose
For an installation with custom values:
.\cx-reporting-auth-setup.ps1 -Verbose -Port 8080 -PortalPort 3001 -BaseAddress http://10.32.123.12 -InstallationPath "D:\Installations\Checkmarx" -DatabaseHost "localhost\SQLExpress" -Username "**Rep**rts**" -Password "********"
Warning
When running the script, an error message might popup regarding the script not being digitally signed.
Execute one of the following command lines:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
or
powershell -ExecutionPolicy Bypass "& '.\cx-reporting-auth-setup.ps1' -Verbose"
For Versions from 2.0.0
In version 2.0.0, the authentication method was changed from implicit to PKCE to the swagger client.
A PowerShell script to setup the Access Control configuration, that includes the scope and the permissions has been developed as well as a SQL query executed to create the needed clients.
Execute the script in the CxSAST Manager host, after first stopping the CxSystemManager Windows service. This will avoid conflicts in the filesystem access and apply the changes to the system when started.
The script can be found under the CxReportingClientFolder (CxReportingClient-XXXX.zip\CxReportingClient\cx-reporting-auth-setup.ps1)
Caution
The script must be executed in a PowerShell console in Administrator mode.
Script Parameters and Execution
The script has the following parameters:
Verbose
Required - To get details about the applied installation steps.Port
Default: 5555 - To configure of the IIS/Docker port where the CxReportingService Client API will be deployed.PortalPort
Default: 3001 - To configure of the IIS/Docker port where the CxReportingWizard will be deployed.InstallationPath
Default: C:\Program Files\Checkmarx - To configure the CxSAST base installation folder.BaseAddress
Default: http://localhost - To configure the CxReportingService Client API Host IP or Name.DatabaseHost
Default: empty string - To configure of the SQL Server host where the CxSAST database is deployed. Examples: localhost or 10.32.2.127,1433.Username
Default: empty string - To configure of the SQL Server username for the CxSAST database.Password
Default: empty string - To configure of the SQL Server password for the CxSAST database.
Notice
If no Username and Password are set, the SQL Server will try to use Windows Authentication.
Example
Run the Script
Default installation, using the default values:
.\cx-reporting-auth-setup.ps1 -Verbose
For an installation with custom values:
.\cx-reporting-auth-setup.ps1 -Verbose -Port 5555 -PortalPort 3001 -BaseAddress http://10.32.123.12 -InstallationPath "D:\Installations\Checkmarx" -DatabaseHost "localhost\SQLExpress" -Username "CxReports" -Password "123456"
Caution
When running the script, an error message might popup regarding the script not being digitally signed. Execute one of the following command lines:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
powershell -ExecutionPolicy Bypass "& '.\cx-reporting-auth-setup.ps1' -Verbose"
Authentication via Swagger
Notice
Before authenticating to the CxReportingService via Swagger, do the following:
Run the Authorization Setup Script.
Install the Client API.
Access the URL
<ip>:<port>/swagger/
to display the familiar Swagger interface, listing all the available endpoints.Click the Authorize button.
In the Available Authorizations window, select reporting_api under Scopes and click Authorize.
You will be re-direct to the CxPortal login page. Enter your credentials to be authenticated.