- 08 Dec 2022
- 12 Minutes to read
ThreatConnect Environment Server Installation Guide
- Updated on 08 Dec 2022
- 12 Minutes to read
In order to install an instance of the ThreatConnect Environment Server, the requirements in the following sections must be met.
The ThreatConnect Environment Server platform requires a server, virtual or physical, that meets the following minimum specifications:
- 4 CPU/vCPU Cores (2 GHz)
- 4 GB of memory
- 10 GB of storage
As the number or frequency of jobs increases, the need to increase system resources will likely occur. The listing in Table 1 highlights typical TC Exchange™ apps and their specific system-resource needs.
|App Name||Frequency||CPU Used||Memory Used|
|ArcSight™ EMS Extract||Daily||1.44||75|
|Tanium™ Extract v2.0||Daily||< 1||< 50|
|QRadar® Extract v2.0||Daily||<1||< 50|
|Palo Alto PAN-OS® Block List||Daily||.10||2.5|
The ThreatConnect Environment Server and its supporting packages require the following software environment in order to run properly:
- Operating System: Red Hat® Linux® variant—either Red Hat Enterprise Linux®(RHEL) 6, 7, or 8 or Community Enterprise Operating System (CentOS™) 6 or 7NoteThis guide assumes that the user for the installation of ThreatConnect is named threatconnect.
- Java® Development Kit (JDK): Access to a local installation of Java 11 (OpenJDK or Oracle Java version 11)
- Python®: Installation of Python 3.6.x for Linux
Developer packages must be installed in order to compile Python from source code:
yum install –y gcc gcc-c++ gcc-gfortran zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gdbm-devel db4-devel libpcap-devel xz-devel expat-devel python-setuptools
Download the source code:
Decompress the downloaded archive:
tar -xf Python-3.6.8.tar.xz
Navigate to the directory where the decompressed files reside:
Run the following command to configure Python:
./configure --prefix=/usr/local --enable-shared LDFLAGS="-Wl,-rpath /usr/local/lib"
Begin the compile process to ensure there are no errors:
make && make altinstall
Set up a symbolic link:
ln -s /usr/local/bin/python3.6 /usr/local/bin/python
TC Exchange requires an available Simple Mail Transfer Protocol (SMTP) server to send email alerts and to correspond with users. This server must be routable from the server running the platform, and if SMTP authorization is required, the ThreatConnect Environment Server will need access to a username and password in order to generate these emails.
Network Traffic Port Requirements
The ports and protocols listed in Table 2 must be opened when deploying the Environment Server inside a network. Appropriate firewall rules must be enabled for these ports from the machine running the Environment Server in order to allow connectivity to your ThreatConnect Dedicated Cloud instance.
|Network Port||Protocol||Traffic Direction||Description|
|443||HTTPS/TCP||Outbound to DC||This port connects to the ThreatConnect Dedicated Cloud API to download apps for execution. Traffic is limited to app installs and upgrades. App downloads are performed when an execution request is sent from the ThreatConnect Dedicated Cloud instance for the first time.|
|62000||TCP||Outbound to DC||This port is defined within the ThreatConnect System Settings. It enables the Environment Server to connect securely with the ThreatConnect Dedicated Cloud message broker to receive real-time commands in order to execute an app to fulfill orchestration requirements, as well as provide command-and-control capabilities. Traffic is lightweight and used primarily in a request/response model to direct app executions.|
Preparing the Environment
The system needs access to the Java JDK as outlined in the “Software” section. In addition, the JAVA_HOME environment variable needs to be properly configured to point to that directory.
The ThreatConnect MEO (Multi-Environment Orchestration) Environment Server requires Java version 11.x to be installed and configured. The latest version of the ThreatConnect MEO software supports both OpenJDK and Oracle JDK version 11.
Installing and Configuring Java
Execute the following command:
rpm -ivh jdk-11.0.10_linux-x64_bin.rpm
Once installation is complete, execute the following command:
alternatives -- config java
This command will output the current location of the new Java installation.
Typically, an installation of this type will create a symbolic link to /usr/java/latest. The following command will confirm whether this location can be configured as the run location for Java:
The next step is to create the threatconnect local OS user account:
Use the following commands to log into and modify the ,bashrc file for the threatconnect account:
su threatconnect vi ~/.bashrc
Then add the following code as the second line of this file, where <path to Java> would typically look like /user/java/latest:
Then reload the bash profile:
ThreatConnect clients can use this guide to configure and install their own Instance of the ThreatConnect Environment Server. This guide assumes a moderate level of systems-administration expertise and an operating environment that satisfies the requirements detailed previously. See Playbook Environments for more information about how to configure, administrate, and use Environments in ThreatConnect.
Downloading the Installer
The Environment Server installer .zip file is available for download on the Environments tab of the Playbooks screen in ThreatConnect (Figure 1).
Click the vertical ellipsis at the upper-right corner of the desired Environment card and select Download. A window containing the download options for the Environment will be displayed (Figure 2).
This window provides three options for download: Download Bundle (All-in-one), Environment Config Only, and Environment Server Only. The Download Bundle (All-in-one) option includes both the Environment Config and the Environment Server as well as the KeyStore files required to make a secure connection to the host ThreatConnect instance. Select this option, and then click the DOWNLOAD button.
Opening the Installer
Unzipping the File
The ThreatConnect Environment Server .zip file serves as an archive of all the necessary files and folders needed to install the application. There are two ways to unzip this file:
- Copy the .zip file to the desired directory on which the ThreatConnect Environment Server will be installed. By default, this directory is /opt, which will result in an installation directory of /opt/threatconnect-envsvr.
- Unzip the file from the command-line interface with the following command:
- Configure permissions within the operating system to ensure that the threatconnect user can access the ThreatConnect Environment Server files. In the following command, the default values of threatconnect and /opt/threatconnect-envsvr, respectively, are being used:
chown –R threatconnect:threatconnect /opt/threatconnect-envsvr
- Run the following command to ensure that all .shscripts are executable, which is a requirement for the MEO Environment Server:
chmod +x /opt/threatconnect-envsvr/*.sh
Installation Directory Structure
After the archive has been extracted, the new folder will contain the following directory structure:
threatconnect-envsvr/ .tcenvsvr README.txt configure.sh run.sh shutdown.sh threatconnect-envsvr.init.sh threatconnect-envsvr.jar
- The .tcenvsvr directory contains the default keystore and broker connection settings.
- The README.txt file contains instructions on how to install the Environment Server.
- The configure.sh file is used to configure the Environment Server settings using a command-line interface.
- The run.sh file is used to run the Environment Server directly from the command line (not as a service).
- The shutdown.sh file is used to shut down the current Environment Server.
- The threatconnect-envsvr.init.sh file is the init.d service script.
- The threatconnect-envsvr.jar file is the file for the Environment Server only (i.e., it does not contain the configuration file).
The ThreatConnect Environment Server Setup
Creating tc-job User
To provide additional security, it is recommended that a separate user on Linux systems be created to run TC Exchange jobs. It is also recommended that read and write groups be created to control the permissions to these files. Use the following code to perform these tasks:
useradd tc‐job echo "tc‐job‐pass123" | passwd tc‐job ‐‐stdin groupadd tc‐job‐read usermod ‐a ‐G tc‐job‐read tc‐job chgrp ‐R tc‐job‐read /opt/threatconnect-envsvr/.tcenvsvr/exchange/programs chmod ‐R 755 /opt/threatconnect-envsvr/.tcenvsvr/exchange/programs groupadd tc‐job‐write usermod ‐a ‐G tc‐job‐write tc‐job chgrp ‐R tc‐job‐write /opt/threatconnect-envsvr/.tcenvsvr/exchange/jobs chmod ‐R 777 /opt/threatconnect-envsvr/.tcenvsvr/exchange/jobs chmod +t /opt/threatconnect-envsvr/.tcenvsvr/exchange/jobs
User Privilege Configuration
Add the following lines to /etc/pam.d/su after the first auth command:
auth [success=ignore default=1] pam_succeed_if.so user = tc‐job auth sufficient pam_succeed_if.so use_uid user = threatconnect
Create /etc/sudoers.d/threatconnect using the following command:
visudo -f /etc/sudoers.d/threatconnect
Then add the following lines:
Defaults:threatconnect !requiretty threatconnect ALL=(tc‐job) NOPASSWD: ALL
This configuration allows the threatconnect user to run the jobs as the tc-job user.
Starting the ThreatConnect Environment Server
After completing the installation and configuration procedures, it is time to start the ThreatConnect Environment Server.
Starting as a Linux Service
The options in the previous sections allow a user to run the ThreatConnect Environment Server in a single session. This approach presents a number of limitations: The platform will need to be started manually after each reboot, or a terminal window or Secure Shell (SSH) session may have to be left open. To address this problem, this section details the file configuration to run the ThreatConnect Environment Server as a service in Linux.
Open a terminal window and browse to the app directory within the ThreatConnect Environment Server directory. Run the run.sh file as follows:
su - threatconnect -c ./opt/threatconnect-envsvr/run.sh
Running this command will ensure proper connectivity to the ThreatConnect Dedicated Cloud instance for your organization. As long as logs indicating connectivity to your DC instance (FQDN:62000 with successful connection) are being generated, the MEO server will connect properly to the DC instance.
Run CTRL-C to force the process to close. Once the process is closed, execute the following command:
su - threatconnect -c ./opt/threatconnect-envsvr/configure.sh
A menu providing options for configuration of the MEO instance will be provided.
Please select an option: 1: System Configuration 2: Variables 3: Exit
Select 1: System Configuration. The System Configuration menu will be displayed.
System Configuration: Please select an option: 1: List all System Config 2: Edit System Config 3: Export Configuration 4: Go Back
Select 2: Edit System Config. Then edit the Java and Python locations as they are configured within your current MEO server configuration. Typically, the options to select are 3: appsJavaHome and 5: appsPythonHome, respectively.
If implementing a proxy within the Environment Server, the fields in the following menu will need to be configured.
13: proxyExternal = <empty> 14: proxyHost = <empty> 15: proxyPassword = <empty> 16: proxyPort = <empty> 17: proxyTC = <empty> 18: proxyUsername = <empty>
- Set options 13 and 17 to true.
- Populate options 14, 15, 16, and 18 according to your organization’s proxy configuration for where this server resides.
The Service Script
Within the ThreatConnect Environment Server installation, there is a script used for running the ThreatConnect Environment Server as an initialized service:
This script must be copied into the /etc/init.d directory for it to be recognized as a system service. Note that users may require privileges to copy to this directory:
The service script requires proper permissions and paths to be set.
- Specify the TCENVSVR_HOME variable within the script to point to the path where the ThreatConnect Environment Server installation exists. By default, this path is /opt/threatconnect-envsvr.
- Specify the USER variable within the script to identify which user owns the files for the ThreatConnect Environment Server application. It is advisable, for security reasons, that the root user not be employed. By default, the username is assumed to be threatconnect.
Starting the ThreatConnect Environment Server as a Service
Once the services have been configured, the ThreatConnect Environment Server can be started as a service. To do so, enter one of the following commands while logged in as the root user:
service threatconnect-envsvr start /etc/init.d/threatconnect-envsvr start
To stop the service, use either one of the following commands:
service threatconnect-envsvr stop
To have the ThreatConnect Environment Server start on system startup, issue the following commands after the script is configured in the /etc/init.d directory:
For sysVinit systems:
chkconfig ‐‐add threatconnect-envsvr chkconfig threatconnect-envsvr on
For systemd systems:
systemctl enable threatconnect-envsvr
The First Login
Setting Master Key for Keychain
The Keychain feature is required for the ThreatConnect Environment Server. When prompted, enter a Master Password. The Master Password is used to encrypt sensitive values and is required on every server restart.
System Settings Checklist
Users should review their Instance settings to ensure that they are configured according to their needs. Table 3 provides a description of each system configuration value.
|System Configuration Value||Description|
|apiURL||This setting should point to the URL for the API at port 8443 (e.g., https://api.threatconnect.com:8443).|
|appDeliveryToken||This setting is the token that is used to authenticate with the App Catalog Server.|
|appsJavaHome||This setting holds the path to the Java binary.|
|appsNumberofJobExecutors||This setting is the number of Job Executors that can run concurrently. It is a factor of the number of CPUs and the available memory on the server. It should not exceed available resources.|
|appsPythonHome||This setting holds the path to the Python® binary.|
|appsSandboxUser||This setting represents the user account used to execute Jobs. It is pertinent only in Linux® installs.|
|appsSessionDaystoKeep||This setting is placed at 5 in Cloud. It indicates the number of days that logs will be kept in the Jobs log directory: %threatconnect%/exchange/jobs.|
|brokerHost||This setting is the remote host name of the messaging server to which the Environment Server will connect.|
|brokerToken||This setting is the secure key used to authenticate a connection to the remote message broker.|
|proxyExternal||This setting is set to true when all external connections for apps should be routed through a proxy server.|
|proxyHost||This setting is the proxy host to use if a proxy server is required. Acceptable values are a valid IP address or host name for a proxy accessible by the ThreatConnect instance.|
|proxyPassword||This setting is the proxy password to use if a proxy server requires authentication.|
|proxyPort||This setting is the proxy port to use if a proxy server is required. Enter a valid proxy port number.|
|proxyTC||This setting is set to true when all connections to the ThreatConnect host server should be routed through a proxy server.|
|proxyUsername||This setting is the proxy username to use if a proxy server requires authentication.|
|queueTransport||This setting is empty by default and utilizes the raw TCP socket for messaging services. For deployments that require a proxy, set this value to websocket. This will change the transport to an HTTP-based transport protocol supported by secured proxy environments. All traffic will move through port 62000 over HTTP/S. If the proxy is defined, then the Environment Server will utilize this proxy for all messaging traffic.|
|relaySystemInfoPublishSeconds||The frequency at which to notify the remote ThreatConnect instance of the status of the Environment Server.|
|serverName||The name of the Environment Server to display on the ThreatConnect Environments screen and administration page.|
|serverXid||This setting is a static number that uniquely identifies the given Environment Server. Its value should not be changed.|
ThreatConnect® is a registered trademark, and TC Exchange™ is a trademark, of ThreatConnect, Inc.
ArcSight™ is a trademark of Hewlett Packard Enterprise Company.
QRadar® is a registered trademark of IBM Corporation.
Linux® is a registered trademark of Linus Torvalds.
Java® is a registered trademark of Oracle Corporation.
PAN-OS® is a registered trademark of Palo Alto Networks.
Python® is a registered trademark of Python Software Foundation.
Red Hat® and Enterprise Linux® are registered trademarks, and CentOS™ is a trademark, of Red Hat, Inc.
Tanium™ is a trademark of Tanium, Inc.
10028-12 EN Rev. A