OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 36 of 111

Installation, Configuration, and Usage Guide

Chapter 2: About the Fortify ScanCentral SAST Controller

Encrypting the Shared Secret on the Controller

Passwords exist in the ScanCentral Controller configuration file as plain text. You can encrypt the

passwords and other values. You can use encrypted keys as values for the following properties:

l

client_auth_token

l

lim_license_pool_password

l

lim_proxy_password

l

lim_proxy_user

l

smtp_auth_pass

l

ssc_scancentral_ctrl_secret

l

swagger_password

l

swagger_username

l

worker_auth_token

To encrypt a shared secret on the Controller:

1. At the command prompt, type the following:

<controller_install_dir>/bin/pwtool <pwtool_keys_file>

2. When prompted, type the password to encode, and then press Enter.

Note: For the sake of security, make sure that the pwtool key file you use to encrypt secrets

for sensors is different from the pwtool key file you use to encrypt secrets on the Controller.

The pwtool generates a new key stored in the file on the path specified in step 1, or reuses an

existing file on the specified path.

3. Copy the new encrypted secret, and paste it as the value for one of the following properties in

the config.propertiesfile:

client_auth_token, lim_license_pool_password, lim_proxy_password, lim_proxy_

user, smtp_auth_pass, ssc_scancentral_ctrl_secret, swagger_password, swagger_

username, worker_auth_token

Tip: Fortify recommends that you assign separate, unique shared secrets for the client_

auth_token, smtp_auth_pass, ssc_scancentral_ctrl_secret, and worker_auth_

tokenproperties.

4.

Create additional encrypted shared secrets (steps 1 and 2) and, in the config.propertiesfile,

paste these as values for the two properties to which you did not already assign an encrypted

secret in step 3.

5.

6.

Uncomment the following property in the config.propertiesfile:

pwtool_keys_file=<pwtool_keys_file>

Save and close the config.propertiesfile.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 37 of 111

Installation, Configuration, and Usage Guide

Chapter 2: About the Fortify ScanCentral SAST Controller

See Also

"Safely Shutting Down Sensors" on page 55

Avoiding Read Timeout Errors

To avoid read timeout errors that can occur during attempts to upload large log files, you can

configure the connection timeout between the Controller and Fortify Software Security Center,

between the Controller and sensors, and between the Controller and clients.

To configure the connection timeout between the Controller and Fortify Software Security Center:

1.

On the Controller, navigate to <controller_install_

dir>/tomcat/webapps/scancentral-ctrl/WEB-INF/classes/and open the

config.propertiesfile in a text editor.

2.

Increase the value of the restapi_connect_timeoutand restapi_read_timeoutproperties

to an acceptable threshold (in milliseconds).

3. Save the changes.

To configure the connection timeout between the Controller and a sensor:

1.

2.

On the sensor machine, navigate to the <sca_install_dir>/Core/configdirectory and open

the worker.propertiesfile in a text editor.

Uncomment the restapi_connect_timeoutand restapi_read_timeoutproperties, and set

the value of each to an acceptable threshold (in milliseconds).

3. Save the changes.

To configure the connection timeout between the Controller and a client:

1.

2.

On the client machine, navigate to the <client_install_dir>/Core/configdirectory and

open the client.propertiesfile in a text editor.

Uncomment the restapi_connect_timeoutand restapi_read_timeoutproperties, and set

the value of each to an acceptable threshold (in milliseconds).

3. Save the changes.

Starting the Controller

You can start the Fortify ScanCentral SAST Controller manually or set it to start automatically, as a

service. For information about how to start the Controller automatically, see "Installing the Controller

as a Windows Service" on page 20.

To start the Controller manually:

1. If you plan to upload your scan results to Fortify Software Security Center, make sure that the

Fortify Software Security Center instance is running.

2.

On the machine that hosts the Controller, navigate to the tomcat/bindirectory:

3. At the command prompt, run one of the following commands:

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 38 of 111

Installation, Configuration, and Usage Guide

Chapter 2: About the Fortify ScanCentral SAST Controller

l

On a Windows system, run startup.bat.

l

On a Linux system, run ./startup.sh.

If Tomcat is running as a service, rather than running the startup command, you can just start the

service.

Placing the Controller in Maintenance Mode

An abrupt shutdown of the Fortify ScanCentral SAST Controller can result in the loss of scans already

started on sensors. To prevent this from happening, place your Controller in maintenance mode. After

you do, the Controller accepts no new job requests from clients and assigns no queued jobs to

sensors.

After the Controller is placed in maintenance mode, sensors complete the scans they are currently

running, but accept no new scans. After the Controller is back up and running, the sensors again

become available.

Tip: If the Controller is in maintenance mode, you can manually shut down any sensor that is not

running a scan.

Important! To place the Controller in maintenance mode, the Controller must be version 21.2.0

or later.

1. Log on to Fortify Software Security Center as an administrator and open the Fortify ScanCentral

SAST page.

2. In the left pane of the SAST page, select Controller.

3. Click START MAINTENANCE MODE.

The Controller receives the maintenance request from Fortify Software Security Center and, if any

sensors are running scans, the Controller mode changes from ACTIVE to WAITING_FOR_JOB_

COMPLETED. If no job is being processed, the mode changes directly from ACTIVE to

MAINTENANCE. At this point, you can safely shut down the Controller.

"Removing the Controller from Maintenance Mode" on the next page

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 39 of 111

Installation, Configuration, and Usage Guide

Chapter 2: About the Fortify ScanCentral SAST Controller

Removing the Controller from Maintenance Mode

To remove the Fortify ScanCentral SAST Controller from maintenance mode:

1. Log on to Fortify Software Security Center as an administrator and open the Fortify ScanCentral

SAST page.

2. In the left pane of the SAST page, select Controller.

3. Click END MAINTENANCE MODE.

"Stopping the Controller" below

Stopping the Controller

You can stop the Controller immediately using the following procedure. However, Fortify strongly

recommends that you first place the Controller in maintenance mode to preserve any scans that are

running.

To stop the Fortify ScanCentral SAST Controller:

1.

On the machine where the Controller is installed, navigate to the Tomcat bindirectory:

2. Type one of the following commands:

l

On a Windows system: shutdown.bat

l

On a Linux system: ./shutdown.sh

"Removing the Controller from Maintenance Mode" above

"Safely Shutting Down Sensors" on page 55

Fortify ScanCentral SAST API

The Fortify ScanCentral SAST provides a RESTful API that enables you perform tasks described in the

following table. The tasks are grouped by the grouping in the API Documentation (Swagger UI).

Tasks you can perform

Request Group

Retrieve the scan requests from the Controller, report job status, and upload

artifacts

sensor-controller

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 40 of 111

Installation, Configuration, and Usage Guide

Chapter 2: About the Fortify ScanCentral SAST Controller

Tasks you can perform

Request Group

job-controller

info-controller

Work with scan jobs such as running a new scan or canceling a job

Get information from the Controller such as the Fortify Software Security

Center URL

Check for client or sensor updates

update-controller

core-controller

Check to see if the Controller is running

To use the Fortify ScanCentral SAST API, your application makes an HTTP request and parses the

response. The Fortify ScanCentral SAST API uses JSON and XML as its communication format and

the standard HTTP methods of GET, POST, and DELETE. URIs have the following structure:

The following is an example cURL:

curl -X 'GET' \

'https://my_ctrl_host:8080/scancentral-ctrl/rest/v4/job/a2f0fe34-f810-

4c76-8e0b-86dfb4f40c9c/status' \

-H 'accept: */*' \

-H 'fortify-client: my_secret'

Authentication

Authenticate your API request with a Fortify ScanCentral SAST authentication token. Use the value of

the client_auth_tokenor the worker_auth_tokenfrom the config.propertiesfile for the

Controller depending on the request. Set the same authentication token in the fortify-client

header that is set for the client_auth_token. Similarly, set the same authentication token in the

fortify-workerheader that is set for worker_auth_token. The following table lists which

authentication token is used for each request group.

Authentication token

Request Group

sensor-controller

job-controller

client_auth_token worker_auth_token

x

info-controller

update-controller

core-controller

x

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 41 of 111

Installation, Configuration, and Usage Guide

Chapter 2: About the Fortify ScanCentral SAST Controller

Accessing the Fortify ScanCentral SAST API Documentation

(Swagger UI)

The documentation describes the input, output, and API endpoints. It also provides the ability to test

the endpoints before using them in production.

To access this documentation:

1. Configure the credentials for access to the documentation in the Controller

