Correlator Installation Guide

Both Linux and Windows hosts are supported. Installation mostly follows the original ThreadFix install guide.

ThreadFix wiki: https://github.com/denimgroup/threadfix/wiki

Installation guides:

• Windows: https://github.com/denimgroup/threadfix/wiki/Windows-2012-R2-Installation-Guide
• Ubuntu: https://github.com/denimgroup/threadfix/wiki/Ubuntu-and-Debian-Installation-Guide

Differences from ThreadFix Install Guide

Follow all steps in either guide linked above. These differences are in comparison to the Ubuntu installation guide. Ubuntu 16.04 LTS was used for this guide.

1. Ignore the Setup init script section under Install and Configure Tomcat 7.

Instead, create a systemd service file: sudo nano /etc/systemd/system/tomcat.service

Enter the following contents into the service file and save:

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking

Environment=JAVA_HOME=/usr/lib/jvm/java-8-oracle/jre
Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC'
Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Xms128m -Xmx1024m -XX:PermSize=64m -XX:MaxPermSize=256m'

WorkingDirectory=/opt/tomcat/temp
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

2. After extracting Tomcat, the tomcat user must be given access and ownership over the /opt/tomcat directory.

    sudo chown -R tomcat:tomcat /opt/tomcat
    sudo chgrp -R tomcat /opt/tomcat
   

3. Before the step Installing ThreadFix, create a scratch directory for the ASTAM Correlator:

    sudo mkdir /etc/threadfix
    sudo mkdir /etc/threadfix/scratch
    sudo chown -R tomcat:tomcat /etc/threadfix
    sudo chgrp -R tomcat /etc/threadfix
   

4. The first step of the Installing ThreadFix section should be ignored. Instead of unzipping a ThreadFix zip file, copy the provided WAR file into /opt/tomcat/webapps. Rename the WAR file to 'threadfix', or whatever is appropriate. This name will determine the endpoint that ASTAM Correlator will be available at. Follow the Update Permissions step and start Tomcat so that the WAR is extracted. Stop Tomcat once extracted. The Correlator WAR can be extracted manually to /opt/tomcat/webapps instead of running Tomcat, if desired. The remaining steps are the same.

5. The section ThreadFix init Script can be ignored.

6. Before running ThreadFix and after completing the Database Configuration step:

Modify the file /opt/tomcat/threadfix*/WEB-INF/classes/jdbc.properties and change the parameter hibernate.hbm2ddl.auto=update. Its value must be changed to create upon the first run. Start Tomcat and wait for the Correlator to start. You can check its progress using tail /opt/tomcat/logs/astam.log -f. This file will not exist until the Correlator has begun startup. It may take a few moments before the log file appears.

The first run of the Correlator may take up to 30 minutes to finish startup depending on the machine running it.

Initialization has finished once you see the log message Application version set to: ...

Change the hibernate.hbm2ddl.auto value back to update once the ASTAM Correlator has completed startup the first time. Restart tomcat.

WARNING: Starting the Correlator with hibernate.hbm2ddl.auto=create will wipe the ThreadFix database and re-import the default configurations.

After Installation

Once the above steps have been followed and the ASTAM Correlator has completed startup, start Tomcat and navigate to: http://localhost:8080/threadfix* where threadfix* is the name of the WAR that was copied to Tomcat. The port may be different depending on your configuration.

Upon navigating you should see an SSL certificate warning. After accepting the certificate or ignoring the warning, you should be presented with a log-in page for the ASTAM Correlator.

See the Correlator User Guide for more information on how to interact with the ASTAM Correlator web interface.