How to capture Fortify logs in a CI server

1. Question
2. Answer
3. Fortify Jenkins Plugin
   1. Fortify Jenkins Plugin Post-Build Action to Translate and Scan Locally
   2. Fortify Jenkins Plugin Post-Build Action to Translate and Scan Remotely
   3. Fortify Jenkins Plugin Post-Build Action to Translate Locally and Scan Remotely
   4. Fortify Jenkins Plugin Pipeline Steps to Translate and Scan Locally
   5. Fortify Jenkins Plugin Pipeline Steps to Translate and Scan Remotely
   6. Fortify Jenkins Plugin Pipeline Steps to Translate Locally and Scan Remotely
4. Fortify Plugin for Bamboo
5. Fortify Azure DevOps Extension
6. Docker
7. Fortify ScanCentral SAST
   1. Additional ScanCentral log files:
8. References

Question

How do I create a Fortify log file in a CI server with debugging turned on?

Answer

Creating a Fortify log file in a CI server is dependent on the type of CI server in use, as well as how Fortify scanning is supported within the CI server. The -debug and -logfile command-line options for sourceanalyzer are still used, except from within the CI server. The path where the Fortify log file(s) should be saved to can be specified, as well as the -verbose argument for more detailed log file output.

If Fortify is run in a container, the log files must be saved to a location outside the container so they persist after the container is torn down. See the technical note on How to manage Fortify artifacts in a CI server for more information on how/where to save the Fortify log files. Note that if the -logfile command-line option is omitted, Fortify will save the log file to a default location:

<userhome>\AppData\Local\Fortify\sca<version>\log\sca.log 
where <version> is the Fortify Static Code Analyzer version.

For resolving scan errors, the developer should generate separate log files for the translation and scan phases of the scan as shown below, according to the type of CI server in use.

Note: Fortify log file artifacts should be managed externally to avoid your CI server running out of disk space or causing potential performance issues. The examples below do not do this, they are provided to explain the Fortify tool commands only.

Fortify Jenkins Plugin

See the Micro Focus Fortify Jenkins Plugin Users Guide for details on how to configure and set up the Fortify Jenkins Plugin on your Jenkins server. Detailed steps are provided, depending on the application type and how the scan should be performed within Jenkins. Post-Build Actions and Pipeline Jobs are supported for configuring Fortify analysis.

Fortify Jenkins Plugin Post-Build Action to Translate and Scan Locally

For the Fortify Translation Phase, the Fortify Jenkins Plugin provides a Fortify SCA translation options box, where the -debug, -verbose, and -logfile options can be specified as follows:

For example: "-debug" "-verbose" "-logfile" "\path\to\logfile\translate.log"

Note: Enclose each option and parameter in double quotes in boxes where you can specify multiple values.

The following application types are supported by the Fortify Jenkins Plugin:

• NET Devenv
• .NET MSBuild
• .NET source code scan
• Java
• Maven - Note: The translation log will be located in the /target directory that is created when the “package” runs from Maven. Any log file location specified in the Jenkins Plugin is ignored when the Fortify Maven Plugin performs the translation.
• Gradle
• Other
• Advanced

For some application types, options to enable the debug and verbose logging options are provided, and a Log file location box is provided, so a custom location for the Fortify Static Code Analyzer log file can be specified. The full path and file name for the log file should be specified.

For the Fortify Scan Phase, the Run Fortify SCA scan check box should be selected, and then the scan settings can be selected. Like the translation phase, options to enable the debug and verbose logging options are provided and a Log file location box is provided, so a custom location for the Fortify Static Code Analyzer log file can be specified. The full path and file name for the log file should be specified. By default the log file for the scan phase is written to the workspace in:

/.fortify/sca<version>/log

Fortify Jenkins Plugin Post-Build Action to Translate and Scan Remotely

For the Fortify Translation Phase, after Fortify Assessment has been selected in the Post-build Actions of Jenkins, and Remote translation & remote scan has been selected, click Advanced, and then specify the logging options along with any other translation options needed. Each option and parameter should be enclosed in double quotes.

For example: "-debug" "-verbose" "-logfile" "\path\to\logfile\translate.log"

