Page tree

Contents

Overview

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.

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.

Device setup:

  1. Route Preparation
  2. VM Installation
  3. Enabling ThreatSTOP on the Device

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.

tsadmin

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.

Route Preparation

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

The TSCM installation is available in three different Linux distribution formats (as listed to the right). After downloading the .ova for your chosen flavor of Linux, the file can be imported to VMware. Once the VM import has completed you will need to configure the new VM as laid out in Adjusting the Appliance to Your Network Environment. A Microsoft Hyper-V based environment is also available through our Support (support@threatstop.com) team but is not directly supported here.

Beginning Deployment

  1. In vSphere, import the OVA file by clicking File and selecting Deploy OVF Template
  2. Enter the location of the .ova file or click on Browse… and locate the file on your computer. Then click Next.
  3. Review the details of the deployment, make note of the Size on disk values. Click Next.
  4. 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.
  5. Select the resource pool into which your device should be deployed, and click Next.
  6. Select the destination storage destination for the Virtual Machine, and click Next.
  7. Select the Provisioning required by your deployment and available disk space.
  8. Verify the network used in the OVF template, and click Next.
  9. Review your deployment selections and click Finish, if they appear correct.

Adjusting the Appliance to Your Network Environment

  1. 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. This will vary by the distribution being deployed. To do this:

CentOS 7.3

  1. At the command prompt enter:

    sudo vi /etc/network-scripts/ifcfg-ens160

  2. Locate the line:

    BOOTPROTO="dhcp"

    This will need to be modified to none.

  3. The following information will also need to be added to the end of the file:

    IPADDR="192.168.1.7"
    NETMASK="255.255.255.0"
    GATEWAY="192.168.1.99"
    DNS1="192.168.1.99"
    DNS2="8.8.8.8"

  4. After these settings are changed, save the file and restart networking with the command:

    sudo systemctl restart NetworkManager

  5. Once this is performed the system should be upgraded to the current version of CentOS 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.

    1. Enter sudo yum update

RHEL 7.3

  1. At the command prompt enter:

    sudo vi /etc/sysconfig/network-scripts/ifcfg-ens192

  2. Locate the line:

    BOOTPROTO="dhcp"

    This will need to be modified to none.

  3. The following information will also need to be added to the end of the file:

    IPADDR="192.168.1.7"
    NETMASK="255.255.255.0"
    GATEWAY="192.168.1.99"
    DNS1="192.168.1.99"
    DNS2="8.8.8.8"

  4. After these settings are changed, save the file and restart networking with the command:

    sudo systemctl restart NetworkManager

  5. Once this is performed the system should be upgraded to the current version of RHEL 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.

    1. Enter sudo yum update

Ubuntu

  1. At the command prompt enter:

    sudo vi /etc/network/interfaces

  2. Locate the line iface eth0 inet dhcp in the file (see figure 1) you will need to change this to iface eth0 inet static.
  3. Uncomment and adjust the address, netmask, and gateway values to match your network (see figure 2).

    # The primary network interface
    auto eth0
    iface eth0 inet dhcp

    # address 192.168.1.7
    # netmask 255.255.255.0
    # gateway 192.168.1.99

    #dns-nameservers 192.168.1.99 8.8.8.8

    Figure 1 /etc/network/interfaces default

    # The primary network interface
    auto eth0
    iface eth0 inet static
       address 192.168.1.7
       netmask 255.255.255.0
       gateway 192.168.1.99
       dns-nameservers 192.168.1.99 8.8.8.8

    Figure 2 /etc/network/interfaces configured for a static IP

  4. This should be followed by restarting the network using the command:

    sudo /etc/init.d/networking restart

  5. 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.

    1. Enter sudo apt-get update

    2. Enter sudo apt-get dist-upgrade

Recommended Versions

ThreatSTOP is compatible with most versions of PAN-OS.

Minimum6.1
Recommended7.1

Note:

A non-TSCM based set of instructions can be found under Palo Alto Networks PAN-OS 5.0. Please take down the following information as you will need it to complete setup instructions if you do not use the TSCM based setup since these values will not correctly populate in the linked document.

Device IP<Device IP>
Block List Name

<block list name>..threatstop.local

Allow List Name<allow list name>..threatstop.local

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.