config.propertiesfile with the two properties: swagger_usernameand swagger_

password. For more information, see "Configuring the Controller" on page 27.

2. Open a browser and visit <controller_url>/rest/swagger-ui/index.html.

Note: OpenAPI documentation in JSON format is available at <controller_url>/rest/api-docs.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 42 of 111

Chapter 3: About Fortify ScanCentral SAST

Sensors

Fortify ScanCentral SAST sensors are computers set up to receive scan requests and analyze code

using Fortify Static Code Analyzer. A sensor accepts either a mobile build session (MBS) file and

performs a scan, or it accepts a project package that contains sources and dependencies, which it

translates and scans.

For MBS scans, ScanCentral SAST supports all languages that Fortify Static Code Analyzer supports.

For remote translation and scans of the prepared packages, ScanCentral SAST supports only the

languages that can be used with remote translation. For a list of languages supported for performing

remote translation, see the Fortify Software System Requirements document.

Tip: As you set up your Fortify ScanCentral SAST environment, you can use subnets to segment

your build machines from the sensors. The build machines need only communicate with the

Controller, which in turn communicates with the sensors.

This section contains the following topics:

Safely Shutting Down Sensors

45

49

55

Installing Sensors

To make it convenient for network administrators to isolate traffic to Fortify ScanCentral SAST

sensors, Fortify recommends that you install sensors in a separate subnet. Use the sensors only as

scan boxes. Fortify ScanCentral SAST supports only one sensor per machine.

Installing a Sensor Using Fortify Static Code Analyzer

The following procedure describes how to create a new sensor. For information about how to upgrade

an existing sensor, see "Upgrading Sensors" on page 63.

If you use Windows, you can install the sensor as a Windows service. For instructions, see "Installing a

Sensor as a Service" on the next page.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 43 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

To install a sensor:

1. Use the instructions provided in the OpenText™ Fortify Static Code Analyzer User Guide to

install Fortify Static Code Analyzer.

Make sure you select Fortify ScanCentral SAST client as a component during the Fortify Static

Code Analyzer installation.

2.

3.

Navigate to the <sca_install_dir>/Core/configdirectory, and open the

worker.propertiesfile in a text editor.

Specify a value for the worker_auth_tokenproperty.

If you are using a plain text password, use the password set for the worker_auth_token

property in the Controller config.propertiesfile. For information about how to generate an

encrypted shared secret, see "Encrypting the Shared Secret on a Sensor" on the next page.

4.

Save and close your worker.propertiesfile.

Installing a Sensor as a Service

If you use Windows services, you can install the Fortify ScanCentral SAST sensor as a Windows

service.

To install the sensor as a Windows service:

1.

Navigate to the <sca_install_dir>\bin\scancentral-worker-servicedirectory, and

then do one of the following:

l

To use a plain text password, run the following command:

setupworkerservice.bat <sca_version> <controller_url> <shared_secret>

l

To use an encrypted password, run the following command:

setupworkerservice.bat <sca_version> <controller_url> "<encrypted_

shared_secret>" <path_to_pwtool.keys_file>

Important! Make sure that you enclose <encrypted_shared_secret> in quotes. This

ensures that the encrypted shared secret does not get corrupted when the services

installer creates the worker.propertiesfile.

where <sca_version> is the Fortify Static Code Analyzer version (<major>.<minor>).

Caution! The setupworkerservicecommand does not correctly handle worker_auth_

tokentokens that contain the caret character (^). If you must use the caret character as a

part of a worker_auth_token, use the following formula:

saved_caret_count = carets_used_on_command_line / 8

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 44 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

Examples:

For a worker_auth_tokenthat contains a single caret, such as this^that, run the

following command:

setupworkerservice.bat 24.2 http://url.com this^^^^^^^^that

For a worker_auth_tokenthat contains two caret characters, such as this^^that, run the

following command:

setupworkerservice.bat 24.2 http://url.com this^^^^^^^^^^^^^^^^that

For information about how to encrypt a shared secret, see "Encrypting the Shared Secret on a

Sensor" below.

2. Start the service, as follows:

net start FortifyScanCentralWorkerService

The services installer creates the <sca_install_dir>\Core\config\worker.propertiesfile for

you.

See Next

"Enabling Sensor Auto-Start on Windows as a Service" on page 50

See Also

"Installing Sensors" on page 43

Configuring Sensors

After you install the Fortify ScanCentral SAST sensors, you can configure sensor settings such as the

maximum run time for scans, sensor expiration time, job cleanup timing, and more.

"Avoiding Read Timeout Errors" on page 38

Encrypting the Shared Secret on a Sensor

Passwords exist in the ScanCentral SAST sensor configuration file as plain text. You can encrypt the

worker_auth_tokenproperty value.

To encrypt a shared secret on a sensor:

1. At the command prompt, run the following command:

<sca_install_dir>/bin/pwtool <pwtool_keys_file>

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 45 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

2. When prompted, type the password to encode, and then press Enter.

The pwtool generates a new pwtool.keysfile to <pwtool_keys_file> and prints a new

encrypted secret to the console.

3.

4.

Copy the encrypted secret, and paste it as the value for worker_auth_tokenproperty in the

worker.propertiesfile.

Add the following line (property) to the worker.propertiesfile:

pwtool_keys_file=<pwtool_keys_file>

Save and close the worker.propertiesfile.

5.

See Also

"Installing Sensors" on page 43

Setting the Maximum Run Time for Scans

By default, a sensor can run a scan for an indefinite period of time, which prevents it from running

other scans. You can limit the amount of time scans can run on sensors for a specific job, for a specific

sensor, or globally for all sensors.

The following rules of precedence apply to timeout settings:

l

Job timeout settings override any sensor-specific or global timeout settings.

l

Sensor timeout configured on the command line overrides a global timeout setting.

Configuring the Maximum Run Time for a Specific Job

To configure the maximum run time of one minute for a specific job, run the following command:

scancentral -url <controller_url> start --scan-timeout 1

To configure the maximum run time of two minutes for a specific sensor, run the following:

scancentral -url <controller_url> worker --scan-timeout 2

Configuring the Maximum Run Time for All Sensors

To configure the maximum run time for all sensors:

1.

2.

3.

Navigate to <controller_install_dir>/tomcat/webapps/scancentral-ctrl/WEB-

INF/classes/and open the config.propertiesfile in a text editor.

Set the scan_timeoutproperty value to the maximum number of minutes for scans to run on

sensors.

Save and close the config.propertiesfile.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 46 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

Changing Sensor Expiration Time

By default, sensors expire 168 hours after they become inactive. To change this default value:

1.

2.

3.

Navigate to <controller_install_dir>/tomcat/webapps/scancentral-ctrl/WEB-

INF/classes/and open the config.propertiesfile in a text editor.

Set the worker_expiry_delayproperty value to the number of hours to elapse after inactivity

before sensors expire.

Save and close the config.propertiesfile.

Configuring Sensors for Remote Translation of .NET Languages

To use your Fortify ScanCentral SAST sensors for remote translation of code written in a

.NET language, configure at least one sensor with the software required to support .NET. Sensors on

Windows or Linux can accept any package for remote translation built by MSBuild and dotnet as long

as .NET capability is enabled. See the Fortify Software System Requirements document for specific

.NET version requirements.

After you start a ScanCentral SAST sensor, it automatically detects if a supported version of .NET is

installed and displays a message that .NET capability is enabled. This indicates that the sensor can

now translate .NET projects.

Important! To avoid Windows errors caused by too long a path during a .NET translation, Fortify

strongly recommends that you start ScanCentral SAST sensors from a directory with a short

name and path.

See Also

"Installing Sensors" on page 43

"Starting the Sensors" on page 49

Configuring Sensors to Use the Progress Command When

Starting on Java

To use the progresscommand to check the progress of your Fortify Static Code Analyzer scans, you

must complete the following sensor configuration:

1. Create a JMX access file, and add the following text to it:

<user_role> readonly

where <user_role> is text that represents something like a user name.

2. Create a JMX password file, and add the following text to it:

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 47 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

<user_role> <password> readonly

where <user_role> is the value you specified in the JMX access file.

3. Run one of the following commands:

l

On a Windows system, cacls jmxremote.password /P <username>:R

l

On a Linux system, chmod 600 jmxremote.password

4.

Open the worker.propertiesfile in a text editor, and then add the following properties to it:

sca_jmx_port=<port>

sca_jmx_access_file=<path_to_access_file>

sca_jmx_password_file=<path_to_password_file>

