As of December 31st, 2023 ThreadFix 2.X has reached End of Life and is no longer supported. For any further information please contact the Success and Implementation team.
ThreadFix Installation
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
Unzip your ThreadFix download.
Copy the threadfix directory into the webapps directory within your Tomcat installation.
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.
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:
You may defer running these commands until after stepping through the entire installation procedure below, namely after copying the threadfix.license file.
sudo chown -R tomcat:tomcat /opt/tomcat
sudo chmod -R 775 /opt/tomcat
Configure Database Connection
Update your jdbc.properties file to connect to your database. Â
Locate the file at <threadfix_deploy>/WEB-INF/classes/jdbc.properties.
Uncomment (delete the '#' character) all of the lines within the database connection section that is relevant for your environment (MySQL or SQL Server).
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).
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
Update your custom.properties file to set up temp directories.Â
Locate the file at <threadfix_deploy>/WEB-INF/classes/custom.properties.
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.Ensure the tomcat user will have read and write permissions to these locations.
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).
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
Locate file at <threadfix_deploy>/WEB-INF/classes/jms.properties.
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.Ensure the tomcat user will have read and write permissions to this location.
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).
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
.
Note, however, that whatever task is currently in progress will not get re-queued. It is always discarded, regardless of the jms.persist
value.
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:
Locate file at <threadfix_deploy>/WEB-INF/classes/ESAPI.properties.
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
Â
Once generated, use the new
Encryptor.MasterKey
andEncryptor.MasterSalt
values in the response to replace both sets ofMasterKey
andMasterSalt
values (Encryptor.MasterKey
&ESAPI.MasterKey
andEncryptor.MasterSalt
&ESAPI.MasterSalt
) in your ESAPI.properties file.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
andjdbc.password
. You can replace any/all of the existing values injdbc.properties
with these encrypted values.custom.encrypted.peroperties will include the encrypted value for
threadfix.saml.key
andthreadfix.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
Update your logback.xml file to change where ThreadFix stores logs, set the rollover interval and/or the logging threshold.
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.
You can change the log path and name via the value of the "file" parameter.
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.
You can change the root logging level (at the bottom), which should be set to
INFO
by default. If set toDEBUG
, 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.
If you received a new threadfix.license file from Denim Group, simply replace the existing file with the new one and restart Tomcat. In LINUX deployments, you may need the chown
 command to give the tomcat user/group access to the new file.
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
Table of Contents
Â
www.threadfix.it | www.coalfire.com
Copyright © 2024 Coalfire. All rights reserved.
This Information Security Policy is CoalFire - Public: Distribution of this material is not limited.