Skip to main content

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,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 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:

  1. Run the Authorization Setup Script.

  2. Install the Client API.

  1. Access the URL <ip>:<port>/swagger/ to display the familiar Swagger interface, listing all the available endpoints.

  2. Click the Authorize button.

    SwaggerAuthorizeButton.png

  3. In the Available Authorizations window, select reporting_api under Scopes and click Authorize.

    AvailableAuthorizationsAuthorize.png

  4. You will be re-direct to the CxPortal login page. Enter your credentials to be authenticated.

    AvailableAuthorizationsLogout.png
In this section: