Page tree



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.

wget -O -

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.

  1. Administrative access to the firewall device must be available via SSH (TCP port 22), to make certain this is available:
    1. ssh to the firewall’s console/CLI
    2. Type enable
    3. Enter the enable password
    4. Type exit
    This allows the ThreatSTOP script to use SSH to create network object groups and addresses in those groups.
  2. 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 (
  3. To enable device logging:
    1. Under Logging in the ASDM, click on Logging, then on Syslog Servers
    2. Add two servers with the following settings:
      1. Interface: inside
      2. 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.
      3. Protocol/Port: UDP/514
      4. Emblem: No
      5. Secure: No
  4. Grant SSL (TCP port 443) access to

Confirm that the appliance can also access/download files from the Internet. Check that your appliance can connect with 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 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:

  1. Querying the ThreatSTOP DNS server to get the IP addresses in your block lists.
  2. Opens an SSH connection to the firewall and gets the current list of IP addresses in the object group.
  3. 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

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

    shell# ssh
    The authenticity of host '' can't be established.
    RSA key fingerprint is 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added '' (RSA) to the list of known hosts.
    user@'s password: ^C

  2. Execute the following command on your UNIX box from the directory where the file is installed. Typically this will be your home directory:


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

    Welcome to the ThreatSTOP setup for CISCO Controllers v2.90

    At the first stage of setup process you will be given the chance
    to specify a number of setup options. You can always change them
    later by re-running setup script or by manually updating the
    relevant entries in threatstop.conf file.

    If parameter had been previously configured its value will be shown
    in [] on parameter request line. You can choose to re-use this value
    by simply pressing enter.

    For security reasons the preconfigured password parameter is not shown.
    Instead if previous configuration exists it will appear as [******].


    [INFO ] : Starting script v.2.90 execution

    [INFO ] : Entering interactive stage.

    Please enter the block_list to use:
    [] ==> <block list name>..threatstop.local

    Please enter the allow_list to use:
    [] ==> <allow list name>..threatstop.local

    Please enter the external IP address of the ASA device:
    [] ==> <Device IP>

    Please enter port to use for DNS queries:
    [53] ==>

    Please enter the Maximum Policy size of the ASA device:
    [30000] ==>

    Please enter the internal IP address of the ASA device:
    [] ==>

    Please enter the username used to SSH to the ASA:
    [] ==>

    Please enter the SSH password (text is hidden):
    [] ==>

    Please enter the ASA enable password (text is hidden):
    [] ==>

    Chosen configuration parameters
    CISCO device external IP : <Device IP>
    CISCO device internal IP :
    Username                 : <user name>
    SSH password             : *******
    ASA enable password      : *******
    ThreatSTOP block list    : <block list name>..threatstop.local
    ThreatSTOP allow list    : <allow list name>..threatstop.local
    Port                     : 53
    Max policy size          : 30000

    Apply settings Y/N?: [Y]
    [INFO ] : Generating configuration file.
    [INFO ] : Verifying network access to CISCO device
    [INFO ] : Establishing ssh connection

    We need to make sure that ssh authorized_keys are properly setup between your
    machine and the CISCO device.  Please wait for the ssh password prompt, then log
    into the CISCO device.  Immediately after, press enter.  This will end the SSH
    session and bring you back into the setup script.
    Please watch for possible ssh connection failures.  If this happens, you will
    need to resolve the issue before proceeding with the setup script.

    <username>@'s password:
    Type help or '?' for a list of available commands.
    ciscoasa> quit


    Connection to closed by remote host.

    [INFO ] : Network access OK.
    [INFO ] : Prepare logrotation configuration.

    We are about to start the system configuration process.
    A SUDO access password may be required.

    [INFO ] : Restarting syslog-ng.
     * Stopping system logging syslog-ng                                 [ OK ]
     * Starting system logging syslog-ng                                   [ OK ]
    [INFO ] : Setting up cron entries for automatic execution.
    [INFO ] : Running upload rules script for the first time...

    We are ready to run upload rules script for the first time.  The script
    execution output will be saved into tsoutput.log log file.

    [INFO ] : Starting ./ v2.90 on Wed Jul 15 14:44:33 2015
    [INFO ] : Locking current execution instance.
    [INFO ] : Previous configuration found ...  Loading config data...
    [INFO ] : Initializing data from configuration file.
    [INFO ] : Verifying manditory parameters state.
    [INFO ] : Updating DNS lists.
    [INFO ] : Testing [] servers.
    [INFO ] : Comparing DNS lists.
    [INFO ] : Updating configuration file with new DNS servers list.
    [INFO ] : Building allow/deny lists.
    [INFO ] : Getting allow list <allow list name>..threatstop.local
    [INFO ] : Received  1   allow  lists to process.
    [INFO ] : Received  2   allow  results.
    [INFO ] : Getting block list block_list=<block list name>..threatstop.local
    [INFO ] : Received  1   block  lists to process.
    [INFO ] : Received  147   block  results.
    [INFO ] : Initializing remote connection.
    [INFO ] : Logging into remote device.
    [INFO ] : Entering Privileged Mode.
    [INFO ] : Retrieving current members of "threatstop-block" network group.
    [INFO ] : 5 items are still active in the ThreatSTOP block list.
    [INFO ] : 146 items are new in the ThreatSTOP block list.
    [INFO ] : 4 items are old and will be removed.
    [INFO ] : Retrieving current members of "threatstop-allow" network group.
    [INFO ] : 4 items are still active in the ThreatSTOP allow list.
    [INFO ] : 0 items are new in the ThreatSTOP allow list.
    [INFO ] : Removing old block addresses...  Please wait.  It can take some time...
    [INFO ] : Adding new block addresses.
    [INFO ] : Removing old allow addresses.
    [INFO ] : Adding new allow addresses.
    [INFO ] : Leaving privileged mode.
    [INFO ] : Logging off.
    [INFO ] : Unlocking current execution instance.
    [INFO ] : Finished on Wed Jul 15 14:44:41 2015 after 00:00:08

    [INFO ] : Upload rules process completed...
    [INFO ] : Finished v.2.90 execution

    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:

    (config)# access-list global_access extended deny ip object-group threatstop-block any
    (config)# access-list global_access extended deny ip any object-group threatstop-block

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:

logging enable
logging timestamp
logging host inside XXX.XXX.XXX.XXX

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:

  • Uploading
  • Email

Uploading Logs

The preferred method of sending your logs to ThreatSTOP is via SSL (https) upload, using the 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.

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

DShield Logs

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> 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 For information about the how to submit logs to DShield go to

Advanced Configuration

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.

Management Appliance

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.

#Configuration file for ThreatSTOP Cisco ASA script

# ThreatSTOP DNS Servers

# Internal IP Address of the ASA

# ThreatSTOP Block List Name
block_list=<block list name>..threatstop.local

# ThreatSTOP Allow List Name
allow_list=<allow list name>..threatstop.local

# Name of the network object group for the block lists

# Name of the network object group for the allow lists

# ASA username for SSH access

# ASA password for SSH access

# Enable password for the ASA

# The type of Cisco device.
# For version 2 of the Net::Session::Appliance module
# For version 3 of the Net::Session::Appliance module

# Configuration for the script.
# Log file to be uploaded by the script

# URL to upload logs to. Used by 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,

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:

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

    crontab -e

  2. Paste the following into the crontab and save the file:

    # Update the ThreatSTOP lists. Every 2 hours, 23 minutes after the hour (00:23, 02:23, 04:23, etc.)
    # You will need to modify the path to the script
    23    */2    *    *    *    /path/to/the/script/

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.

  1. ssh into the ASA device.
  2. Get into enable mode by entering: enable and pressing ENTER.
  3. Type configure terminal and press ENTER.
  4. To add a network object group type object-group network threatstop-block and press ENTER.
    This will create the threatstop-block network object group.
  5. 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:

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

  1. Stop the VM from updating the firewall by deleting the user crontab:

    crontab -r

  2. Remove the ThreatSTOP address groups from the policies using them (or delete the policies completely).
  3. Delete the ThreatSTOP address groups (TSBlock-(number) and TSAllow-(number)).


There is no content with the specified labels