Cisco firewalls do not have a built-in DNS resolver so an external script must be used to work with ThreatSTOP. This script queries your ThreatSTOP list and populates an object group on a Cisco ASA firewall. The script is written in Perl and will only run in a UNIX environment; Windows cannot run the script. The following command will download the setup script to the folder where the command is run. We recommend downloading this to your home directory and beginning the installation from there.
The script works by querying the ThreatSTOP DNS servers to get the IP addresses in your target lists. Then SSH connection to the firewall is made the current list of IP addresses in the object group is retrieved. After comparing those addresses to what is in the new list, entries are added or deleted as needed. Based on the number of IP addresses added. The first time running the script will take a few minutes. After this initial setup, future updates will go much faster since they only add or delete entries as needed.
Due to the manner in which ThreatSTOP needs to work with Cisco devices, a few things need to happen before the software is downloaded and configured to control the appliance.
- Administrative access to the firewall device must be available via SSH (TCP port 22), to make certain this is available:
- ssh to the firewall’s console/CLI
- Type enable
- Enter the enable password
- Type exit
- Ensure that the appliance has a name server configured. If you wish you may set the default Dynamic Name Server (DNS) on TCP/UDP port 53 to one of the ThreatSTOP DNS servers (126.96.36.199).
- To enable device logging:
- Under Logging in the ASDM, click on Logging, then on Syslog Servers
- Add two servers with the following settings:
- Interface: inside
- IP Address: the Internal IP address for the device uploading its logs to ThreatSTOP.
You may need to repeat this step in multiple-device setups.
- Protocol/Port: UDP/514
- Emblem: No
- Secure: No
- Grant SSL (TCP port 443) access to https://www.threatstop.com.
Confirm that the appliance can also access/download files from the Internet. Check that your appliance can connect with ftp.threatstop.com to do this:
When setting up your device on the ThreatSTOP website, do not use the external IP address of the ASA, but the public IP address of the computer that will run the script. The DNS query must come from the computer that is running the script or it will not work. If you do not know the public IP address of that computer, go to http://www.threatstop.com/cgi-bin/validip.pl from the computer that will run it. This will show you what IP address to use and whether that IP address is currently in our database.
If this is a new device, please allow up to 15 minutes for our systems to be updated.
The script works by:
- Querying the ThreatSTOP DNS server to get the IP addresses in your block lists.
- Opens an SSH connection to the firewall and gets the current list of IP addresses in the object group.
- Compares those addresses to what is in the new list and adds or deletes entries as needed.
The first time the script is run, it will take a few minutes depending on how many IP addresses are being added. After this initial setup, future updates will go much faster since it only adds or deletes entries as needed.
Running the Script
Before running the script, you will need to make an initial SSH connection to the ASA so that the SSH key is properly transferred. You only need to accept the SSH key, you do not need to login. You can type CTRL-C when the password prompt comes up.
Execute the following command on your UNIX box from the directory where the file is installed. Typically this will be your home directory:
As the script runs you will see multiple prompts for information. The example below lists the settings needed for your particular setup, data that will need to be entered is listed in bold. Certain settings will have a default entry listed between the [ ] brackets. In most instances pressing ENTER to use the default will be the correct option, however some specialized setups may require that this data be changed.
At this point, all we have done is create and populate an object group. We do not create any rules on the ASA. The exact rules would depend on your configuration, but the following rules will block all incoming and outgoing traffic that have a source or destination IP address that is in the threatstop-block object group:
Sending Your Logs
Once the setup script has been run for the first time, you will need to configure log parsing on your network appliance. Log parsing is a feature that takes your firewall log and uploads it to us. We then take the log, parse it, and compare the source and destination IP addresses to what is in our database which takes about an hour. After we parse the log, and toss out any IPs that are not in our database, we place the results of the log parsing into our web portal where you can login and see the results. This allows you, and us, to see how effective we are in protecting your network infrastructure.
We do want to note that log parsing only looks for addresses that already exist in our database. If your firewall blocks or allows a connection from an address that is not in our database, we do not record it.
In order the get the logs from a Cisco ASA, you will need to configure the ASA to send logs to a syslog server. The following will configure the ASA to send its logs to a syslog server:
These commands enable logging, add the internal timestamp to the syslog message, and send the logs to a syslog server through the inside interface. You will need to enter the correct IP Address of the syslog server. Please consult the Cisco ASA documentation for additional logging options.
Once the ASA has been configured to send logs to the syslog server, you will need to submit the logs to us, there are two methods to do this:
The preferred method of sending your logs to ThreatSTOP is via SSL (https) upload, using the loguploadclient.pl script included in the download. It is assumed that the syslog server is the same machine used to apply the blocklists. There is a separate page that explains in detail how to setup the syslog server to receive the firewall logs and direct them to a dedicated file that is suitable for upload.
You can also manually upload logs on the Log Submission page. Log files submitted through that web page have a maximum size of 5 MB. If your logs exceed 5 MB you will need to use the loguploadclient script or email the logs.
The email address you send your logs to depends on the IP address of the device the log is for. For this device, you would send the logs to <Device IP>@threatstop.com. The IP address must match the one configured on our website. The email must be in plain text and the log must not be an attachment or compressed.
There is no size limit to the size of the logs sent with email.
If you are sending your logs to DShield, you can add the appropriate ThreatSTOP log email address to the recipient list. For this device, you would add <Device IP>@threatstop.com to the recipient list. Most of the DShield clients support sending the log to multiple email addresses. Consult the documentation of the DShield client you are using for more information.
If you are not submitting logs to DShield and would like to contribute to their effort, please visit their website at http://www.dshield.org. For information about the how to submit logs to DShield go to http://www.dshield.org/howto.html.
In rare circumstances more advanced configuration steps may be required to allow the ThreatSTOP script to communicate with our servers, the material in this section is intended for this boundary cases.
While the setup script automates the creation and maintenance of the threatstop.conf file, some users may choose to edit the file by hand, or in rare circumstances manual changes may need to be made. The following is an example configuration file for this device. If you choose to edit this file, make certain that it is located in the same directory as the script.
The following settings will need to be changed to match your environment:
- dns_server: The ThreatSTOP DNS servers. There is no need to change this.
- device: This is the internal IP address of the ASA. This is the address internal computers use to talk to the firewall.
- block_list: The name of your block list. There is usually no need to change this.
- allow_list: The name of your allow list. There is usually no need to change this.
- object_group_block: The name of the object group where the ThreatSTOP block lists will be stored.
- object_group_allow: The name of the object group where the ThreatSTOP allow lists will be stored.
- username: The username on the ASA used to make an SSH connection.
- password: The password for the SSH user on the ASA.
- enable_pw: The ASA enable password. Leave blank if you do not need an enable password.
- platform: The type of Cisco firewall. The ASA uses FWSM3. There is no need to change this.
- personality: The type of Cisco device. The ASA uses ios. There is no need to change this.
- logfile: The location of the syslog file the ASA creates on this system.
- url: The ThreatSTOP web page to upload the syslog file to. There is no need to change this.
We automatically create an allow list for all devices. The allow list contains only the IP addresses of our DNS servers, 188.8.131.52.
Create the Cron Job
Similar to the Management Appliance section, this section describes a task performed by the automated setup script. However, some individuals may choose to manually setup a cronjob. To do this:
Once you are happy that everything is running properly, you should setup a cron job to run the script at regular intervals. We recommend updating our block lists every two hours. Run this command to edit your crontab:
Paste the following into the crontab and save the file:
Advanced Setup and Troubleshooting
The following steps will allow you to perform an advanced setup on your ASA firewall. Note that these are very advanced steps and should be performed by a Network Administrator familiar with Cisco hardware.
- ssh into the ASA device.
- Get into enable mode by entering: enable and pressing ENTER.
- Type configure terminal and press ENTER.
- To add a network object group type object-group network threatstop-block and press ENTER.
This will create the threatstop-block network object group.
- Type network-object <ip address and netmask> and press ENTER.
This will add the network object for an ip address to the threatstop-block network object group.
To remove a network object:
- Type no network-object<ip address and netmask> and press ENTER.
This will remove the ip address from the threatstop-block network object group.
Restore to Previous State
If you decide to return to your pre-ThreatSTOP configuration, you will need to perform the following actions to disable and remove ThreatSTOP from your system:
Stop the VM from updating the firewall by deleting the user crontab:
- Remove the ThreatSTOP address groups from the policies using them (or delete the policies completely).
- Delete the ThreatSTOP address groups (TSBlock-(number) and TSAllow-(number)).
There is no content with the specified labels