sca_jmx_password=<password>

sca_jmx_user=<user_role>

sca_jmx_auth=true

5.

Save and close the worker.propertiesfile.

After you complete this configuration, Fortify ScanCentral SAST clients start on the specified port

using JMX password authentication. Make sure that the port is not already bound.

Caution! If you use sca_jmx_auth, you can start only one sensor. Any attempt to open a new

Fortify Static Code Analyzer instance results in a bind port error. To have multiple sensors on a

machine, you must have several Fortify ScanCentral SAST instances, each with its own

worker.propertiesfile.

Configuring Where to Generate Job Files and the worker_

persist.properties File

For containerized deployments, it is useful to determine where files are generated so that you can

customize persistence. This enables you to persist the worker_persist.propertiesfile, which you

need to maintain sensor pool assignments, without having to keep all the old job files.

Note: If you choose not to configure these locations, the default locations are used. The default

location for the worker_persist.propertiesfile is <working_dir>/props. The default

location for the job files is <working_dir>/jobs.

To configure where job files and the worker_persist.propertiesfile are generated:

1.

On a sensor machine, navigate to the <sca_install_dir>/Core/configdirectory, and then

open the worker.propertiesfile in a text editor.

2. Add the following properties to the file, and specify the directories for each:

l

The props_dirproperty specifies where the worker_persist.propertiesfile is saved.

l

The jobs_dirproperty specifies the directory where the job files are created.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 48 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

3.

Save and close your worker.propertiesfile.

4. Restart the sensor.

Configuring Job Cleanup Timing on Sensors

To prevent the progressive loss of disc space as job files accumulate, Fortify ScanCentral SAST

sensors automatically clean up internal job files (packages received from the Controller, FPR files,

logs, and so on), and Fortify Static Code Analyzer build files related to cleaned Fortify ScanCentral

SAST jobs. Although you cannot turn off this feature, you can configure its timing.

To configure the timing of job file cleanup on a sensor:

1.

Navigate to the <sca_install_dir>/Core/configdirectory, and then open the

worker.propertiesfile in a text editor.

2. Configure the following properties based on your scheduling needs.

Default value

(hours)

Property

Description

Age (in hours) job files must be before

they are removed from the sensor

working directory

168

(one week)

worker_cleanup_age

Frequency with which the cleanup

process runs

1

worker_cleanup_interval

3.

Save and close your worker.propertiesfile.

4. Restart the sensor.

Starting the Sensors

To start the Fortify ScanCentral SAST sensors:

1. Start the Controller if it is not already running.

2.

On each sensor, navigate to <sca_install_dir>/bin.

3. Start the sensor by typing the following command:

scancentral –url <controller_url> worker

If the sensor starts successfully, it displays messages to signal its waiting status on the console. After

you verify that the sensor is working, you can create a Startup Task in Windows Task Scheduler or

add it to your startup scripts. For more information, see "Configuring Sensor Auto-Start" on the next

page.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 49 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

Note: Make sure that you run each sensor consistently from the same directory. Otherwise, its

UUID changes and, if Fortify ScanCentral SAST is connected to Fortify Software Security Center,

Fortify Software Security Center identifies it as different sensor.

"Configuring Sensor Auto-Start" below

Configuring Sensor Auto-Start

The following topics provide general guidance to enable sensor auto-start and might not be

appropriate in all environments. Fortify strongly recommends that you review the instructions with

your system administrator and make any changes required for your environment.

Enabling Sensor Auto-Start on Windows as a Service

Make sure the ScanCentral SAST Controller is running before you perform the following procedure.

To enable sensor auto-start on Windows as a service:

1. Log in to the sensor machine as a local user with administrative permissions.

Sensors are dedicated machines intended only to run Fortify Static Code Analyzer on behalf of

Fortify ScanCentral SAST. Do not share them with any other service. To avoid issues associated

with insufficient permissions, use a fully-privileged administrator account for the auto-start

setup.

2.

3.

Open a command prompt and navigate to the <sca_install_dir>\bin\scancentral-

worker-servicedirectory.

Run setupworkerservice.batwith no options to display the usage help.

4. Re-run the batch script with the required options included.

5. Open Windows Services and check to make sure that the sensor service is present.

6. Right-click the listed sensor service, and then select Start.

7. Fortify recommends that you change the startup type setting to Manual until you verify that the

sensor runs successfully. After verification, change the startup type setting to Automatic

(Delayed Start) in Windows Services.

8. Make sure that the sensor communicates with the Controller.

"Troubleshooting a Sensor as a Windows Service" on page 91

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 50 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

Enabling Sensor Auto-Start on Windows as a Scheduled Task

To enable Fortify ScanCentral SAST sensor auto-start on Windows as a scheduled task:

1. Log on to the sensor machine as a local user with administrative permissions.

Sensors are dedicated machines intended only to run Fortify Static Code Analyzer on behalf of

Fortify ScanCentral SAST. Do not share them with any other service. To avoid issues associated

with insufficient permissions, use a fully-privileged administrator account for the auto-start

setup.

2. Start the Task Scheduler.

3. In the Actions pane, select Create Task.

4. On the General tab, provide the following information:

a. In the Name box, type a name for the task.

b. Click Run whether user is logged on or not.

5. Click the Actions tab, and then click New.

The New Action dialog box opens.

a. In the Action list, select Start a program.

b.

In the Program/script box, type the directory path to your scancentral.batfile (for

example, <sca_install_dir>\bin\scancentral.bat).

c. In the Add arguments (optional) box, type the following:

–url https://<host>:<port>/scancentral-ctrl worker >taskout.txt 2>&1

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 51 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

d.

In the Start in (optional) box, type the path to the Fortify ScanCentral SAST sensor bin

directory (for example, <sca_install_dir>\bin\).

e. Click OK.

6. Click the Triggers tab.

7. Make sure that the At startup trigger is enabled, and then click OK.

8. Click the Settings tab.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 52 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

9. Make sure the Stop the task if it runs longer than check box is cleared, and then click OK.

10. Click Save.

11. Restart the machine.

The script output in the taskout.txtfile indicates whether the sensor started successfully.

You can also start and stop the scheduled task manually from the Task Scheduler interface when you

are logged into the machine.

Enabling Sensor Auto-Start on a Linux System

The following procedure has been tested with Red Hat Enterprise Linux; there might be some

variation for other Linux varieties. Review these steps with your system administrator before you

make any changes.

To enable Fortify ScanCentral SAST sensor auto-start on a Linux system:

1. Log in to the machine as “root.”

2.

Run the visudocommand to edit the sudoersfile and disable requiretty.

Defaults !requiretty

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 53 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

Note: You can also disable requiretty per user.

3. Set auto-start as follows:

a. Verify the command invocation from the console (modify it based on your install directory).

sudo -u <username> -- <sca_install_dir>/bin/ScanCentral -url

<controller_url> worker > <sca_install_dir>/bin/workerout.txt 2>&1

&

o

Add the sudocommand to the end of the file (add it before the line exit 0if it exists).

o

The ampersand (&) at the end enables the machine to start up even if sensor startup fails

or hangs.

o

The double-dash (--) is important to separate the options for sudo from the options for

your service.

b. Make the change to the startup file.

Caution! Make sure that you do not change anything else in your bootup script.

vi /etc/rc.d/rc.local

4. Check the setup:

a. Reboot and log in to the machine as “root.”

b. To verify the processes under root, type:

ps -x | grep java

c. Verify that the output shows that the sensor is not started under root.

d. To verify the processes under the user, type:

sudo -u <username> ps x | grep java

e. Verify that the output displays the sensor process.

f. To verify the existence and contents of the script output file, type:

tail -f /opt/<sca_install_dir>/bin/workerout.txt

For example:

tail -f /opt/Fortify/Fortify_SCA_24.2.0/bin/workerout.txt

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 54 of 111

Installation, Configuration, and Usage Guide

Chapter 3: About Fortify ScanCentral SAST Sensors

Safely Shutting Down Sensors

This topic describes how to move Fortify ScanCentral SAST sensors to Shutdown or Shutdown

scheduled mode from Fortify Software Security Center.