For the Fortify Scan Phase, click Optional configuration, and in the Fortify SCA scan options field, specify the logging options along with any other scan options needed. Each option and parameter should be enclosed in double quotes.

For example: "-debug" "-verbose" "-logfile" "\path\to\logfile\scan.log"

Click Save after the logging options for both the translation and scan phases have been entered.

Fortify Jenkins Plugin Post-Build Action to Translate Locally and Scan Remotely

For the Fortify Translation Phase, after Fortify Assessment has been selected in the Post-build Actions of Jenkins, and Local translation & remote scan has been selected, then the application type is selected, which results in menu options being displayed according to the application type chosen. The GUI may provide options to enable or disable the debug or verbose logging options. Otherwise, the Fortify SCA translation options box can be used to specify the Fortify logging options as follows:

For example: "-debug" "-verbose" "-logfile" "\path\to\logfile\translate.log"

Each option and parameter should be enclosed in double quotes.

Note that for Maven projects, the translation log will be located in the /target directory that is created when the “package” runs from Maven. Any log file location specified in the Fortify Jenkins Plugin is ignored when the Fortify Maven Plugin performs the translation.

For the Fortify Scan Phase, click Optional configuration, and in the Fortify SCA scan options field, specify the logging options along with any other scan options needed. Each option and parameter should be enclosed in double quotes.

For example: "-debug" "-verbose" "-logfile" "\path\to\logfile\scan.log"

Click Save after the logging options for both the translation and scan phases have been entered.

Fortify Jenkins Plugin Pipeline Steps to Translate and Scan Locally

The Jenkins Plugin Pipeline uses steps to perform the Fortify Translation and Fortify Scan phases. If any Fortify Jenkins Plugin Pipeline step in a script fails to execute, then the build fails. There is an option to implement an exception-catch mechanism to ignore a step failure.

The fortifyTranslate Step is used to translate the project source code on the local system. The fortifyScan Step is used to run a scan on all the translated files with the specific build ID.

debug, verbose, and logFile parameters are used to control logging during both the Fortify translation and scan phases:

debug

Optional (boolean). Specifies whether to include debug information in the Fortify Support log file. (Default value is false).

verbose

Optional (boolean). Specifies whether to send verbose status messages to the console and to the Fortify Support log file. (Default value is false).

logFile

Optional (String). Specifies the log file location and file name. The default file name is sca.log and the default location is the workspace directory.

The following example translates a Java project with the debug, verbose, and logFile options specified:

node {
    stage('Fortify Translate') {
        fortifyTranslate buildID: 'MyJavaApp',
        logFile: 'filesystem\\path\\MyJavaApp-translate.log',
        debug: 'true',
        verbose: 'true',
        projectScanType: fortifyJava(javaSrcFiles:
            'src\\main\\java\\com\\projectA',javaVersion: '1.8')
    }
}

The following example scans the previously-translated project with the MyJavaApp build ID:

node {
    stage('Fortify Scan') {
        fortifyScan buildID: 'MyJavaApp', resultsFile: 'MyJavaApp.fpr',
        logFile: 'filesystem\\path\\MyJavaApp-scan.log',
        debug: 'true',
        verbose: 'true',
    }
}

Note that the values for the logging options for both the translation and scan phases are enclosed in single quotes.

Fortify Jenkins Plugin Pipeline Steps to Translate and Scan Remotely

The fortifyRemoteArguments step is used to specify Fortify SCA translation and scan options in a settings file for remote analysis. Following the fortifyRemoteArguments step, the fortifyRemoteAnalysis step is used to initiate the remote analysis.

The following example shows the fortifyRemoteArguments stage, where the debug, verbose, and logfile location options are set for the translation phase using transoptions, and the scan phase using scanOptions. The fortifyRemoteAnalysis stage will send the project to a remote system for analysis after the appropriate options are set, according to the project type, and other configuration options needed:

node {
    stage('Fortify Remote Arguments') {
        fortifyRemoteArguments transOptions: '"-debug", "-verbose", 
            "-logfile" "filesystem\\path\\MyApp-translate.log"'
            scanOptions: '"-debug", "-verbose", "-logfile" "filesystem\\path\\MyApp-scan.log"'
    }
    stage('Fortify Remote Analysis') {
        fortifyRemoteAnalysis remoteAnalysisProjectType: ...
       ...
    }
}

