Configuring the Controller

After you install the OpenText ScanCentral SASTController, edit global properties such as the email address to use, the shared secret for the Controller (password that Application Security uses when it requests data from the Controller), the shared secret for clients, and the Application Security web address.

To avoid potential conflicts, OpenText recommends that you run the Controller on a Tomcat server instance other than the instance that Application Security uses.

To configure the Controller:

  1. Open the <controller_install_dir>/tomcat/webapps/scancentral-ctrl/WEB-INF/classes/config.properties file in a text editor.

  2. Configure the properties described in the following table.

    Controller property

    Description

    client_auth_tokenSpecifies a client authentication token string that contains no spaces or backslashes to secure the Controller for use by authorized clients only. If you prefer not to use plain text, you can use an encrypted shared secret as the value for this property. For instructions on how to encrypt a shared secret, see Encrypting the Shared Secret on the Controller.
    client_auto_update

    If set to true, the Controller automatically updates all outdated sensors and clients. For details, see Enabling Automatic Updates of Clients and Sensors.

    client_zip_location

    Specifies the location of the directory that contains OpenText ScanCentral SAST client ZIP files. To enable remote upgrades of one or more client versions, place them in this directory. The default value is client_zip_location=${catalina.base}/client.

    db_dir

    Specifies the OpenText ScanCentral SAST database home directory. The default value is ${catalina.base}/cloudCtrlDb.

    job_file_dir

    Specifies the job storage directory. The default value is: ${catalina.base}/jobFiles.

    fail_job_if_ssc_upload_data_invalid

    If set to true, then before the Controller creates a scan job and assigns it to a sensor, it verifies that the following requirements are true:

    • The token has not expired

      If the token expires before the Controller assigns the scan job to a sensor, the scan does not run, and the job fails.

    • The application version exists in Application Security and is active

    The default value for this property is true.

    job_expiry_delay

    Specifies the number of hours after a job finishes that the job becomes a candidate for cleanup.

    Cleanup removes the job directory, removes jobs from the database, and removes information about expired sensors from the database so that they are no longer displayed in Application Security. By default, the jobs are deleted from the Controller after 168 hours (or 7 days).

    worker_expiry_delay

    		Specifies the amount of time (in hours) after a sensor stops communicating that it becomes a candidate for cleanup. The default is 168 hours (or 7 days).
    cleanup_period

    Specifies the frequency (in minutes) that expired jobs and sensors are cleaned up. The default is 60.

    lim_server_url

    Specifies the web address for the OpenText™ Fortify License and Infrastructure Manager (LIM) server website. The web address format is https://<location>:<port>, where <location> is IP address, hostname, or domain name.

    If the LIM does not use SSL certificates, the protocol is http.

    For more information about using the LIM for sensors, see Configuring Licensing with Fortify License and Infrastructure Manager.

    lim_license_pool

    Specifies the name of the LIM license pool.

    lim_license_pool_password

    Specifies the password for the LIM license pool.

    You can either use a plain text password or use the pwtool_keys_file property to encrypt this password. For information about how to encrypt your passwords, see Encrypting the Shared Secret on the Controller.

    lim_proxy_urlSpecifies the proxy server to access the LIM server if the sensor is behind a proxy.
    lim_proxy_user

    Specifies the LIM proxy user name if authentication is required for the LIM proxy server. For information about how to encrypt user names and passwords, see Encrypting the Shared Secret on the Controller.

    lim_proxy_password

    Specifies the password for the LIM proxy user.

    You can either use a plain text password or use the pwtool_keys_file property to encrypt this password. For information about how to encrypt your passwords, see Encrypting the Shared Secret on the Controller.

    max_upload_size

    		Specifies the maximum size (in megabytes) for files uploaded to the Controller from clients or sensors (for example, log files, result files, and job files).
    pool_mapping_mode

    Configures the mode for mapping scan requests to sensor pools. For information about the valid values for pool_mapping_mode, see About the pool_mapping_mode Property.

    pwtool_keys_file

    Specifies the path to a file with pwtool keys. If encrypted passwords are used, this must specify a file with the pwtool keys used to encrypt the passwords.

    scan_timeout

    Specifies the maximum amount of time (in minutes) that sensors can process a scan job and be prevented from doing other jobs. After the specified time has passed, a scan job is canceled.

    This setting applies to all sensors associated with the Controller but can be overridden with the --scan-timeout command-line option for a specific job or sensor (see Setting the Maximum Run Time for Scans and Start Command Options).

    accept_job_when_no_sensor_available

    Determines whether to accept scan requests if no compatible sensors (or compatible versions) are available. The default value is true. Also see sensor_version_for_all_jobs.

    In the following examples, the property is set to false:

    • If a version 24.4 client submits a scan request, and only version 25.2 sensors are available, the scan request is rejected.

    • If a client submits a request to scan a .NET application and no .NET sensors are available, the scan request is rejected.

    sensor_version_for_all_jobs

    Specifies the version (<year>.<quarter> portion only) of the sensor to which the Controller assigns scan jobs for remote translation and scan. For example, if this property is set to 25.2, then scan requests from 24.2, 24.4, or 25.2 version clients are assigned to a 25.2 version sensor.

    If the OpenText ScanCentral SAST client version is later than the sensor version specified in this property, then the Controller assigns jobs to the sensor version that matches the client version. For example, if this property is set to 24.4, a scan request from a 25.2 version client is assigned to a 25.2 sensor.

    If this property is not set (default), remote translation and scan jobs are assigned to a sensor with the same version as the OpenText ScanCentral SAST client.

    from_email

    		Specifies the outgoing email address that the Controller uses to send job status notifications.
    include_job_status_in_email_subjectIf set to false, the job status for the scan request is not included in the email subject of job status notifications. By default, the job status is included in the notification.

    email_allow_list

    Specifies a comma-, colon-, or semicolon-separated list of email domains to which the Controller can send notifications. Examples of valid values for this property:

    *@yourcompanyname.com

    *@*yourcompanyname.com

    a*@yourcompanyname.com

    name1@yourcompanyname.com,name2@yourcompany.com

    email_deny_list

    Specifies a comma-, colon, or semicolon-separated list of email domains to which the Controller cannot send notifications. Examples of valid values for this property:

    *@yourcompanyname.com

    *@*yourcompanyname.com

    a*@yourcompanyname.com

    name1@yourcompanyname.com,name2@yourcompany.com

    smtp_host

    		Specifies the SMTP server host name.

    smtp_port

    		Specifies the SMTP server port number.

    smtp_auth_user

    If your SMTP server requires authentication, uncomment both the smtp_auth_user and smtp_auth_pass properties and set their values.

    smtp_auth_pass

    You can either use a plain text password or use the pwtool_keys_file property to encrypt the password for smtp_auth_pass. For information about how to encrypt this password, see Encrypting the Shared Secret on the Controller.

    smtp_ssl

    If set to true, the Controller uses SSL for connections to the SMTP server. By default, the Controller does not use SSL.

    smtp_ssl_check_trust

    If set to false, the SMTP server certificate is always trusted. Otherwise, the certificate trust is based on the certification path (the default)

    smtp_ssl_check_server_identity

    If set to false, the SMTP server identity is not checked. Otherwise, the Controller checks server identity as specified by RFC 2595 (the default).

    use_starttls

    If set to true, uses the STARTTLS protocol command (opportunistic SSL/TLS) to inform the SMTP server that the email client wants to upgrade from an insecure connection to a secure connection using SSL/TLS. The default value for this property is false.

    ssc_lockdown_mode

    If set to true, OpenText ScanCentral SAST clients must work with the OpenText ScanCentral SASTController through Application Security. Jobs must be uploaded to an application version and users cannot manually assign scans to specific sensor pools.

    In SSC lockdown mode, you:

    • Cannot use the start command -url option, but must use the -sscurl and -ssctoken options instead

    • Must specify the application name and version, or the application version ID, and the -upload option when starting the scan

    • Cannot use the -pool option, because the job is automatically assigned to the pool configured for the specified application version

    ssc_ctrl_account_username

    Specifies the user name of a OpenText ScanCentral SAST Controller service account created in Application Security with the ScanCentral SAST Controller role. For information about how the Controller uses this account, see Uploading Results to Application Security.

    For information about how to encrypt this value, see Encrypting the Shared Secret on the Controller.

    ssc_ctrl_account_passwordSpecifies the password for the OpenText ScanCentral SAST Controller service account. For information about how to encrypt this value, see Encrypting the Shared Secret on the Controller.

    ssc_remote_ip

    Specifies the remote IP address.

    You can configure an allowed remote IP address for Application Security. Only requests with a matching remote IP address are allowed.

    ssc_remote_ip_header

    Specifies the remote IP HTTP header, where the Application Security remote IP is found if the ssc_remote_ip_trusted_proxies_range property is set.

    The default value is X-FORWARDED-FOR.

    ssc_remote_ip_trusted_proxies_range

    Specifies the remote IP range (in CIDR format). Set this property if Application Security accesses the Controller using a (reverse) proxy server. You can specify comma-separated IP addresses or CIDR network ranges.

    This is unavailable by default, which means that ssc_remote_ip_header is never used to retrieve the remote IP address for Application Security.

    ssc_restapi_connect_timeout

    Specifies the Application Security connection timeout (in milliseconds). The default value is 10000 (or 10 seconds). You can use this, and the ssc_restapi_read_timeout property to resolve timeout errors between the Controller and Application Security.

    ssc_restapi_read_timeout

    Specifies the Application Security read timeout (in milliseconds). The default value is 110000 (or 110 seconds). You can use this property and the ssc_restapi_connect_timeout property to resolve timeout errors between the Controller and Application Security.

    ssc_scancentral_ctrl_secret

    Specifies the password that Application Security uses to request data from the Controller. Use a string that contains no spaces or backslashes. For instructions on how to encrypt this shared secret value, see Encrypting the Shared Secret on the Controller.

    ssc_url

    Specifies the web address for the Application Security server; all uploads are sent to this address. Examples:

    https://<ssc_host>:<port>/ssc

    https://<ssc_host>:<port>/<context_path>

    replace_duplicate_scans

    If set to true, OpenText ScanCentral SAST replaces a pending scan request with a newer scan request if it is a duplicate. A duplicate scan request occurs if you have more than one scan request that uploads scan results to the same application version in Application Security. The Controller places the new scan request in the same queue position as the one it replaced. Any existing duplicate scan requests with a status of pending are automatically canceled. The scan requests are run sequentially to maintain the submission order. This is typically useful if you submit OpenText ScanCentral SAST scans with upload as part of your build process, which might cause a large queue of unnecessary scan requests that can cause delays for the sensors to process. The default value for this property is true.

    You can override the replacement of duplicate scan requests for specific scans. For more information, see Preventing Replacement of Duplicate Scan Requests.

    ssc_upload_retry_count

    Specifies the maximum number of times the Controller can retry to upload scan results after an upload fails. The default value is 5. For more information, see Retrying Failed Uploads to Application Security.

    ssc_upload_retry_intervalSpecifies the amount of time (in seconds) the Controller waits after a failed upload before it tries again. The default is 120 seconds (or 2 minutes). For more information, see Retrying Failed Uploads to Application Security.
    swagger_usernameSpecifies the user name for access to the OpenText ScanCentral SAST API documentation. For information about how to encrypt this value, see Encrypting the Shared Secret on the Controller.
    swagger_passwordSpecifies the password for access to the OpenText ScanCentral SAST API documentation.

    You can either use a plain text password or use the pwtool_keys_file property to encrypt this password. For information about how to encrypt this password, see Encrypting the Shared Secret on the Controller.

    this_url

    Specifies the web address for the Controller; used in emails to refer to this server for manual job result downloads. Example:

    https://<controller_host>:8443/scancentral-ctrl

    worker_auth_tokenSpecifies a string that contains no spaces or backslashes to secure the Controller for use by authorized sensors only. If you prefer not to use plain text, you can use an encrypted shared secret as the value for this property. For instructions on how to encrypt this value, see Encrypting the Shared Secret on the Controller.

    worker_inactive_delay

    Specifies the amount of time (in minutes) after which a non-communicating sensor is considered inactive and all jobs are marked as faulted. Assign a value that is much larger than worker_stale_delay. Note that this property uses different time units than worker_stale_delay. The default value is 60 (or 1 hour).

    worker_stale_delay

    Specifies the amount of time (in seconds) after which a non-communicating sensor is considered inactive. Assign a value that is larger than the worker_sleep_interval and worker_jobwatcher_interval defined for any sensor. The default value for this property is 60 (or 1 minute).

  3. Save and close your config.properties file.

  4. Start the Controller.

    For instructions, see Starting the Controller.

See also

Installing the Controller

Stopping the Controller

Placing the Controller in maintenance mode

Configuring job cleanup timing on sensors