Important! If the Controller is in maintenance mode (see "Placing the Controller in Maintenance

Mode" on page 39), you cannot shut down sensors from Fortify Software Security Center. Also, to

shut down sensors from Fortify Software Security Center, the sensors must be version 21.2.0 or

later.

To shut down active sensors:

1. Log on to Fortify ScanCentral SAST as an administrator and open the Fortify ScanCentral SAST

page.

2. In the left pane of the SAST page, select Sensors.

3. In the sensors table, do one of the following:

l

Expand the row for a sensor you want to shut down, and then click SHUT DOWN.

l

Select the check boxes for one or more sensors you want to shut down, and then click

SHUT DOWN.

If the SHUT DOWN button is not enabled, it can mean that:

l

The sensor version is earlier than 21.2.0.

l

The sensor is already shut down.

l

The Controller is in maintenance mode.

l

The sensor is inactive or disabled.

If a sensor you shut down is running a scan, the State value for the sensor changes from Active to

Shutdown scheduled. After the scan is complete, the state then changes to Inactive.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 55 of 111

Chapter 4: About Fortify ScanCentral SAST

Clients

A client is a build machine on which Fortify Static Code Analyzer translates code and generates Fortify

Static Code Analyzer mobile build sessions (MBS). The translated source code, along with optional

and required data, such as custom rules and Fortify Static Code Analyzer command-line options, are

uploaded to the Controller.

Clients not only translate code and generate MBS files, but can also generate packages with sources

and dependencies for remote translation on sensors. You can use this functionality independent of

Fortify Static Code Analyzer.

This section contains the following topics:

Embedded Clients and Standalone Clients

Fortify Static Code Analyzer and ScanCentral SAST Version Compatibility

Encrypting the Shared Secret on a Client

Configuring Proxies for Clients and Sensors

Embedded Clients and Standalone Clients

A client can be either an embedded client, which is part of the Fortify Static Code Analyzer

distribution or a standalone client, which is independent of Fortify Static Code Analyzer. The interface

for issuing Fortify ScanCentral SAST commands is installed on your client. You use this interface to

set the options for the scan and communicate your intentions to the Controller.

Within a Fortify Static Code Analyzer installation, the files used to create Fortify ScanCentral SAST

sensors and embedded clients are the same. The only difference is how you invoke the functionality

from the command line. To use Fortify ScanCentral SAST as a sensor, you run Fortify ScanCentral

SAST using the workercommand. To use Fortify ScanCentral SAST as an embedded client to start a

scan, invoke it using the startcommand. Sensor functionality depends on Fortify Static Code

Analyzer. So, you can have a standalone client, but not a standalone sensor. You can use an

embedded client for either local translation and remote scan or remote translation and scan.

A standalone client does not require the installation of Fortify Static Code Analyzer. You can use it to

create a package of the code with its dependencies to send to the Controller for remote translation

and scan.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 56 of 111

Installation, Configuration, and Usage Guide

Chapter 4: About Fortify ScanCentral SAST Clients

Fortify Static Code Analyzer and ScanCentral SAST

Version Compatibility

The Fortify Static Code Analyzer version on a Fortify ScanCentral SAST client must be compatible

with the Fortify Static Code Analyzer version installed on the sensors. The version number format is

year.quarter.patch.buildnumber(for example 24.2.0.0068). By default, the major and minor

portions of the Fortify Static Code Analyzer version numbers on both the client and sensor must

match. For example, version 24.2.0 works with version 24.2.1. For other options of supported version

compatibility, see the ScanCentral SAST Controller configuration property sensor_ version_for_

all_jobsin "Configuring the Controller" on page 27.

To determine the Fortify Static Code Analyzer version, run the command sourceanalyzer

-version.

Installing Clients

Unless you use a language that supports offloading the translation phase of analysis to your sensors,

you must have a licensed copy of Fortify Static Code Analyzer on each machine you plan to use as

Fortify ScanCentral SAST clients. If you use a language supported for remote translation, you can

install standalone clients, independent of Fortify Static Code Analyzer. For a list of languages that

ScanCentral SAST supports for remote translation, see the Fortify Software System Requirements

document.

In this guide, <client_install_dir> refers to the ScanCentral SAST client installation directory.

"Installing an Embedded Client" below

"Installing a Standalone Client" on the next page

Installing an Embedded Client

Use an embedded client (client included with Fortify Static Code Analyzer) to perform a local

translation before submitting the remote scan to your sensors.

To install an embedded client:

1. Log on to a build machine using credentials for an account that is not an administrator or root

account.

2. Use the instructions provided in the OpenText™ Fortify Static Code Analyzer User Guide to

install Fortify Static Code Analyzer on your build machine.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 57 of 111

Installation, Configuration, and Usage Guide

Chapter 4: About Fortify ScanCentral SAST Clients

Make sure you select Fortify ScanCentral SAST client as a component during the Fortify Static

Code Analyzer installation.

3.

4.

Navigate to the <sca_install_dir>/Core/configdirectory, and then open the

client.propertiesin a text editor.

Set the same value for the client_auth_tokenproperty that you set for the client_auth_

tokenproperty on the Controller (in the <controller_install_

dir>/tomcat/webapps/scancentral-ctrl/WEB-INF/classes/config.propertiesfile).

For information about how to generate an encrypted shared secret, see "Encrypting the Shared

Secret on a Client" on the next page.

5.

Save and close the client.propertiesfile.

See Also

"Installing a Standalone Client" below

Installing a Standalone Client

To submit scan requests for remote translation and remote scan to your Fortify ScanCentral SAST

sensors, you can use standalone clients. A standalone client is independent of a Fortify Static Code

Analyzer installation.

To install a standalone client:

1. Copy the Fortify ScanCentral SAST client files to your machine by doing one of the following:

l

Install from a ScanCentral SAST client ZIP file:

i.

Extract the contents of the Fortify_ScanCentral_Client_<version>_x64.zipfile

to any directory on your machine.

Important! Make sure that the installation path contains no spaces.

ii.

Add <client_install_dir>/binto your PATH environment variable.

The <client_install_dir> is the directory where you extracted the ScanCentral SAST client

ZIP.

iii.

Set the JAVA_HOMEenvironment variable to point to the supported Java version, and

make sure that you add the Java executable to the PATHenvironment variable.

Important! If you have a Java project that requires Java 8 to build, set the

SCANCENTRAL_JAVA_HOMEenvironment variable to a version of Java that Fortify

ScanCentral SAST supports. Leave the JAVA_HOMEenvironment variable set to Java

8.

l

Install the ScanCentral SAST client as a component of a Fortify Applications and

Tools installation.

For instructions, see the OpenText™ Fortify Static Code Analyzer Applications and Tools

Guide.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 58 of 111

Installation, Configuration, and Usage Guide

Chapter 4: About Fortify ScanCentral SAST Clients

2.

3.

Navigate to the <client_install_dir>/Core/configdirectory, and then open the

client.propertiesin a text editor.

Set the same value for the client_auth_tokenproperty that you set for the client_auth_

tokenproperty on the Controller (in the <controller_install_

dir>/tomcat/webapps/scancentral-ctrl/WEB-INF/classes/config.propertiesfile).

For information about how to generate an encrypted shared secret, see "Encrypting the Shared

Secret on a Client" below.

4.

Save and close the client.propertiesfile.

"Upgrading a Client" on page 64

Placing Multiple Standalone Clients on the Controller

You can place multiple standalone clients of different supported versions on the Controller. To do

this, place any number of client ZIP files for any and all supported versions into the <controller_

install_dir>/tomcat/clientdirectory. You can use any ZIP file names. At startup, the Controller

parses the available clients.

To install a patch for a client or sensor version installed on the Controller, place the patch ZIP file into

the <controller_install_dir>/tomcat/clientdirectory. If automatic updates is enabled, the

clients of that version are automatically updated with the patch. For information about how to enable

automatic updates of your clients and sensors, see "Enabling Automatic Updates of Clients and

Sensors" on page 65.

Encrypting the Shared Secret on a Client

Passwords exist in the ScanCentral SAST client configuration file as plain text. You can encrypt the

client_auth_tokenproperty value.

To encrypt a shared secret on a client:

1. At the command prompt, run one of the following commands:

l

For an embedded client installed with Fortify Static Code Analyzer, run <sca_install_

dir>/bin/pwtool <pwtool_keys_file>

l

For a standalone client, run <client_install_dir>/bin/pwtool <pwtool_keys_file>

2. When prompted, type the password to encode, and then press Enter.

The pwtool generates a new key in the file on the specified path, or reuses an existing file and

prints the encrypted password.

3.

Copy the new encrypted secret, and paste it as the value for the client_auth_tokenproperty

in the client.propertiesfile.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 59 of 111

Installation, Configuration, and Usage Guide

Chapter 4: About Fortify ScanCentral SAST Clients

4.

5.

Add the following to the client.propertiesfile:

pwtool_keys_file=<pwtool_keys_file>

Save and close the client.propertiesfile.

See Also

"Installing Clients" on page 57

Configuring Proxies for Clients and Sensors

If all your outbound traffic must go through a proxy, you can configure one for your Fortify

ScanCentral SAST clients.

To configure proxies for clients:

1.

Navigate to <client_install_dir>/Core/config/, and, in both the client.properties

and worker.propertiesfiles, uncomment, and then set values for the properties listed in the

following table.

Property

Description

ctrl_proxy_host

ctrl_proxy_port

ctrl_proxy_user

Type the name of the Controller proxy host.

Type the Controller proxy port number.

If authentication is required, type a user name.

ctrl_proxy_password If authentication is required, type the password for the user.

ssc_proxy_host

ssc_proxy_port

ssc_proxy_user

Type the name of the Fortify Software Security Center proxy host.

Type the number of the Fortify Software Security Center proxy port.

If authentication is required, type the proxy user name.

ssc_proxy_password If authentication is required, type the password for the proxy user.

2. To enable proxy authentication when the Controller is running under HTTPS, navigate to

<client_install_dir>/bin/, and then add the following property to the scancentral

executable file:

-Djdk.http.auth.tunneling.disabledSchemes

Example:

$JAVA_CMD -Djdk.http.auth.tunneling.disabledSchemes= -

Dscancentral.installRoot="${FORTIFY_HOME}" -Dlog4j.dir="${SCANCENTRAL_

LOG}" $SCANCENTRAL_JAVA_PROPS -jar "${FORTIFY_

HOME}/Core/lib/scancentral-launcher-24.2.0.0.jar" "$@"

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 60 of 111