Note:

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.

  1. 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.

    Device name: Type Management IP syslog IP Log upload IP Log size Device updates Log uploads

    Example TSCM device list, after fresh installation.

  2. After verifying your devices, enter tsadmin add <device name> --type <type name>
    For example given a PAN firewall named Test1:

    tsadmin add Test1 --type pan

    Caution:

    Device names should only consist of upper or lowercase A-Z, the numbers 0-9, underscores, periods, and hyphens.

  3. 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.

    Configuring 'Palo Alto Networks'. Continue? (y or n) [default y]

  4. 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.

    Block list name : [default basic.threatstop.local] <block list name>..threatstop.local

  5. 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.

    Allow list name : [default dns.threatstop.local] <allow list name>..threatstop.local

    Setting the Block list name and Allow list name fields will establish the external lists (EBL) in the PAN device.

  6. 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.

    Log upload IP address :

    Alternatively, you can run the following command to find the IP address to use:

    wget -qO - https://www.threatstop.com/cgi-bin/validip.pl

    A message will appear similar to the following example:

    Your IP address: 192.0.2.0
    This is the IP address you will want to use.

    Note:

    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.

  7. 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.

    DNS port : [default 53]

  8. 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.

    Device management IP address :

  9. 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.3 you will want to include the primary device's Device Management IP address in this list.

    Please enter all possible syslog source IP(s) :

    If the setup script was run previously, this field will update to include the previously entered data as a default value.

    Caution:

    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.

  10. 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.

    Log rotate size, in Kb : [default 100]

  11. 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.

    Send logs to ThreatSTOP? (y or n) [default y]

  12. 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.

    Enable policy updates? (y or n) [default y]

  13. At the Device username: prompt enter the username used to login to your firewall. Enter this to allow the TSCM to configure the device.

    Important:

     TSCM uses the PANOS API to make updates to the device, which means that this account must have API permissions on the PANOS device.

    Device username :

  14. 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.

    Note:

    The password will not display on the screen and is stored securely.

  15. 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.

    Is this device part of an HA/cluster setup?
        If so, enter the additional IP(s) (space-separated),
        or "none" for no HA : [default none]

  16. 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.

    Name of an existing syslog profile in which the ThreatSTOP server will be added
                  or "none, and a ThreatSTOP syslog profile will be created : [default none]

     

  17. 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.

    Name of the trusted zone : [default Trusted]

  18. 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.

    Name of the untrusted zone : [default Untrusted]

  19. 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.

    Virtual system name (case-sensitive) : [default VSYS_NAME]

  20. 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 dynamic lists ThreatSTOP may use : [default 9]
    **** Important PAN device configuration note :
      You indicated "yes" to enable device updates by ThreatSTOP.
      Upon the first update, the PAN device will be configured,
      followed by a FULL commit of all pending changes on the
      device. If you want time to check your device for pending
      configuration changes that were not initiated by ThreatSTOP,
      you may proceed with updates disabled. And then come back
      later and enable this setting.

    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.

    Note:

    •  If this is a new device and new policy, please wait about 15 minutes before attempting to apply the policy to the PAN device
  21. 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.

    Are you sure you want device updates enabled at this time? (y or n) [default y]

  22. 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:

    [INFO ] : Checking Palo Alto Networks credentials at 192.0.2.0
    Successfully added pan

    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.

    Caution:

    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.

  23. Successfully completing a connection test will allow the TSCM to download system logs, and upload them to ThreatSTOP for processing.

  24. 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.
  25. 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 .

    Caution:

    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:

  1. Log into your PAN device through the web management interface.
  2. Click on Policies.
  3. You will see all of your rules established for your policy on this device. Including four rules for ThreatSTOP:
    • ThreatSTOP-Allow-Inbound
    • ThreatSTOP-Allow-Outbound
    • ThreatSTOP-Block-Inbound
    • ThreatSTOP-Block-Outbound
  4. Place these rules where you want them in your policy. We recommend placing them at the top to receive the maximum amount of protection from ThreatSTOP.
  5. After placing the rules in your desired location select all four rules, and click Enable () at the bottom of the screen.
  6. Now click Commit () at the top of the screen to enact the changes.

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:

  1. Click Objects.
  2. Click Dynamic Block Lists.
  3. Check the box next to the lists you want imported immediately.
  4. Click Import Now ().

Enable Reporting

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:

  1. Under Objects click Log Forwarding.
  2. Click on ThreatSTOP.
  3. Select any of the data you want to forward and click OK.
  4. 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.

  1. Click on the Device tab.
  2. Then click on Syslog.
  3. Then click on TSCM.
  4. Click Add.
    A list of log forwarding options will appear.
  5. Add the entries TSCM should include and click OK twice.
  6. Click Commit to save the changes to the router.

Note:

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:

  1. 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 :

    1. Check each of the four ThreatSTOP policy rules
    2. Click Disable () at the bottom of the policy rules window
  2. Login to the management device.
  3. 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:

  1. Open a console on the TSCM and enter "tail -f /var/log/threatstop/devices/<device name>/syslog"
  2. From a device behind the firewall that is not the TSCM, attempt to connect to bad.threatstop.com 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.

TSCM Configuration

After the initial setup, reconfiguring the device (for example to enable sending logs to ThreatSTOP for processing) uses the following instructions:

  1. At the command prompt, enter: tsadmin configure <device name> and press ENTER.
  2. 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.
  3. If setup completed correctly in the previous steps and you choose to Submit logs to ThreatSTOP enter Y when prompted.
  4. The username and password are stored securely and will not need to be added a second time.
  5. If one appears, enter the password at the Enable Password prompt.
  6. 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.
  7. 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.
  8. For the Max entries or Number of Dynamic Lists prompts accept the defaults or enter the values determined to be required for your network.
  9. 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.

SwitchEffect
--additional_devices

If in HA mode, these are the additional IP(s) (quoted, space-separated)
Default value
: None

--max_dynamic_lists

Number of dynamic lists to use (2-9)
Default value: None
Valid values: [2,3,4,5,6,7,8,9]

--trusted_zone

The name of the trusted zone
Default value: None

--untrusted_zone

The name of the untrusted zone
Default value: None
--vsys_nameVirtual system name (case-sensitive)
Default value
: None