Open

You will learn

How to install and configure ThreadFix.

Prerequisites

Audience: IT Professional and/or End User
Difficulty: Intermediate
Time needed: Approximately 90 minutes
Tools required: latest version of Tomcat 8.5, ThreadFix License

Introduction

Once the Web Application and Database Servers are set up, it is time to install and configure ThreadFix.

Deploy ThreadFix

1. Unzip your ThreadFix download.
   
   

2. Copy the threadfix directory into the webapps directory within your Tomcat installation.
   
   

3. If you have not already done so, remove all other directories within the webapps directory that shipped with Tomcat (except for the "ROOT" application, which can be useful for troubleshooting). Tomcat will deploy any directory located within the webapps directory, and some default apps shipped with Tomcat can cause dependency issues with ThreadFix.
   
   

4. If you're deploying on a Linux environment, give your tomcat user and group ownership of your tomcat directory and set permissions. Update Linux Permissions:

Configure Database Connection

1. Update your jdbc.properties file to connect to your database.  

   1. Locate the file at <threadfix_deploy>/WEB-INF/classes/jdbc.properties.

   2. Uncomment (delete the '#' character) all of the lines within the database connection section that is relevant for your environment (MySQL or SQL Server).

   3. You can remove the database connection that is not relevant for your environment (e.g., if you're using MySQL, remove the SQL Server block or vice-versa).

   4. Fields that require modification:

      • jdbc.url = (If your MySQL/SQL instance is on the same machine as Tomcat, leave it as a localhost; otherwise modify to the correct URL).

      • jdbc.username = (Your MySQL/SQL ThreadFix user).

      • jdbc.password = (Your MySQL/SQL user’s password).

Configure Custom Properties

1. Update your custom.properties file to set up temp directories. 

   1. Locate the file at <threadfix_deploy>/WEB-INF/classes/custom.properties.

   2. Uncomment (delete the '#' character) the threadfix.scratchFolder and threadfix.workFolder properties and set those locations to temp directories of your choosing within the Tomcat artifact (though outside of the ThreadFix artifact). See the example paths below.

      1. Ensure the tomcat user will have read and write permissions to these locations.

      2. Use an absolute path for these; e.g., /opt/tomcat/etc/threadfix/scratch (Linux), C:\\tomcat8.5\\etc\\threadfix\\scratch (Windows, note the double-backslashes).

      3. For Linux deployments, we recommend placing your scratch and work folders within your tomcat directory, as shown in the example above.

Configure JMS Properties

Specify the directory for queued data (required)

Update your jms.properties file

1. Locate file at <threadfix_deploy>/WEB-INF/classes/jms.properties.
   
   

2. Uncomment the jms.dir line (delete the '#' character at the beginning of the line) and set the location to a temp directory of your choosing within the Tomcat artifact (though outside of the ThreadFix artifact). See the example paths below.

   1. Ensure the tomcat user will have read and write permissions to this location.

   2. Use an absolute path; e.g., /opt/tomcat/etc/threadfix/activemq-data (Linux), C:\\tomcat8.5\\etc\\threadfix\\activemq-data (Windows, note the double-backslashes).

   3. For Linux deployments, we recommend placing your activemq-data folder within your tomcat directory, as shown in the example above.

Specify whether or not to persist the task queue when restarting Tomcat (optional)

By default, when you restart Tomcat, all queued tasks (e.g., pending scan uploads/deletions, etc.) will be cleared. If you want to persist the task queue and have ThreadFix resume from the next task onward, change the jms.persist parameter value in jms.properties from false to true.

Update your ESAPI Key and Salt

Updating your ESAPI.properties key and salt is highly recommended for ensuring your encrypted connection credentials for your database and remote integrations are secure. To update the master key (Encryptor.MasterKey & ESAPI.MasterKey) and master salt (Encryptor.MasterSalt & ESAPI.MasterSalt) in the ESAPI.properties file:

1. Locate file at <threadfix_deploy>/WEB-INF/classes/ESAPI.properties.
   
   

2. At a command/shell prompt, run the following command from within the <threadfix_deploy>/WEB-INF/classes/ directory:
   
   Linux:

   java -classpath "../lib/*:../classes" org.owasp.esapi.reference.crypto.JavaEncryptor

   
   Windows:

   java -classpath "../lib/*;../classes" org.owasp.esapi.reference.crypto.JavaEncryptor

    

3. Once generated, use the new Encryptor.MasterKey and Encryptor.MasterSalt values in the response to replace both sets of MasterKey and MasterSalt values (Encryptor.MasterKey & ESAPI.MasterKey and Encryptor.MasterSalt & ESAPI.MasterSalt) in your ESAPI.properties file.
   
   

4. After restarting Tomcat, ThreadFix will create the ".encrypted." version of jdbc.properties and custom.properties (jdbc.encrypted.properties and custom.encrypted.properties) in the threadfix.workFolder specified within custom.properties per the "Configure Custom Properties" section above.
   
   

   • jdbc.encrypted.properties will include the encrypted value for jdbc.url, jdbc.username and jdbc.password. You can replace any/all of the existing values in jdbc.properties with these encrypted values.

   • custom.encrypted.peroperties will include the encrypted value for threadfix.saml.key and threadfix.saml.value (if SAML is configured). You can replace either/both of the existing values in custom.properties with these encrypted values.

   • After replacing the values with their encrypted version, restart Tomcat.

Configure Logging

1. Update your logback.xml file to change where ThreadFix stores logs, set the rollover interval and/or the logging threshold.

   1. As of 2.8.5.1 ThreadFix has switched logging libraries. If you are upgrading from a previous version you will have to translate a customized log4j.xml file to the logback.xml file.

   2. You can change the log path and name via the value of the "file" parameter.

   3. You can adjust the rollover policy in logback.xml, we use a daily rollover with TimeBasedRollingPolicy.. For a reference that lists the interval options, click here.

   4. You can change the root logging level (at the bottom), which should be set to INFO by default. If set to DEBUG, the log will be very verbose and could impact performance.

ThreadFix License Installation

Copy your ThreadFix license to the following directory: <threadfix_deploy>/WEB-INF/classes/
If you downloaded the ThreadFix Trial, you should already have your license file in place and can skip this step.

Start Tomcat

Once everything is configured, you're ready to start Tomcat.

• In Windows, launch the Configure Tomcat application and click the Start button.

• In Linux, run the following command to start Tomcat:
  
  

Related articles

CentOS Enterprise Setup

Ubuntu Enterprise Setup

Windows Enterprise Setup

Table of Contents