ThreatSTOP's ThreatSTOP Centralized Manager (TSCM) software allows for the rapid deployment of ThreatSTOP across multiple devices and types of devices in a production environment. Installation and configuration is also simpler than the single device scripts.
The following instructions will cover the setup of the TSCM from the Command Line Interface (CLI). Note that automating these setups is possible with a simple shell script. However, the instructions will only cover the prompted device installation at this time.
The command to setup and control TSCM is tsadmin. During configuration, tsadmin associates module files that contain configuration data relevant to your available hardware. These files allow tsadmin to communicate with your hardware and expedite setting up ThreatSTOP on your network.
Who should use this manual?
This manual is intended to be a step-by-step guide for System Administrators of intermediate to advanced skill levels. It assumes a certain level of familiarity with setting up Linux based Virtual Machines (VMs), and importing saved Virtual Machine Images (OVA files) into a VM host.
Before installation can begin, the following ports will need to be open along the communications route between the specified destinations:
- tcp/udp port 53: Needs to be opened from the TSCM to ThreatSTOP's DNS servers. The TSCM will query for ThreatSTOP policy (IP Intelligence) data and deliver the data to your firewall device (network objects). This query is a standard DNS query to ThreatSTOP's DNS servers.
- SSH access from the TSCM to the device: To load ThreatSTOP policy to your device, the TSCM requires SSH access to your device.
- UDP port 514 from the device to the TSCM: Syslog on your device is configured to send data to the TSCM. ThreatSTOP requires the messages from syslog as this is the source data for your reports.
- SSL from the TSCM to ThreatSTOP: syslogs upload from the TSCM to ThreatSTOP where our internal systems will parse and process your device logs. In the ThreatSTOP portal the Reporting section shows the result of the log parsing for your account.
VM installation of the ts-appliance image can take one of two different paths. For a Linux based installation download the latest ts-appliance image from our FTP service (ftp://ftp.threatstop.com/pub/TSCM.ova), and make note of its location. Once the VM import has completed you will need to configure Ubuntu as laid out in Adjusting the Appliance to Your Network Environment. A Microsoft Hyper-V based environment is available through our Support (email@example.com) team.
Users running an Oracle Virtual Box based environment will be able to follow the directions in a Virtual Box Deployment and create an environment quickly and easily. Users running VMware's vSphere client may need to follow the additional steps to convert the OVA from Virtual Box format into VMWare's .OVF format as described in VMWare Conversion and Setup.
Virtual Box Deployment
- In Virtual Box, import the OVA file, under Virtual Box this is done by clicking File and selecting Import Appliance…
- Enter the location of the .ova file or click on Browse… and locate the file on your computer. Then click Open, then click Next.
- Review the specifications for the VM to be created, and make any needed changes. Then click Import.
- Provide a name for the VM, this can be left as-is or may be updated to fall into an existing naming schema. Click Next.
- Verify your storage setup and requirements then click Import.
- After the VM has been imported right-click on the new VM entry and select Settings...
- Select the Provisioning required by your deployment.
- Verify the network connections mapped in your OVA template and the network to which it will be deployed, adjust as needed. Then click OK.
Adjusting the Appliance to Your Network Environment
- Power on the VM Console and login using the following login information:
- Username: threatstop
- Password: threatstop
- After powering up the system, the VM will need to be modified to access the network with a static IP address. To do this:
At the command prompt enter:
- Locate the line iface eth0 inet dhcp in the file (see figure 1) you will need to change this.
- Modify the line to iface eth0 inet static, and uncomment the following four lines (see figure 2).
You will need to adjust the address, netmask, and gateway values to match your network.
Figure 1 /etc/network/interfaces default
Figure 2 /etc/network/interfaces configured for a static IP
This should be followed by restarting the network using the command:
Once this is performed the system should be upgraded to the current version of Ubuntu using the following commands. Please be aware that this upgrade process can take more than 25 minutes depending on the speed of your Internet connection.
Enter "sudo apt-get update"
Enter "sudo apt-get dist-upgrade"
As of 08/04/2016, Ubuntu has been updated to 16.04, while the provided OVA does not provide 16.04 the Hardware Enablement (HWE) stack is still supported, but will need to be upgraded. To do this, enter the following command and reboot your system:
Once the VM is back online log in and finish device setup.
Certain conditions will need to be met to use TSCM post installation.
- The user will need either root privileges, or if multiple users are to be allowed to setup devices with TSCM they will need to be added to the threatstop user group.
Entering tsadmin by itself or followed by the switch --help will load tsadmin's internal help system. This system is context sensitive and will change in response to the rest of the provided command line. Definitions of the available switches are available in the Switches section.
Device name entries are not case sensitive.
A note about High-Availability/clustered environments: This setup script should be run against the primary device, a prompt will appear asking for the IP addresses of any other routers that will send logs to syslog, individual configuration of those devices will not be necessary.
To add an FortiGate device to TSCM:
- Enter tsadmin list to check for available devices, if none are available only the header will appear.
Enter tsadmin add <device name> --type <type name>
For example given an FortiGate router named Test1:
This tells the TSCM to load the Fortinet FortiGate module and apply the following settings to that device type.
- A message showing the type of device to be configured will display, press Y to confirm.
- Enter the Block list name (<block list name>.<ThreatSTOP account ID>.threatstop.local), if using a custom Block list, or press ENTER to accept the default.
Enter the Allow list name (<allow list name>.<ThreatSTOP account ID>.threatstop.local), if using a custom Allow list, or press ENTER to accept the default.
Enter the Log upload IP address, use the IP address seen in the ThreatSTOP portal. If you are uncertain of this number visit our Check IP tool and copy the IP Address that appears. Alternatively you can run the following command to find the IP address to use:
A message will appear similar to the following example:
IP address entries are validated by TSCM during installation. This will help to avoid invalid or risky IP addresses such as 127.0.0.1 from being entered.
At the prompt for DNS Port, enter the port number used by your network. In the majority of cases, this is set to the standard DNS port of 53, and it is safe to accept the default by pressing ENTER. In certain rare cases this may need to be changed to port 5353.
The Device management IP address is the router's internal IP address.
At the Please enter all possible s yslog source IP(s) prompt enter the address used to send syslog data from the device to the TSCM. From there the TSCM will send the data to ThreatSTOP for processing. This is most likely going to be the same as the Device management IP address listed above, though some configurations may have a different source. Multiple devices can be entered at the same time for HA/clustered environments this will be supported in a future update. To do this enter each IP separated by a space, for example:
192.0.2.0 192.0.2.1 192.0.2.3you will want to include the primary device's Device Management IP address in this list.
If the setup script was run previously, this field will update to include the previously entered data as a default value.
While multiple devices can be set to the same IP address, this will cause IP collisions and should be avoided. If an incorrect address is put in here, configuration will need to be performed again. A warning will not be provided at this point if a collision has occurred. For setup purposes, if you have not setup your network devices at this time, enter a unique 'dummy' address, and reconfigure the device after provisioning your network.
For the Log rotate size, we recommend that you accept the default value provided; unless you have a specific reason to change the log rotation size. This number is the log size in Kb.
For Send logs to ThreatSTOP enter "N" at this time.
A test needs to be performed to ensure the firewall is blocking connections based on a ThreatSTOP policy that has been loaded into the firewall, and that attempts to connect to a hostile IP are being recorded by the TSCM. However until the device is configured, this test will not complete, as such we're bypassing this step. Once blocking has been confirmed using the test laid out inthe configure switch (detailed in ) can be used to update the device to send logs to ThreatSTOP.
At the Enable policy updates? prompt enter Y.
At the Device username prompt enter the username used to login to your firewall with elevated privileges.
At the Device password prompt enter the password for the username entered in the last step.
The password will not display on the screen and is is stored securely.
For Enable virtual domain support enter Y to add virtual domains to your device.
- Set the Virtual domain name to root.
For Address group name for block list enter the name you want the block or allow lists to appear with in the Address Groups for Fortinet Devices.
We recommend a clear all lowercase object group name (i.e., threatstop-block).
For Address group name for allow list enter the name you want the block or allow lists to appear with in the Address Groups for Fortinet Devices.
We recommend a clear all lowercase object group name (i.e., threatstop-allow).
For the Max entries per policy this property will need to be adjusted as needed for your device.
Set the Max entries per address group to the parameters determined appropriate for your device.
Both the Max entries per policy and Max entries per address group are subject to the available resources for your device. Fortinet provides a guide ( ) that will help you establish the appropriate settings for your device.
The next step will check the connectivity between the TSCM and the device. This is done by opening an SSH connection to the device and attempting to automatically connect. Once this process completes press ENTER to return to the command line. If an IP collision is detected it will be displayed at this point. No changes will be saved and you will need to go through the steps to add a device again and provide an IP address that does not conflict with another device. The availability of IP addresses can be determined using the command tsadmin list to determine which addresses in your configuration have already been issued in your network setup.
At this point you will want to refer to the setup documentation for your device, and setup the device to begin interfacing with the TSCM.
After completing the configuration you will want to test your connection. Details on how to do this can be found in.
Testing the Connection
After device setup has been completed, a test will need to be run to verify the firewall is behaving as intended. To perform this test:
- Open a console on the TSCM and enter "tail -f /var/log/threatstop/devices/<device name>/syslog"
- From a device behind the firewall that is not the TSCM, attempt to connect to
with a web browser.
- If the connection is blocked, you will see a connection blocked error message in the web browser, and the log being tailed will update.
- If the connection is not blocked you will see the ThreatSTOP logo appear, and the configuration settings will need to be double checked.
If the command runs successfully update the device's configuration as detailed in TSCM Configuration to begin sending logs back to ThreatSTOP for enhanced security.
After the initial setup, reconfiguring the device (for example to enable sending logs to ThreatSTOP for processing) uses the following instructions:
- At the command prompt, enter:
tsadmin configure <device name>and press ENTER.
- Accept the established defaults; these come from the settings provided during the initial device setup. If a parameter needs to be changed, you may do so when its prompt appears.
- If setup completed correctly in the previous steps and you choose to Submit logs to ThreatSTOP enter
- The username and password are stored securely and will not need to be added a second time.
- If one appears, enter the password at the Enable Password prompt.
- For the block list, grouping name (Object, Address, or Zone) enter the name you want the block or allow lists to appear as in the control panel for the maintenance device.
- For the allow list, grouping name (Object, Address, or Zone) enter the name you want the block or allow lists to appear as in the control panel for the maintenance device.
- For the Max entries or Number of Dynamic Lists prompts accept the defaults or enter the values determined to be required for your network.
- To verify your settings enter
tsadmin show <device name>and review the output.
Reconfiguration of the device is not immediately applied. tsadmin update is scheduled in cron (/etc/cron.d/multidevice-core) and will automatically update the device when the job is normally scheduled to run. You can speed up this process by entering tsadmin update <device name>.
Notes and Limitations
Attempting to run multiple instances of tsadmin will not work. Multiple users are locked, and only the first user will be allowed to commit their changes.
It is possible to adjust resources on a VM, but the number of CPUs cannot be changed, this will cause the VM to fail to start.
FortiGate Specific Command Line Switches
The following command line switches may be used when setting up a FortiGate based device, in addition to the core ThreatSTOP Centralized Manager switches listed in General TSCM Information.
Name of the address group for the allow lists
|Name of the address group for the block lists|
Default value: None
|Maximum number of entries allowed in block or allow address groups|
Default value: None
|--vdom||Virtual domain name (case-sensitive) |
Default value: None
|--vdom_support||Enable virtual domain support |
Default value: None
Valid Values: enabled, disabled