Page tree


Cisco firewalls do not have a 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 IOS based firewall. The script is written in Perl and will only run in a UNIX environment it will not run in Windows. We recommend downloading this to your home directory and beginning the installation from there.

wget-O - 

IOS Version

Not all releases of IOS software correctly implement the firewall element required to apply ThreatSTOP. Specifically this bug is known to exist in IOS 12.4(22)T and earlier and to be fixed in 12.4(22)T5. It should be possible to obtain this version of IOS by contacting Cisco (you should reference this url: ThreatSTOP has not tested other versions of IOS apart from 12.4(22)T5.


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 Anycast server (
  3. Device logging must be enabled, to do this:
    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. SSL (TCP port 443) access to should be granted.

Confirm that the appliance can also access/download files from the Internet. In particular you should 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 firewall, 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 transfered. You only need to accept the SSH key, you don't 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. To run the script, execute the following command:


  3. Here is a sample run of the script the first time it is run:

    threatstop@tsclient:~/work/ts-isr$ ./

    Welcome to the ThreatSTOP setup for CISCO Controllers v2.80
    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.80 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 ISR device:
    [] ==> <Device IP>
    Please enter port to use for DNS queries:
    [53] ==>
    Please enter the Maximum Policy size of the ISR device:
    [30000] ==>
    Please enter the internal IP address of the ISR device:
    [] ==>
    Please enter the username used to SSH to the ISR:
    [] ==> tsadmin
    Please enter the SSH password (text is hidden):
    [] ==>
    Please enter the ISR enable password (text is hidden):
    [] ==>

    Chosen configuration parameters
    CISCO device external IP : <Device IP>
    CISCO device internal IP :
    Username                 : tsadmin
    SSH password             : *******
    ISR 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 ] : Verifying network access to CISCO device <Device IP>
    [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 willneed to resolve the issue before proceeding with the setup script.


    [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 Fri Jul 17 10:00:54 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 name>..threatstop.local
    [INFO ] : Received  1   block  lists to process.
    [INFO ] : Received  234   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 ] : 228 items are still active in the ThreatSTOP block list.
    [INFO ] : 127 items are new in the ThreatSTOP block list.
    [INFO ] : 121 items are old and will be removed.
    [INFO ] : Retrieving current members of "threatstop-allow" network group.
    [INFO ] : 2 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 Fri Jul 17 10:01:09 2015 after 00:00:15

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

    When the script runs, it creates a logfile named "tsoutput.txt" that has a more detailed log of what the script is doing, including every command that is executed while connected to the ISR. The logfile is saved in the same directory as the script.
    At this point, all we have done is create and populate a object group. We do not create any rules on the ISR. 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 ISR, you will need to configure the ISR to send logs to a syslog server. The following will configure the ISR to send its logs to a syslog server:

logging enable
logging timestamp
logging host inside

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 where the place holder is located. Please consult the Cisco ISR 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 <IP Address> 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 <IP Address> 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 these 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 ISR script

# ThreatSTOP DNS Servers

# Internal IP Address of the ISR

# 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

# IOS username for SSH access

# IOS password for SSH access

# Enable password for the ISR

# The type of Cisco device. Current only supports FWSM3
# The type of Cisco device. Current always ios
# Configuration for the script.

# Log file to be uploaded by the script

# URL to upload logs to. Used by the script

Change the following settings 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 ISR.
  • 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 ISR used to make a SSH connection.
  • password: The password for the SSH user on the ISR.
  • enable_pw: The ISR enable password. Leave blank if you do not need an enable password.
  • platform: The type of Cisco firewall. The ISR uses FWSM3. There is no need to change this.
  • personality: The type of Cisco device. The ISR uses IOS. There is no need to change this.
  • logfile: The location of the syslog file the ISR 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 Anycast server,

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 2 hours. Run the 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/

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