Note that each option and its value is enclosed in double quotes, while the entire string for all of the options specified for transOptions and scanOptions are enclosed in single quotes.

Fortify Jenkins Plugin Pipeline Steps to Translate Locally and Scan Remotely

To translate the project locally and then scan the project on a remote system, the fortifyTranslate stage is used to specify the options for the translation, and the fortifyRemoteScan stage is used to specify the options for the scan phase.

The following example shows the fortifyTranslate stage, where the debug, verbose, and logfile location options are set for the translation phase, performed on the local machine. The fortifyRemoteScan stage uses the remoteOptionalConfig parameter to set the scanOptions, where the debug, verbose, and logfile location options are set for the scan to be performed on a remote system.

node {
    stage('Fortify Translate') {
        fortifyTranslate buildID: 'MyJavaApp',
            logFile: 'filesystem\\path\\MyJavaApp-translate.log',
            debug: 'true',
            verbose: 'true',
            projectScanType: fortifyJava(javaSrcFiles:
                'src\\main\\java\\com\\projectA',
            javaVersion: '11')
    }
    stage('Remote Fortify Scan') {
        fortifyRemoteScan buildID: 'MyJavaApp',
            remoteOptionalConfig: [notifyEmail: 'joe@xyzCo.com',
                scanOptions: '"-debug", "-verbose", "-logfile" "filesystem\\path\\MyApp-scan.log"']
    }
}

Note that the values for the logging options for the translation phase are enclosed in single quotes. For the scan phase, each option and its value is enclosed in double quotes and the entire string for all of the options specified for scanOptions is enclosed in single quotes.

Fortify Plugin for Bamboo

See the Fortify Plugin for Bamboo Documentation for details on how to configure and set up the Fortify Plugin for Bamboo on your Bamboo server. Detailed steps are provided, depending on the application type. After the Fortify Static Code Analyzer task has been added to your plan, it should be configured to run the scan.

The following application types are supported by the Fortify Plugin for Bamboo:

• .NET Devenv
• .NET MSBuild
• .NET source code scan
• Java
• Maven 3 - Note: The translation log will be located in the /target directory that is created when the “package” runs from Maven. Any log file location specified in the Fortify Plugin for Bamboo is ignored when the Fortify Maven Plugin performs the translation.
• Gradle
• Other

For the Fortify Translation Phase, select the Run Fortify SCA Translation check box, and then specify the translation settings. To enable the debug or verbose options or to specify a custom location for the Fortify Static Code Analyzer log file, click Advanced options. Then, enter the translation options applicable for your application, including the log file options.

For example: "-debug" "-verbose" "-logfile" "\path\to\logfile\translate.log"

Note: Enclose each option and parameter in double quotes in boxes where you can specify multiple values.

For the Fortify Scan Phase, select the Run Fortify SCA Scan check box, and then specify the scan settings. To enable the debug or verbose options or to specify a custom location for the Fortify Static Code Analyzer log file, click Advanced options. Then, enter the scan options applicable for your application, including the log file options.

For example: "-debug" "-verbose" "-logfile" "\path\to\logfile\scan.log"

Note: Enclose each option and parameter in double quotes in boxes where you can specify multiple values.

Fortify Azure DevOps Extension

The Fortify Azure DevOps Extension can be used to run Fortify SCA in either a Fortify Static Code Analyzer Assessment task or a Fortify ScanCentral SAST Assessment task. See the Fortify Azure DevOps Extension Documentation for details on how to configure and set up either of these tasks to be run in the Azure DevOps agent. The translation and scan can be performed on a local agent, or remotely using Fortify ScanCentral SAST (formerly Fortify CloudScan).

The following application types are supported by the Fortify Azure DevOps Extension with the configuration settings dynamically changing based on the application type selected:

• .NET
• Java3
• Other

After the Fortify Static Code Analyzer Assessment build step has been added, options to configure Fortify logging are available. SCA verbose and SCA debug check boxes are available for both the Fortify Translation and Scan phases and can be selected or deselected to configure the amount of Fortify data logged.

For the Fortify Translation Phase, select the Run Fortify SCA Build (translate) check box. The location of the log file can be specified in the Additional Build Parameters text box. A custom location for the log file can be specified as follows:

For example:  "-logfile" "\path\to\logfile\translate.log"

For the Fortify Scan Phase, a selection for either a local scan or a remote scan using Fortify ScanCentral SAST must first be made. For a local scan, select the Run Fortify SCA scan check box. The location of the log file can be specified in the Additional Scan Options text box. A custom location for the log file can be specified as follows:

For example:  "-logfile" "\path\to\logfile\scan.log"

For a remote scan using Fortify ScanCentral SAST, a standard Azure DevOps Publish Pipeline Artifact build step should be added to collect the scan results and log files. To ensure that the scan log files are available when the scan artifacts are published, make sure that the Continue on error check box in the task configuration is selected. Otherwise, if the assessment fails, the artifact collection task does not start.

Docker

See the Fortify Static Code Analyzer and Tools Software Documentation

• Chapter 2: Installing Fortify Static Code Analyzer, section Using Docker to Install and Run Fortify Static Code Analyzer for details on how to configure and run the Fortify Static Code Analyzer image as a container.

To capture the Fortify log files for the Translation and Scan Phases when running a Fortify scan in Docker, the Docker image with Fortify installed must first be created (see the technical note on How to run Fortify Static Code Analyzer in a container).

The Docker image must be run separately for the translate and scan commands. The following example commands mount the input directory /sources in /src and the output directory in /scratch_docker. The image name in the example is fortify-sca. (credit: Fortify SCA Users Guide)

Translation phase:

docker run -v /scratch_local/:/scratch_docker -v /sources/:/src -it fortify-sca -b <build_id> 
-project-root /scratch_docker -fcontainer [<sca_options>] /src

Specify the logging options needed as part of the <sca_options> passed to -fcontainer.

For example, to enable debug and verbose logging, and to send the translation log file to the host’s /scratch_local directory, the following options are passed to -fcontainer:

-fcontainer ["-debug" "-verbose" "-logfile" "translate.log"]

Scan phase:

docker run -v /scratch_local/:/scratch_docker -it fortify-sca -b <build_id> -project-root /scratch_docker 
-scan -fcontainer [<sca_options>] -f /scratch_docker/results.fpr

Just like for the translation phase, to enable debug and verbose logging, and to send the scan log file to the host’s /scratch_local directory, the following options are passed to -fcontainer:

-fcontainer ["-debug" "-verbose" "-logfile" "scan.log"]

The results.fpr, translation.log, and scan.log files are created in the host’s /scratch_local directory

Fortify ScanCentral SAST

See the Fortify Software Security Center Documentation - Fortify ScanCentral SAST Installation, Configuration, and Usage Guide for details on how to configure and run Fortify ScanCentral SAST. Code analysis tasks can be offloaded from build machines to a cloud of machines (sensors) provided for the purpose of translating and/or scanning code using Fortify SCA.

Depending on the language of the source code, Fortify ScanCentral SAST can be used to offload only the Fortify SCA scan phase, or both the translation and scan phases to ScanCentral SAST sensors.

Fortify SCA log files by default are created in a temp directory that is removed after program termination, so it is important to save any log files needed by specifying the -logfile option with a location where the log file can later be retrieved.

Scan phase offloaded using ScanCentral:

When submitting a scan request that offloads only the scan phase of Fortify SCA, the following command will enable debug and verbose logging for the Fortify SCA scan phase, and specifies the location the scan log will be sent to:

scancentral.bat -url <sc_controller_url> start -b <my_build_id> -scan -debug -verbose -logfile \"\\path\\to\\logfile\\scan.log\"

Note that special characters in options specified after the -scan keyword must be escaped (such as the quotes around the log file location, as well as the directory separator character). The scancentral command interprets any options after the -scan keyword as scan arguments for Fortify SCA.

Translation and Scan phases offloaded using ScanCentral:

When performing a remote translation and scan of a project, the arguments command for scancentral should be used to generate a settings file for additional Fortify SCA command-line options. The -targs option of the arguments command specifies the translation arguments for Fortify SCA. The -sargs option of the arguments command specifies the scan arguments for Fortify SCA.

