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.
ThreatSTOP Centralized Manager has the following pre-installation conditions for Palo Alto Networks devices:
- Users that will be allowed to setup devices with TSCM must either have root privileges, or be added to the threatstop usergroup.
- Port 80 must allow TCP communications between the TSCM and PAN devices.
The following steps correspond to onscreen prompts to add a PAN device to the TSCM. These steps install a TSCM controlled ThreatSTOP configuration onto a PAN device. Please be aware that the configuration put in place is disabled and needs activation through the PAN interface. Enabling a PAN Configuration Post Setup, explains how to enable ThreatSTOP on the PAN Device.
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.
Enter tsadmin list to check for available devices. On a fresh installation, no devices should display, only the header will appear. The rest of these steps will add a PAN device to your configuration.
Example TSCM device list, after fresh installation.
After verifying your devices, enter tsadmin add <device name> --type <type name>
For example given a PAN firewall named Test1:
Device names should only consist of upper or lowercase A-Z, the numbers 0-9, underscores, periods, and hyphens.
This displays the following prompt. Answer Y or accept the default to the prompt by pressing ENTER to begin the configuration for a Palo Alto Networks device.
Enter the Block list name you wish to use, if using a custom Block list, or press ENTER to accept the default. This is the blocklist name as provided by ThreatSTOP and can be located in your Devices screen on the portal. The format follows <Policy name>-netb.<Threatstop Account ID>.threatstop.local. For example TSBasic-netb.Threat<xx>.threatstop.local.
Enter the Allow list name you wish to use, if using a custom Allow list, or press ENTER to accept the default. This is the allowlist name as provided by ThreatSTOP and can be located in your Devices screen on the portal. The format follows <Policy name>-neta.<Threatstop Account ID>.threatstop.local. For example TSBasic-neta.Threat<xx>.threatstop.local.
Setting the Block list name and Allow list name fields will establish the external lists (EBL) in the PAN device.
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 entry validation by TSCM occurs during installation. This will help to avoid entry of invalid or risky IP addresses such as 127.0.0.1.
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 firewall’s management IP address. This is the static IP address for this management device, as it was established in the VM Installation section of General TSCM Information. If this is not set, the TSCM will not be able to reach the firewall for updates, and may require a reset to regain control.
At the Please enter all possible syslog 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. 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. Entry of an incorrect address will require reconfiguration. No warning is 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 accept the default of Y.
We will to need test that the firewall is blocking connections based on a ThreatSTOP policy that has been loaded into the firewall, and that the TSCM is recording attempts to connect to a hostile IP. Testing the Connection covers the test. However, until the configuration is complete, this test will not succeed, it is however OK to leave this switch set to Y. The configuration will continue and we will manually update the device at the end with a single line command.
At the Enable policy updates? prompt accept the default of Y. This will download allow policy information from ThreatSTOP's servers and load them into the PAN device. This is the backbone of the ThreatSTOP, and is quite potentially the most important step in this process.
At the Device username: prompt enter the username used to login to your firewall. Enter this to allow the TSCM to configure the device.
TSCM uses the PANOS API to make updates to the device, which means that this account must have API permissions on the PANOS device.
At the Device password: prompt enter the password for the username entered in the last step. Enter this to allow the TSCM to configure the device.
The password will not display on the screen and is stored securely.
You will now be prompted for High-Availability (HA) or cluster mode. If your device is in an HA/clustered setup enter the IP addresses for the additional firewalls in the network (the setup script is already handling the primary). If you are not using an HA/clustered environment tap ENTER to default to none.
The next prompt will add ThreatSTOP into an existing syslog profile (if one exists and is specified), or will create a new syslog profile for ThreatSTOP. Enter a syslog profile name, or tap ENTER to have one generated.
When prompted with Name of the Trusted Zone, enter one or more Trusted Zone names in a comma separated format. These are the names used to refer to anything on the safe side of your PAN device, meaning your internal network. This has been defaulted to Trusted.
Similarly, enter the name for an Untrusted Zone at the Name of the Untrusted Zone prompt in a comma separated format. These are the ports that may present bad data sources. The default is set to Untrusted.
For the Virtual system name prompt, enter the vsys name as it appears at the top of the screen when viewing your vsys. This is not the entry in the Name field of the device, but has the format vsysX (where X is a number) and should appear at the top of the screen when configuring the PAN device. For a single firewall instance, this would be vsys1.
The number of dynamic lists ThreatSTOP may use : Defaults to 9 (one allow and eight block). Adjust this property to meet the available resources on your device. If you have custom dynamic lists already generated, you will need to drop this number to account for the number of block and allow lists you currently have setup.
The number of objects in a dynamic block list is determined by the maximum number of IP addresses supported by your firewall. This is calculated automatically for each device.
To do this, we retrieve the maximum number of addresses from the device. These are returned to us per-dynamic list. That is, if a device claims 10,000 addresses, then the server reserves 300 for it's own use, so the device can actually support as many as 9,700 block rules per list, or 77,600 addresses total (8 * 9,700 = 77,600 with another 9,700 for an allow list).
Dynamic lists are loaded in order, up to max addresses - 300 with a maximum of eight (8) blocklists, and one allow list. Any addresses that aren't loaded will be empty. That is, if your ThreatSTOP Policy uses less than the maximum number of addresses, or you have other dynamic objects on the firewall, you will want to lower the number of dynamic lists used by TSCM.
- If this is a new device and new policy, please wait about 15 minutes before attempting to apply the policy to the PAN device
The prompt Are you sure you want device updates enabled at this time? allows device updates by ThreatSTOP. The first update will configure the device and issue a full commit of any pending changes. If you have pending changes that were not created by ThreatSTOP you may wish to enter N for now, verify the changes, and then re-run this setup and enter Y to enable ThreatSTOP's changes.
Configured policy rules are installed in a disabled state. They will need to be enabled on the PAN device once the changes have been uploaded to the device.
The next step will check the connectivity between the TSCM and the Palo Alto Networks device. The API does this transparently, and automatically attempts to connect to the device. A successful attempt will display:
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 list issued addresses in your network setup.
Once the device is configured the Hostname in Syslog is set to a value of ipv4-address. Do not change this. It is required for ThreatSTOP reporting to work correctly, and changes to this value will cause the reporting to fail.
Successfully completing a connection test will allow the TSCM to download system logs, and upload them to ThreatSTOP for processing.
- After the program exits, if the connection test was successful, enter: tsadmin update <device name> and press ENTER . This will configure the PAN with the data provided above, set the syslog source IP, establish the syslog server, setup log forwarding, create the EBLs and then setup the policies.
Configuration of the TSCM is now complete, but the policies uploaded to the TSCM will not be active at this point. You will need to login to the TSCM and activate the policies in the firewall itself. Instructions to accomplish this are in Committing the Changes to the Device .
Lists cannot be imported until they have been added to a policy rule. After adding the list to an enabled policy rule, the data for it will be imported.
Committing the Changes to the Device
Once the configuration of the TSCM is completed, you will need to turn on the policies in the PAN device to place the device in a state to receive information from the TSCM and ThreatSTOP. To enable the policies on the device:
- Log into your PAN device through the web management interface.
- Click on Policies.
- You will see all of your rules established for your policy on this device. Including four rules for ThreatSTOP:
After enabling your policies, you will want to test the connection between your device and ThreatSTOP. Testing the Connection has details on how to do this.
Forcing the import of a block list into the EBL
It may be necessary at times to force the import of a block list into the EBL. The procedure to do this is:
- Click Objects.
- Click Dynamic Block Lists.
- Check the box next to the lists you want imported immediately.
- Click Import Now ( ).
In addition to the ThreatSTOP policies that you will now receive, and the updates that these will send back, you have the option of setting up log forwarding on all of a devices policies using syslog and Log forwarding. Enabling this information across all of your devices will help to strengthen the threat intelligence we provide.
This procedure has two parts, one of ThreatSTOP and one for existing policies on the PAN.
To turn on Log Forwarding to ThreatSTOP:
- Under Objects click Log Forwarding.
- Click on ThreatSTOP.
- Select any of the data you want to forward and click OK.
- Click on Commit, this will start contributing your logs to our threat assessment pool starting with your next batch.
To turn on Log Forwarding for other policies:
As an option, other logs generated by your Palo Alto device can be forwarded to ThreatSTOP for processing and inclusion in your ThreatSTOP firewall.
- Click on the Device tab.
- Then click on Syslog.
- Then click on TSCM.
- Click Add.
A list of log forwarding options will appear.
- Add the entries TSCM should include and click OK twice.
- Click Commit to save the changes to the router.
The TSCM VM maintains a webserver for Palo Alto devices, which the PAN should use for rule updates.
Steps to Remove ThreatSTOP Configurations from PAN Devices
Removing a PAN device from TSCM, will remove the ThreatSTOP configurations on the PAN device. You will need to log onto your PAN device and perform the following steps:
Disable the ThreatSTOP Policy Rules - these rules reference the dynamic block lists and the log forwarding profile. Until these policy rules are removed, you will be unable to delete the configurations under Policies->Security :
- Check each of the four ThreatSTOP policy rules
- Click Disable ( ) at the bottom of the policy rules window
- Login to the management device.
Enter tsadmin remove <device name>
This will remove the PANOS device and all ThreatSTOP Policy Rules, as well as the dynamic block lists and log forwarding profile.
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.
PANOS Specific Command Line Switches
The following command line switches may be used when setting up a PANOS based device, in addition to the core ThreatSTOP Centralized Manager switches listed in General TSCM Information.
If in HA mode, these are the additional IP(s) (quoted, space-separated)
|Number of dynamic lists to use (2-9)|
Default value: None
Valid values: [2,3,4,5,6,7,8,9]
|The name of the trusted zone|
Default value: None
|The name of the untrusted zone|
Default value: None
|--vsys_name||Virtual system name (case-sensitive) |
Default value: None