Chapter 5: Upgrading Fortify ScanCentral

SAST Components

Fortify ScanCentral SAST-related functionality in Fortify Software Security Center requires updated

Fortify ScanCentral SAST components.

Important! You must upgrade the Controller before you upgrade the Fortify ScanCentral SAST

sensors and clients. Also, make sure that your Controller version is the same as your Fortify

Software Security Center version.

This section contains the following topics:

Supporting Multiple Fortify Static Code Analyzer Versions

Upgrading the Controller

Enabling Automatic Updates of Clients and Sensors

Supporting Multiple Fortify Static Code Analyzer

Versions

To support heterogeneous environments and facilitate phased Fortify Static Code Analyzer upgrades,

the Fortify ScanCentral SAST Controller supports scan request routing based on the Fortify Static

Code Analyzer version. For example, you can configure two different client machines, each with a

different Fortify Static Code Analyzer version, and configure the sensors with compatible Fortify

Static Code Analyzer versions. By default, jobs from each client are then routed to the sensor that has

the same Fortify Static Code Analyzer version installed. You can change this behavior and specify a

specific sensor version for all jobs (see "Configuring the Controller" on page 27).

If you have an existing Fortify Static Code Analyzer installation (that includes the ScanCentral SAST

client executable file in your path and a mixed version environment, make sure that you are running

the latest Fortify ScanCentral SAST executable when you run the client and sensor commands. (Use

explicit paths.) To add capacity (new clients or sensors), you can clone the VMs you have already

configured or use sensor hosts with the same specifications and installation directory structure.

Important! If you clone VMs, then after cloning, you must remove the worker_

persist.propertiesfile from the directory specified for the props_dirproperty (see

"Configuring Where to Generate Job Files and the worker_persist.properties File" on page 48).

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 61 of 111

Installation, Configuration, and Usage Guide

Chapter 5: Upgrading Fortify ScanCentral SAST Components

Use sensor machines dedicated to Fortify ScanCentral SAST and run sensors under a dedicated user

name. Run only one sensor instance per machine.

If the Controller and Fortify Software Security Center run on different machines, make sure that the

ssc_urland this_urlproperties in the scancentral-ctrl/WEB-

INF/classes/config.properties, and the Controller URL set on Fortify Software Security Center

(select Administration > Configuration > ScanCentral SAST) resolve to the correct IP addresses.

Make sure a security system or other tool does not block the following channels of communication:

l

Controller to Fortify Software Security Center port (for uploads of scan results)

l

Fortify Software Security Center to the ScanCentral SAST Controller port (for Fortify ScanCentral

SAST administration console functionality)

l

Clients to the Controller port

l

Sensors to the Controller port

l

Clients to the Fortify Software Security Center port (required only if Fortify Software Security

Center is in lockdown mode, or if you use the -sscurloption)

Upgrading the Controller

To upgrade your Fortify ScanCentral SAST Controller:

1. (Recommended) Allow all jobs to finish.

Place the Controller in maintenance mode so that sensors complete all currently running scans.

2. Shut down the Controller.

3. Back up the existing Controller directories.

4. Install the new Controller in a different location from the existing Controller directories.

If you plan to install the Controller as a Windows or Linux service, make sure that you install the

Controller in a directory where the local service (Windows) or the user or group using the service

(Linux) has access.

5.

If your existing config.propertiesfile has been modified, you must manually apply any

changes you made to the new config.propertiesfile. You cannot simply copy the existing

config.propertiesfile.

6. If (and only if) you are upgrading your Controller from version 23.1.x or earlier to version 24.2.0,

run the migration script as follows:

a. Open a command prompt and navigate to the new 24.2.0 Controller installation directory.

b.

c.

At the command prompt, enter cd db-migrate.

Identify the cloudCtrlDband Controller directories for the existing Fortify ScanCentral

SAST version. In the following example, the existing Controller is installed on a Windows

system in the C:\scancentral23.1.0directory:

C:\scancentral23.1.0\tomcat\cloudCtrlDb

C:\scancentral23.1.0\tomcat\webapps\scancentral-ctrl

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 62 of 111

Installation, Configuration, and Usage Guide

Chapter 5: Upgrading Fortify ScanCentral SAST Components

d. Run the following command.

This command example includes the example directories shown in the preceding step.

migrate C:\scancentral23.1.0\tomcat\cloudCtrlDb

C:\scancentral23.1.0\tomcat\webapps\scancentral-ctrl

The migration script generates the cloudCtrlDbdirectory in the current working directory.

7.

Navigate to the jobFilesand cloudCtrlDbdirectories of the existing Controller, and then

copy them to the corresponding directories for the new Controller.

Important! If you migrated the database (step 6), make sure that you copy the migrated

database (cloudCtrlDbdirectory) to the new Controller installation directory.

The process owner must have write permission for the database file in the cloudCtrlDb

directory. If you run the ScanCentral SAST Controller as a Windows service, make sure that the

LOCAL SERVICE account has write permission to the database file.

To change these directories, edit the job_file_dirand db_dirproperties in the

config.propertiesfile (see "Configuring the Controller" on page 27).

8. Start the new Controller.

The database is automatically migrated.

9. (Optional) Remove the Controller directories for the previous version.

See Also

"Installing the Controller" on page 19

"Upgrading Fortify ScanCentral SAST Components" on page 61

"Upgrading Sensors" below

"Enabling Automatic Updates of Clients and Sensors" on page 65

Upgrading Sensors

Important! If Fortify Static Code Analyzer is installed in a location that requires that you have

administrator permissions to modify it (for example in Program Files), then to update a sensor

you must start it with administrator permissions. Otherwise, the sensor cannot write files to disk.

If automatic updates is enabled, major updates on standalone clients must finish successfully

before the sensor can start. With automatic updates enabled, patch updates allow sensors and

clients to start unless the upgrade fails.

To upgrade your Fortify ScanCentral SAST sensors (on Windows or Linux), you can either install the

latest version of Fortify Static Code Analyzer, or unzip the Fortify_ScanCentral_Client_

<version>_x64.zipfile. You can use the client-only approach if you plan only to use remote

translation and analysis workflows. Local translation requires a local Fortify Static Code Analyzer

installation. You can also find the Fortify ScanCentral SAST client inside the Fortify_ScanCentral_

Controller_<version>_x64.zipfile in the tomcat/client/scancentral.zipdirectory.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 63 of 111

Installation, Configuration, and Usage Guide

Chapter 5: Upgrading Fortify ScanCentral SAST Components

Tip: You can configure automatic upgrades of both sensors and clients. For details, see "Enabling

Automatic Updates of Clients and Sensors" on the next page.

To upgrade sensors by installing or upgrading Fortify Static Code Analyzer:

1. Stop all sensors from running.

2. Install or upgrade Fortify Static Code Analyzer using the instructions provided in the OpenText™

Fortify Static Code Analyzer User Guide.

3.

Check the <sca_install_dir>/Core/configdirectory to make sure that the

worker.propertiesfile resides there.

4.

Add the following property to the worker.propertiesfile:

worker_auth_token=<value_set_in_controller_configuration>

5. Specify either a plain text password, or an encrypted shared secret (password the Controller uses

to communicate with the sensor) as the worker.propertiesvalue. For information about how

to generate an encrypted shared secret, see "Encrypting the Shared Secret on a Sensor" on

page 45.

6.

Save the worker.propertiesfile.

7. Start the sensors.

"Starting the Sensors" on page 49

"Configuring Sensors to Use the Progress Command When Starting on Java" on page 47

"Upgrading the Controller" on page 62

Upgrading a Client

Important! Fortify recommends that your standalone Fortify ScanCentral SAST clients and your

Fortify Static Code Analyzer installation be the same version.

To upgrade a standalone client (independent of Fortify Static Code Analyzer), do one of the following:

l

Delete the existing client, and then extract the Fortify_ScanCentral_Client_<version>_

x64.zipfile to any directory on the machine.

l

Extract the contents of the Fortify_ScanCentral_Client_<version>_x64.zipfile on top of

the existing client.

To upgrade an embedded client, which resides on the same machine as Fortify Static Code Analyzer:

1. Log on to the build machine using credentials for an account that is not an administrator account

or root.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 64 of 111

Installation, Configuration, and Usage Guide

Chapter 5: Upgrading Fortify ScanCentral SAST Components

2. Back up the following directories:

l

<sca_install_dir>/bin

l

<sca_install_dir>/Core/lib

l

<sca_install_dir>/Core/config

3. Upgrade Fortify Static Code Analyzer.

For instructions on how to install and upgrade Fortify Static Code Analyzer, see the OpenText™

Fortify Static Code Analyzer User Guide.

4. Accept all overwrite requests.

On a Linux system, you might also need to run chmod +x ScanCentralin the <sca_install_

dir>/bin/ScanCentraldirectory.

Tip: After you configure a client, you can copy the configuration files and use them to create

other clients.

"Installing an Embedded Client" on page 57

Enabling Automatic Updates of Clients and Sensors

You can have all Fortify ScanCentral SAST clients and sensors check with the Controller after a

manual update and following each startup to determine whether updates are available (meaning the

client or sensor version is earlier than the Controller version). Then, if an update is available, the

Controller updates all sensors and clients.

The upgrade paths for clients and sensors are as follows:

l

You can update standalone clients to a major or a patch version (for example from 23.2.0 to 24.2.0,

or from 23.2.0 to 23.2.1).

l

If automatic updates are enabled and a major update of standalone clients fails, the clients do not

start any jobs until they are updated.

l

If automatic updates are enabled and a patch update of standalone clients fails, the clients continue

to work and a warning is displayed.

l

You can only update embedded clients and sensors to a patch version (for example, from 23.2.0 to

23.2.1 or 23.2.2, but not to 24.2.0). Automatic updates for major versions is not available for

embedded clients and sensors.

l

If automatic updates are enabled and a patch update of an embedded client fails, the clients and

sensors continue to work and a warning is displayed.

To update sensors and embedded clients to the next version, you must install the latest Fortify Static

Code Analyzer version.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 65 of 111

Installation, Configuration, and Usage Guide

Chapter 5: Upgrading Fortify ScanCentral SAST Components

Important! Fortify ScanCentral SAST clients and sensors check for updates only if you use the

-urlor -sscurloptions. The packagecommand does not start the update process.

To enable automatic updates of your clients and sensors:

1.

Navigate to <controller_install_dir>/tomcat/webapps/scancentral-ctrl/WEB-

INF/classes/and open the config.propertiesfile in a text editor.

2.

To enable automatic updates, set client_auto_updateto true.

3. Save and close the file.

The update process (and its resulting success or failure status) is written to the console.

Important! If you have Fortify Static Code Analyzer installed in a location that requires that you

have administrator permissions to modify it (for example in Program Files), then to update a

sensor, you must start it with administrator permissions. Otherwise, the sensor cannot write files

to disk. If automatic updates is enabled, major updates on standalone clients must finish

successfully before the sensor can start. With automatic updates enabled, patch updates allow

sensors and clients to start unless the upgrade fails.

"Upgrading the Controller" on page 62

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 66 of 111

Chapter 6: Submitting Scan Requests

You can request a scan that performs remote translation and scan or one that performs a remote scan

for a project that is already translated to your Fortify ScanCentral SAST sensors. This chapter

describes how to submit scan requests (including special considerations for some project languages),

how to upload your scan results to Fortify Software Security Center in your scan request, and how to

prepare a Fortify ScanCentral SAST package to be scanned without sending it to a Controller.

This section contains the following topics:

Submitting Local Translation and Remote Scan Requests

Submitting Remote Translation and Scan Requests

Targeting a Specific Sensor Pool for a Scan Request

Working with .NET Projects

Working with Go Projects

Working with Python Projects

Working with SQL Projects

Working with COBOL Projects

Working with Java 8 Projects

Uploading Results to Fortify Software Security Center

Optimizing Scan Performance

Generating a ScanCentral SAST Package

Using the PackageScanner Tool

Submitting Local Translation and Remote Scan

Requests

You can submit a project that has already been translated by Fortify Static Code Analyzer to your

Fortify ScanCentral SAST sensors for remote scanning. To submit a scan request to perform only the

scan phase, use the startcommand with either the --build_id(-b) or the -mbsoption to identify

the local translation or an existing mobile build session file together with the -scanoption. The

following is an example of a scan request to submit a remote scan:

scancentral –url <controller_url> start -b <build_id> -scan

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 67 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

You can pass any supported Fortify Static Code Analyzer scan options after the –scanoption. If you

use options such as –build-label, -build-application, or –build-version, make sure that

you escape the quotes that enclose the parameter. For example:

-scan –build-label \"Application 5.4 – January 2, 2024\"

If the submission succeeds, you receive a job token. The Fortify ScanCentral SAST sensor pulls the

scan request from the Controller, processes it, and publishes the results to the Controller.

By default, jobs submitted and scan results (FPR files) cannot be larger than 1 GB. Before you start

large scans, review "Optimizing Scan Performance" on page 79.

Submitting Remote Translation and Scan Requests

If you use a supported language, you can submit your project to your Fortify ScanCentral

SAST sensors for a complete remote analysis (both translation and scan phases). To submit a scan

request that performs both the translation and scan phases, use the startcommand.

Fortify ScanCentral SAST automatically detects the build tool you are using based on the project files

being scanned. For example, if Fortify ScanCentral SAST detects a pom.xmlfile, it automatically sets

-btto mvn. If it detects a build.gradlefile, it sets -btto gradle. If Fortify ScanCentral SAST

detects a *.slnfile, it sets -btto msbuildand sets -bfto the xxx.slnfile. If Fortify ScanCentral

SAST detects multiple file types (for example, pom.xmland build.gradle), it prioritizes the build

tool selection as follows: Maven > Gradle > MSBuild and prints a message to indicate which build tool

was selected based on the multiple file types found.

The following table provides example scan request commands for different tasks. The examples

assume that the command is run from the project's working directory. The build tool option --build-

tool(-bt) shown in these example commands is not required.

Task

Example Command

Start a job to scan a

.NET application

scancentral -url <controller_url> start

Start a job to scan a dotnet project

on Windows

scancentral -url <controller_url> start -bt

dotnet -bf mySolution.sln

Start a job to scan a Maven project

that includes the test scope

scancentral -url <controller_url> start -bt mvn

--include-test

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 68 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

Task

Example Command

or

scancentral -url <controller_url> start -t

Start a job to scan a Maven project

with a non-default build file

scancentral -url <controller_url> start -bt mvn

-bf c:\myproj\myproj-pom.xml

Start a job to scan a

JavaScript/TypeScript project

scancentral -url <controller_url> start

scancentral -url <controller_url> start -hv 8.2

scancentral -url <controller_url> start

Start a job to scan a PHP version

8.2 project

Start a job to scan an ABAP

project

Start a job to scan a Ruby project

Start a job to scan a Gradle project

scancentral -url <controller_url> start -bt

gradle

Start a job to scan a Gradle

project, get email notifications

from the Controller, and upload

the results to Fortify Software

Security Center

scancentral -url <controller_url> start -email

username@domain.com -upload -application

"MyProject" -version "1.0" -uptoken <token>

"Uploading Results to Fortify Software Security Center" on page 75

Targeting a Specific Sensor Pool for a Scan Request

To target a specific sensor pool for a scan request, you must have:

l

The UUID for the sensor pool

l

The pool_mapping_modeproperty set to enabled or disabled

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 69 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

To get the UUID for the sensor pool:

1. Log on to Fortify Software Security Center and open the Fortify ScanCentral SAST page.

2. In the left pane of the SAST page, select Sensor Pools.

3. In the Sensor Pools table, copy the value shown in the UUID column for the sensor pool you

want to target for a scan request.

Note: All unassigned and enabled sensors are used, even if they are not assigned to sensor

pools.

To specify a sensor pool to use for a scan request:

l

At the command prompt on the client host, run the following command:

scancentral –url <controller_url> start -pool <uuid>

Working with .NET Projects

Fortify ScanCentral SAST MSBuild integration is available on Windows only. Fortify ScanCentral SAST

dotnet integration is available on Windows and Linux.

To translate and scan .NET projects, the client machine must have the software required to build and

package .NET projects installed:

l

MSBuild or dotnet (see supported versions of MSBuild in the Fortify Software System

Requirements document)

l

NuGet (optional)

l

.NET Framework, .NET Core, or .NET Standard as required for the project configuration

To use Fortify ScanCentral SAST MSBuild integration, the required MSBuild version must be included

in the PATH environment variable. To make sure the project is built correctly, Fortify recommends

that you start Fortify ScanCentral SAST from the Developer Command Prompt for Visual Studio,

which sets the required .NET environment variables automatically. To use Fortify ScanCentral SAST

dotnet integration, the required dotnet version must be included in the PATH environment variable.

Some projects also require that you start NuGet to restore some dependencies. If any dependencies

are unresolved, the build fails and the scan results might be incomplete. For these types of projects,

you must install NuGet manually on the machine and make sure it is included in the PATH

environment variable. If NuGet is found, Fortify ScanCentral SAST runs it automatically.

The following are command-line examples to translate and scan a .NET project:

scancentral -url <controller_url> start --build-tool msbuild --build-file

<sln_file_or_path_to_sln_file>

scancentral -url <controller_url> start --build-tool dotnet

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 70 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

The following command uses MSBuild integration on a Windows client and dotnet integration on a

Linux client because no build tool option is specified:

scancentral -url <controller_url> start --build-file <sln_file_or_path_to_

sln_file>

Note: To use the dotnet integration on a Windows client, you must include -bt dotnet.

If no build tool is specified, ScanCentral SAST client tries to automatically detect the build tool for

*.sln, *.csproj, *.vbproj, and dirs.proj.

Fortify ScanCentral SAST returns a job token that you can use to track the scan.

Excluding .NET Projects from Analysis

To exclude a .NET project from Fortify ScanCentral SAST analysis, you must create a build

configuration to exclude the project, and then specify the build configuration with the --build-

commandoption.

For example, the solution MySolution.slnincludes two projects: ProjectA and ProjectB. The

<build_config> file, created in Visual Studio excludes ProjectB from the builds. To exclude ProjectB

from Fortify ScanCentral SAST analysis, run the following from the directory where the solution file

resides:

scancentral -url <controller_url> start --build-tool msbuild --build-file

MySolution.sln --build-command "/t:Rebuild /p:Configuration=<build_config>"

Working with Go Projects

To enable Fortify ScanCentral SAST clients to package Go projects for remote translation and scan,

the following requirements must be met:

l

The Go compiler must be installed on the client to resolve project dependencies.

l

The Go compiler executable location must be available in the PATH variable.

l

Because ScanCentral SAST relies on Go environment variables, you must configure things

accordingly. For example, to use a specific Go proxy, configure it as follows:

set GOPROXY=.... (Windows)

export GOPROXY=... (Linux)

Note: Sensors do not require a connection to a Go proxy website to resolve dependencies

because they run Go translation with GOPROXY=offconfigured. Also, the vendor directory

under the project root has all the required dependencies. The sensor rewrites the GOFLAGS

system variable with GOFLAGS=-mod=vendorwhen it runs a Fortify Static Code Analyzer

translation.

l

The Go project must include a go.modfile.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 71 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

To start a job to scan a Go project, run the following command:

scancentral -url <controller_url> start

Working with Python Projects

Fortify ScanCentral SAST clients can work with Python projects in three ways:

l

Submit a scan request in a prepared virtual environment (see "Submitting a Scan Request in a

Virtual Environment" on the next page).

l

Use an existing virtual environment, without activating that virtual environment (see "Submitting a

Scan Request in an Unactivated Virtual Environment" on the next page). In this case, Fortify

ScanCentral SAST activates the virtual environment.

l

Start the job outside of a virtual environment (see "Submitting a Scan Request Outside of a Virtual

Environment" on the next page).

The following table provides examples of different ways to submit scan requests for Python code.

Task

Command

Start a job to scan a Python 3 project

scancentral -url <controller_url> start

--python-requirements <requirements_

file_path>

Start a job to scan a Python 2 project

scancentral -url <controller_url> start

–-python-version 2 --python-

requirements <requirements_file_path>

Start a job to scan a Python project under an

active virtual environment with dependencies

already installed

scancentral -url <controller_url> start

Start a job to scan a Python project under an

active virtual environment without project

dependencies installed

scancentral -url <controller_url> start

--python-requirements <requirements_

file_path>

Start a job to scan a Python project using an

existing Python virtual environment and

install project dependencies

scancentral -url <controller_url> start

--python-virtual-env <venv_location>

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 72 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

Submitting a Scan Request in a Virtual Environment

If you work in a virtual environment, all your project dependencies are already installed. You do not

need to invoke the pip package manager before you start the job. Fortify ScanCentral SAST

can detect the Python version automatically.

To start the scan job in a virtual environment:

1. At the command prompt, activate the virtual environment.

2. Start a job to scan the Python project as shown in the following example:

scancentral -url <controller_url> start

If pip dependencies are not yet installed in the virtual environment used, Fortify ScanCentral

SAST installs them automatically using the requirements file with the following example:

scancentral -url <controller_url> start --python-requirements

<requirements_file_path>

Submitting a Scan Request in an Unactivated Virtual Environment

To start the scan job in a virtual environment (with all dependencies installed) without activating that

virtual environment:

l

At the command prompt, start the Python project scan as shown in the following examples:

scancentral -url <controller_url> start --python-virtual-env <venv_

location>

or

scancentral -url <controller_url> start --python-virtual-env <venv_

location> --python-requirements <requirements_file_path>

Fortify ScanCentral SAST goes to the virtual environment, determines the Python version used,

packages all required libraries, and then submits the scan job to the Controller.

Submitting a Scan Request Outside of a Virtual Environment

To start the scan job if there is no virtual environment on the client, you must have Python installed

on the client. You must also specify the Python version. Fortify ScanCentral SAST locates the Python

installation. In this case, Fortify ScanCentral SAST creates a temporary virtual environment, installs all

dependencies from the requirements file, and then submits the job to the Controller.

To start the scan job outside of a virtual environment:

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 73 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

l

At the command prompt, start the scan job as shown in the following example:

scancentral –url <controller_url> start

Working with SQL Projects

On Windows (and Linux for .NET projects only), Fortify Static Code Analyzer assumes that files with

the .sql extension are T-SQL rather than PL/SQL. To perform remote translation of a SQL project, you

might need to specify what type of SQL your project uses.

To scan the project, run one of the following commands:

scancentral -url <controller_url> start -targs "-sql-language PL/SQL"

or

scancentral -url <controller_url> start -targs "-sql-language TSQL"

Fortify ScanCentral SAST returns a job token that you can use to track the scan.

Working with COBOL Projects

Fortify ScanCentral SAST clients can package COBOL projects for remote translation and scan. For

detailed information about the requirements and options available for COBOL analysis, see the

OpenText™ Fortify Static Code Analyzer User Guide.

You must have a sensor with the Windows operating system. Fortify ScanCentral SAST automatically

assigns COBOL scans to a Windows sensor. If no Windows sensor is available, then the scan job is

created but cannot be started.

Make sure the copybook files are in a separate directory from the COBOL source code files. Fortify

recommends that you place your COBOL source code files in a directory called sources and your

copybook files in a directory called copybooks. Create these directories at the same level.

Note: To analyze a COBOL project on Linux and to use Legacy COBOL translation, you must

perform a local Fortify Static Code Analyzer translation:

scancentral -url <controller_url> start -b <build_id>

The following example command submits a scan request for a COBOL project where the copybooks

files are in the local copybooksdirectory:

scancentral -url <controller_url> start -targs "-copydirs copybooks -

dialect COBOL390"

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 74 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

The following example command submits a scan request for a COBOL project that contains source

code files with a non-standard file extension mfcbl:

scancentral -url <controller_url> start -targs "-copydirs

MyCopydir1;MyCopydir2 -Dcom.fortify.sca.fileextensions.mfcbl=COBOL"

The following example command submits a scan request for a COBOL project that contains source

code files without file extensions:

scancentral -url <controller_url> start -targs "-copydirs MyCopyDir -

noextension-type COBOL"

Working with Java 8 Projects

If your Java project requires Java 8 to build, set the SCANCENTRAL_JAVA_HOMEenvironment variable

to a version of Java that Fortify ScanCentral SAST supports. After you do, ScanCentral SAST runs

successfully, and the build runs with the JAVA_HOMEset to Java 8.

Uploading Results to Fortify Software Security Center

To submit a scan request and upload the scan results to an application version in Fortify Software

Security Center, you must have an authentication token of type ScanCentralCtrlToken. You can use

the fortifyclient utility to obtain an authentication token from Fortify Software Security Center and

reuse it for future requests. The fortifyclient utility can also provide application version IDs, which you

can use to upload the scan results. For more information about how to use the fortifyclient utility, see

the OpenText™ Fortify Software Security Center User Guide.

Note: The Fortify Software Security Center user account must have permission to upload scan

results for the application version, and must have access to the application version on Fortify

Software Security Center. A user who submits a Fortify ScanCentral SAST job for upload to a

Fortify Software Security Center application version must use a token obtained using an account

that has permission to upload scan results. If a Fortify Software Security Center user is assigned

to a target application version with a view-only role, and that user requests a token and uses it to

submit the job, the upload fails.

To submit a scan request and upload the scan results to an application version in Fortify Software

Security Center:

1. Generate an authentication token to use with Fortify ScanCentral SAST by typing the following

command:

fortifyclient token -gettoken ScanCentralCtrlToken -url <ssc_url> -user

<user_name> -password <password>

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 75 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

2. To list the application versions to which a user account has access, open a command prompt, and

then type the following command:

fortifyclient listApplicationVersions -url <ssc_url> -authtoken <token>

The following is a sample of the command output:

ID

Application Name

Version

10002

10000

10001

10004

10003

Bill Payment Processor 1.1

Logistics

1.3

2.5

RWI

1.0

Web application 1.0

3. Submit your scan request and upload the scan results to a Fortify Software Security

Center application version.

The following example scan request performs a remote translation and scan and uploads the

scan results:

scancentral -sscurl <ssc_url> -ssctoken <token> start -upload -

versionid <app_version_id> -uptoken <token>

The following example scan request performs a remote scan and uploads the scan results:

scancentral -sscurl <ssc_url> -ssctoken <token> start -upload -

versionid <app_version_id> -uptoken <token> -b <build_id> -scan

Note:

l

You can use the ScanCentralCtrlToken type token for both the -ssctokenand the -

uptokenoptions. For more details about token types for these options, see "Global

Options" on page 95 and "Start Command" on page 96.

l

Instead of –versionid <app_version_id>, you can pass –application

<application_name> -version <version_name>. The values for <application_

name> and <version_name> must match the values in Fortify Software Security Center.

These values are case-sensitive.

Typically, the previous steps are combined into a scripted flow from a build server.

"Submitting Remote Translation and Scan Requests" on page 68

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 76 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

"Submitting Local Translation and Remote Scan Requests" on page 67

Specifying the Scan Results (FPR) File Name

You can specify the name of the scan results (FPR) file you upload to Fortify Software Security Center

using the -fprsscoption with the startcommand.

The following example scan request performs a remote translation and scan and specifies a name for

the FPR file to upload:

scancentral -sscurl <ssc_url> -ssctoken <token> start -upload -versionid

<app_version_id> -uptoken <token> -fprssc <my_fpr>.fpr

The following example scan request performs a remote scan and specifies a name for the FPR file for

upload:

scancentral -sscurl <ssc_url> -ssctoken <token> start -upload -versionid

<app_version_id> -uptoken <token> -fprssc <my_fpr>.fpr -b <build_id> -scan

See Also

Preventing Replacement of Duplicate Scan Requests

A duplicate scan request occurs if you have more than one scan requests that upload scan results to

the same application version in Fortify Software Security Center. If the Controller is configured to

replace duplicate scan jobs by enabling the replace_duplicate_scansproperty, you can prevent

the replacement for specific scan requests with the --disallow-replacement(-dr) option in a

scan request.

Consider the following scenario:

1. Submit a scan for upload to AppA 1.0, scan job 1 is added to the queue.

2. Submit a scan for upload to AppA 1.0, scan job 1 is canceled and scan job 2 is added.

3.

Submit a scan for upload to AppA 1.0 with the -droption, scan job 2 is canceled and scan job 3

is added to the queue.

4.

Submit a scan for upload to AppA 1.0 with or without the -droption, scan job 3 remains in the

queue and scan job 4 is added to the queue.

The following example scan request performs a remote translation and scan, uploads the results to

the application version AppA, 1.0 on Fortify Software Security Center, and overrides a duplicate

replacement to ensure the scan job is not removed from the queue by future scan requests uploaded

to the same application version:

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 77 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

scancentral -sscurl <ssc_url> -ssctoken <token> start -upload -application

AppA -version 1.0 -uptoken <token> --disallow-replacement

See Also

"Uploading Results to Fortify Software Security Center" on page 75

Retrying Failed Uploads to Fortify Software Security Center

If a job configured to upload scan results to Fortify Software Security Center fails, the Fortify

ScanCentral SAST Controller retries to upload (up to five attempts by default) and, if the next

attempt fails, waits two minutes before it tries again.

If the Controller fails to upload an FPR file to Fortify Software Security Center, you can use the upload

command as follows to resend the FPR:

scancentral -url <controller_url> upload -token <job_token>

where <job_token> corresponds to the original job that failed to upload the FPR.

Configuring Upload to Fortify Software Security Center Retry

Attempts

To configure the number of times the Controller can retry to upload scan results, and the amount of

time the Controller waits after a failed upload before it tries again:

1.

2.

Navigate to <controller_install_dir>/tomcat/webapps/scancentral-ctrl/WEB-

INF/classes/and open the config.propertiesfile in a text editor.

To set the maximum number of upload retry attempts, locate the ssc_upload_retry_count

property, and replace the default value of 5with any integer value from 1to 10.

Note: If the specified value is outside of the valid range or is invalid, Fortify ScanCentral

SAST applies the default value.

3.

4.

To set the interval between upload retry attempts, locate the ssc_upload_retry_interval

property, and replace the default value of 120(seconds) with any integer value from 60(1

minute) to 900(15 minutes).

Note: If the specified value is outside of the valid range or is invalid, Fortify ScanCentral

SAST applies the default value.

Save and close the config.propertiesfile.

OpenText™ Fortify ScanCentral SAST (24.2.0)

Page 78 of 111

Installation, Configuration, and Usage Guide

Chapter 6: Submitting Scan Requests

"Retrying Failed Uploads to Fortify Software Security Center" on the previous page

Optimizing Scan Performance

If you plan to regularly scan large applications, Fortify recommends that you run a manual test scan

on hardware that is equivalent to the hardware on which your sensor is installed.

To optimize your scan:

1. Set the Fortify Static Code Analyzer scan parameters for optimal performance by adjusting the

memory settings to align with your hardware.

For information about how to tune Fortify Static Code Analyzer, see the OpenText™ Fortify

Static Code Analyzer User Guide.

2. Run a scan.

3. Note the size of the resulting FPR file and scan log.

4. To ensure that the Fortify ScanCentral SAST Controller and Fortify Software Security Center can

accept FPR or log files larger than 1 GB, increase the maximum upload size threshold by doing

the following:

a.

Navigate to <controller_install_dir>/tomcat/webapps/scancentral-

ctrl/classes/and open the config.propertiesfile.

b. Set the Controller threshold to the maximum size in megabytes as follows:

max_upload_size=<max_size_in_megabytes>

The default value is 1024.

5. Make sure that your Fortify Static Code Analyzer configuration is set to process large FPR files.

For more information, see the OpenText™ Fortify Static Code Analyzer User Guide.

See Also