The following command will enable debug and verbose logging for both the translation and scan phases, and specifies the location the translation and scan log files will be sent to:

scancentral arguments -targs "-debug" -targs "-verbose" -targs "-logfile '\path\to\log file\translation.log'" -sargs "-debug" -sargs "-verbose" -sargs "-logfile '\path\to\log file\scan.log'"

Note that the -targs and -sargs options take a single string argument, enclosed in double quotes. To specify multiple translation or scan arguments, use multiple -targs and (or) -sargs options. When the translation or scan option has a path parameter that includes a space, enclose the path in single quotes, as shown above for the path specified for the -logfile option.

The packagescanner tool can also be used to specify additional Fortify SCA command-line options. Packagescanner takes a package generated using the ScanCentral package command, generates Fortify Static Code Analyzer commands, and then performs a scan using a locally installed Fortify SCA instance. The following options are available for use with packagescanner for specifying Fortify SCA logging options:

Option	Description
-sargs, --scan-arguments	(Optional) Additional Fortify SCA scan options. Enclose multiple options in quotes separated by spaces, or repeat this option for each Fortify SCA scan option and parameter.
--sca-scan-log	(Optional) Fortify SCA scan log file. By default, the log file is created in a temp folder, which is removed after program execution.
--sca-translation-log	(Optional) Fortify SCA translation log file. By default, the log file is created in a temp folder, which is removed after program execution.
-targs, --translation-arguments	(Optional) Fortify SCA translation options. Enclose multiple options in quotes separated by spaces, or repeat this option for each Fortify SCA translation option and parameter.

The following packagescanner command will enable debug and verbose logging for both the translation and scan phases, and specifies the location the translation and scan log files will be sent to:

packagescanner -b <my_build_id> -fpr <fpr_output_file> -package <Path_to_package_file_generated_by_ScanCentral> -targs "-debug -verbose" -sargs "-debug -verbose" --sca-translation-log "\path\to\log file\translation.log" --sca-scan-log "\path\to\log file\scan.log"

Additional ScanCentral log files:

The Fortify ScanCentral Client, Sensor and Controller generate log files which can be found in the following locations:

Windows ScanCentral Client and Sensor logs:

%FORTIFY_HOME%\scancentral\log

where

%FORTIFY_HOME% is ${win32.LocalAppdata}\Fortify 

On Windows 10, for example, the location is

C:\Users\<user>\AppData\Local\Fortify

Linux ScanCentral Client and Sensor logs:

~/.fortify/scancentral/log/scancentral.log

Windows ScanCentral Controller log:

<sc_controller_dir>\tomcat\logs\cloudCtrl.log

Linux ScanCentral Controller log:

<sc_controller_dir>/tomcat/logs/cloudCtrl.log

For additional trouble shooting of ScanCentral Sensors, Sensor temporary folders are generated that contain Mobile Build Session (MBS) files, Fortify SCA log files, and generated FPR files at the following location on Windows:

c:\ScanCentralWorkdir\<job_token>

Sensor stdOut and stdErr logs:

c:\ScanCentralWorkdir\workerout.log and c:\ScanCentralWorkdir\workererr.log

Note: Before a sensor is started, check to make sure that the log files are not open in an application. Open log files prevent the process from writing to the file.

Commons-daemon log:

c:\ScanCentralWorkdir\<year_month_day>.log

The Start and Retrieve commands for ScanCentral take a -log or –logfile option for specifying the filename for local log output:

Start:

scancentral.bat -url <sc_controller_url> start -b <my_build_id> -log "path\to\log\start.log" -scan -Xmx2G

Retrieve:

scancentral.bat -url <sc_controller_url> retrieve -token <tokenid> -f worker.fpr -log "path\to\log\worker.log"

References

• Micro Focus Security Fortify Static Code Analyzer User Guide - Chapter 13: Command Line Interface, Chapter 2: Installing Fortify Static Code Analyzer
• Micro Focus Fortify Jenkins Plugin Users Guide
• Fortify Plugin for Bamboo Documentation
• Fortify Azure DevOps Extension Documentation
• Fortify Software Security Center Documentation - Fortify ScanCentral SAST Installation, Configuration, and Usage Guide