Introduction

CAST Report Generator is now provided as an cross-platform ZIP file alongside the traditional Microsoft Windows GUI "installable" release. In other words this release can run on both Microsoft Windows and Linux operating systems and can be simply unzipped to the install location (no installer is provided). The tool has two main uses:

• the primary goal of this tool is to provide reporting capabilities to the CAST RestAPI - this integration is first and foremost used by the CAST dashboards to generate Standard Compliance reports from within the dashboard interface (see Engineering Dashboard - Report Generation and Security Dashboard - Report Generation).
• The tool can also be used in CLI mode to generate reports, if required.

Where can I obtain the CAST Report Generator for Dashboards?

≥ 1.10.0

You can obtain the Report Generator for Dashboards from CAST Extend:

A ZIP file will be downloaded. Extract the ZIP and deploy the files as described below in Installation process.

1.9.0

You can obtain the CAST Report Generator for Dashboards from the CAST Product Center - this requires a CAST login. Download the latest release, unpack the ZIP, and you will find another ZIP called ReportGeneratorCLIforAllOS.zip alongside the traditional GUI based ReportGeneratorSetup.exe:

Extract the ZIP called ReportGeneratorCLIforAllOS.zip and deploy the files as described below in Installation process.

Limitations

• The tool has no GUI - it is designed to be used primarily when generating reports from within the CAST Dashboard interface (see Engineering Dashboard - Report Generation and Security Dashboard - Report Generation) and also in CLI mode.
• No PDF export capabilities in CLI mode.

Installation prerequisites

To install and use the CAST Report Generator for Dashboards, the following is required:

.NET Core

CAST Report Generator for Dashboards requires the .NET Core runtime/SDK as follows:

This runtime/SDK is available for both Microsoft Windows and for Linux operating systems depending on the Operating System used to host Apache Tomcat:

Supported Operating Systems

CAST Report Generator for Dashboards only requires that .NET Core runtime is present on the operating system. Therefore any operating system that supports the installation of .NET Core can be used for the CAST Report Generator for Dashboards. CAST has tested Microsoft Windows and CentOS (Linux).

CAST RestAPI

≥ 1.9.x

Folder access permissions

The user that Apache Tomcat is running as must have read/write access to the following locations:

• folder into which the Report Generator for Dashboards is unzipped
• "Logs" sub-folder.

Installation and configuration process

Step 1 - Deploy files

Installing CAST Report Generator for Dashboards consists only of unzipping the downloaded ZIP file to a location on the target server, for example:

If you:

• need to use the tool to generate Standard Compliance reports in the CAST Engineering or Security Dashboards, you should deploy the tool on the Apache Tomcat server which hosts your dashboards and then complete Step 2 below.
• simply want to use the tool via CLI to generate reports (see below) you can deploy the tool on any server providing it has network access to a CAST RestAPI interface (i.e. a dashboard). There is nothing further to do in this case.

Step 2 - Configure for Standard Compliance Report Generation in CAST Dashboards

If you need to use the tool to generate Standard Compliance reports in the CAST Engineering or Security Dashboards, a further configuration process is required:

Edit .properties file

Edit the following file with a text editor:

WAR 1.x
CATALINA_HOME\webapps\<deployed_war>\WEB-INF\report.properties

WAR ≥ 2.x
CATALINA_HOME\webapps\<deployed_war>\WEB-INF\classses\application.properties

ZIP ≥ 2.x
<unpacked_zip>\application.properties

Find the following options and modify as explained below:

# Set the Report Generator path
# If this variable is not set then the document generation is considered as disabled.
# The path is probably something such as (Linux/Windows):
#report.reportGenerator=dotnet /opt/report-generator/CastReporting.Console.Core.dll 
#report.reportGenerator=dotnet D:\\data\\CAST\\ReportGeneratorforDashboards\\CastReporting.Console.Core.dll

# Set the directory of reports
#report.directory=/tmp/reports
#report.directory=D:\\temp\\reports

# Set the current Web Service URL. The current REST API called back by the Report Generator.
report.webServiceURL=http://localhost:8888/CAST-RESTAPI/rest

report.reportGenerator=dotnet c:\\ReportGeneratorforDashboards\\CastReporting.Console.Core.dll

report.directory=c:\\temp\\reports

WAR 1.x / ≥ 2.x
report.webServiceURL=http://<server>:<port>/<dashboard>/rest

ZIP ≥ 2.x
report.webServiceURL=http://<server>:<port>/rest

For example:

# Set the Report Generator path
# If this variable is not set then the document generation is considered as disabled.
# The path is probably something such as (Linux/Windows):
#report.reportGenerator=dotnet /opt/report-generator/CastReporting.Console.Core.dll 
#report.reportGenerator=dotnet c:\\ReportGenerator\\CastReporting.Console.Core.dll

report.reportGenerator=dotnet c:\\ReportGeneratorforDashboards\\CastReporting.Console.Core.dll

# Set the directory of reports
#report.directory=/tmp/reports
#report.directory=c:\\temp\\reports

report.directory=c:\\temp\\reports

# Set the current Web Service URL. The current REST API called back by the Report Generator.
report.webServiceURL=http://localhost:8888/CAST-RESTAPI/rest

Restart the application

Restart the web application to ensure the changes are taken into account.

Using CAST Report Generator for Dashboards in CLI mode

As mentioned previously, the primary goal of this release is to provide reporting capabilities for the CAST Dashboards (Engineering and Security) - However, it is also possible to use CAST Report Generator for Dashboards yourself via its CLI. The CLI instructions are identical to those provided for the standard CAST Report Generator GUI - see here for more instructions.

You must run the CAST Report Generator for Dashboards in a specific way when used in CLI mode. The CastReporting.Console.Core.dll is provided with the tool:

dotnet %path_to_CastReporting.Console.Core.dll% -webservice %webservice% -username %username% -password %password% -application %application% -domain %domain% -template %template% -file %file%

For example:

dotnet "D:\data\CAST\ReportGeneratorCore\CastReporting.Console.Core.dll" -webservice "http://<server>:<port>/CAST-RESTAPI/rest/" -username cio -password cast -application "Jurassic Park" -domain "AED" -template "Executive-summary.docx" -file "D:\temp\Core_Report.docx"

Using an API Key instead of a password

If you have enabled SAML authentication mode for your CAST Dashboard/RestAPI deployment, you will need to use an API Key instead of a password. To do, so you will need to modify the command line as follows:

• add the -apikey true option
• enter the API Key in the -password option

For example:

dotnet "D:\data\CAST\ReportGeneratorCore\CastReporting.Console.Core.dll" -webservice "http://<server>:<port>/CAST-RESTAPI/rest/" -username cio -password myapikey -apikey true -application "Jurassic Park" -domain "AED" -template "Executive-summary.docx" -file "D:\temp\Core_Report.docx"

Log files

The CAST Report Generator for Dashboards saves a log of all interactions in the folder into the Logs folder (located in the folder in to which you have unzipped the CAST Report Generator for Dashboards). One log file per day is generated:

ReportGenerator_<timestamp>.log

For example ReportGenerator_20190328.log.

Return codes

One of the following codes will be returned on completion of the CLI: