This document describes how to integrate ThreatSTOP’s Policy and Reporting services with a Cisco ASA device:
- Automated retrieval and updates of IP Defense policies from ThreatSTOP’s systems to the ASA.
- Automated collection and upload of log files from the ASA to ThreatSTOP’s systems.
The integration is performed by a Linux-based virtual machine provided by ThreatSTOP, named ThreatSTOP Centralized Manager (TSCM). After its initial installation, the TSCM will retrieve the list of subnets matching the policy configured via the ThreatSTOP Admin portal and update the ASA using an SSH connection. Optionally, the ASA can be configured to send the connection log events to the TSCM via syslog and the TSCM will package and upload log files to ThreatSTOP’s Portal, for analysis and reporting.
Fig 1. : Network traffic between ThreatSTOP services, the TSCM and the ASA. (click to expand)
This document provides the steps using the Command Line-based installation of ThreatSTOP. Using the Command Line method, device settings are configured on the command line. The initial configuration and future changes must be done using the TSCM CLI. Changes to the policy assignment must be done on both the portal and TSCM CLI.
For the Web-based installation, please read this document instead.
The current version of TSCM is compatible with all ASA devices running ASA Software version 7.x, 8.x and 9.x.
It is also compatible with Cisco ASA with FirePower services (5500-FTD-X range) using standard ASA features. For ASA with Firepower or Firepower NGFW support, use the Cisco Firepower or Cisco Firepower (Web Automation) integrations. The Firepower models are listed here .
The Maximum Policy Size is the maximum number of ACLs that your device can support. It depends on the hardware and memory available on the device. Please contact your Cisco reseller to find out the capacity of your device, or refer to this independent document .
Current version of TSCM
The current version of the TSCM OVA is 1.38. If your TSCM image is older, please download the latest version from the device configuration page in the Admin Portal. You can find out the TSCM version by running
$ tsadmin version
The current version of the ASA module is 3.36 (included with TSCM 1.38 images)
Installation parameters for experienced users
If you have already created a device entry in the portal, and are familiar with the installation procedure, you can access the TSCM parameters below if you access this document from the Portal Device page.
|Device ID||Retrieved from the device settings page|
|Policy (Block List)||Retrieved from the device settings page|
|Policy (Allow List)||Retrieved from the device settings page|
The TSCM is delivered as an OVA or VHD image, built using Ubuntu 20.04 as the base Operating System. It is preconfigured with:
- 2 CPUs
- 2 GB of RAM
- 20 GB of disk space
You will need a Hypervisor such as vSphere, ESXi, Virtualbox or Hyper-V to deploy the image.
To retrieve its configuration and policy, and to upload log data, the TSCM needs the following connectivity:
- DNS over TCP - Policy service
- Hostname: dns.threatstop.com
- IP Range: 22.214.171.124/24
- Outbound TCP port 53 or 5353
- HTTPS - Log service
- Hostname: logs.threatstop.com
- IP range: 126.96.36.199/28
- Outbound TCP port 443
- Direct Connection or via Proxy
- Hostname: ntp.ubuntu.com
- Outbound UDP port 123
It must also be able to communicate with the Cisco device:
- TCP Port 22
- From the TSCM to the ASA
- TCP or UDP Port 514
- From the ASA to the TSCM
Cisco ASA credentials
To perform this installation, you need an account reachable via SSH on the ASA as well as the Enable password for the device.
Integration ThreatSTOP with a Cisco ASA device using the TSCM CLI is performed in 4 steps:
- Configuring the device settings on the Admin Portal
- Downloading and loading the OVA
- Configure the device settings using the TSCM CLI
- Apply ACLs and configure log forwarding on the ASA
Step 1: Portal
During this step, you will create a device entry on the Admin Portal. You will select a device type (Cisco ASA) and enter the configuration settings.
To create a Cisco ASA device entry:
- Log into the Admin Portal with your ThreatSTOP account
- Browse to the Device page and click Add Device
- Select the ASA model:
- Type: IP Defense
- Manufacturer: Cisco
- Model: ASA
- Integration Type: TSCM
The Admin Portal will display a form to enter the device settings described below and the links to retrieve the TSCM image.
Nickname: this is a mnemonic name used to identify the device. It can be set to any string (A-Z, 0-9, - and _). If you create multiple device entries, each entry must have a unique nickname. The Nickname will be used to identify the device on the TSCM and in the Reporting user interface.
Policy: select a pre-defined policy or a customized policy. It must be an IP Defense Policy.
IP Type: Access to the ThreatSTOP services is controlled in part using an ACL allowing the device IP to connect. If your device has a static public IP address (the most common case), select static. If your device has a dynamic public IP address, the ThreatSTOP services can lookup the IP address using a DNS fully-qualified name (FQDN).
Public IP address: In static mode, this is the public IP address of the device. It is possible to configure multiple device entries with the same public IP address.
Domain name: In Dynamic mode, this is a DNS FQDN which must be kept up-to-date as an A record pointing to the device’s dynamic IP.
Note: An optional field to store a note of your choice about the device - location, identifiers, model…
Upon saving the form, a device entry will be created in ThreatSTOP’s cloud.
Step 2: Download and boot image
After creating the device entry, the next step is the download using FTP and installation of the TSCM image.
You can choose between the OVA format (ESXi/vSphere, VirtualBox, Xen…) and the VHD format (Microsoft Hyper-V).
The download link is listed in the Step 2 section, as shown in this image.
- Click on the Copy Download Link to copy the link to your clipboard
- Use an ftp client of your choice, or a tool such as curl
- For your security: after downloading the file, we encourage you to validate its SHA 256 checksum. Compute it as shown below and compare it to the checksum in the Portal.
$ shasum -a 256 <filename>
- Import the OVA or VHD file in your Hypervisor to create the virtual machine and start it.
Log into the TSCM
The TSCM virtual machine will use DHCP to obtain its IP address. If your Hypervisor doesn’t show the IP address assigned to the virtual machine, you can retrieve it from the console of the TSCM: it is displayed as part of the login prompt.
The virtual machine will be reachable using ssh:
- The default username is: threatstop
- The default password is: threatstop
Step 3: Configure the Device settings using the TSCM CLI
After booting the TSCM and logging in via ssh, the third setup step will link the virtual machine to the device entry created in Step 1.
The TSCM has a configuration utility named tsadmin. A reference for the utility is provided here but we will cover the full installation steps below.
Obtain the Device ID and Policy zone names from the device configuration or device info pages on the portal
Login with the threatstop account using ssh
- Validate that the TSCM can reach the ASA using SSH
ssh admin@<ASA IP address> The authenticity of host '<ip address>' can't be established. ECDSA key fingerprint is SHA256:UW05wRgAblpwjfObj4ZklSYfau8PnoE1GXXuSCO5Zfs. Are you sure you want to continue connecting (yes/no)?
- Accept the host key
- Login to validate the password
- Run the following command:
$ tsadmin add --type asa [device nickname]
The tsadmin command will prompt you for the following device settings.
Device ID (tdid): A unique identifier for the device. This setting must be correct for the TSCM to operate normally. This setting can be retrieved from the Device settings or Device Info page on the portal.
Device Management IP address: This is the internal address of the device. The TSCM will communicate with the ASA via SSH using this IP address.
Block list name: the name of the zone associated with the Block list of the policy selected in the portal. This setting can be retrieved from the Device settings or Device Info page on the portal.
Allow list name: the name of the zone associated with the Allow list of the policy selected in the portal. This setting can be retrieved from the Device settings or Device Info page on the portal.
Object Group Name (Block List): the name of the Object Group that the TSCM will use to store the subnets in the Block List generated by your Policy. The default is threatstop-block.
Object Group Name (Allow List): the name of the Object Group that the TSCM will use to store the subnets in the Allow List (whitelist) generated by your Policy. The default is threatstop-allow.
Max entries per object group: select the highest number of ACLs supported by your ASA; see this document for guidance. If the policy becomes larger than this setting, the TSCM will truncate it to match the configured setting.
Send logs to ThreatSTOP?: If enabled, the TSCM will send logs received from the device to the ThreatSTOP reporting system. This is the recommended setting. When disabled, logs for this device will not be available for reporting in the Portal.
Device username: the username for a Cisco ASA account available via SSH
Device password: the SSH password for the Cisco ASA account
Cisco Enable Password: the “enable” password for the ASA device
The TSCM supports the following advanced settings, which cover uncommon ASA configurations or network environments. To enable the advanced settings, add the –advanced option to the tsadmin command line
$ tsadmin add --type asa --advanced [device nickname]
Enable policy updates? (y or n) [default y] Enable syslog forward? (y or n) [default n] 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] User name prompt : (leave empty unless you have customized the device’s user name prompt) [default empty] Password prompt : (leave empty unless you have customized the device’s password prompt) [default empty]
DNS Port: The TSCM uses TCP Port 53 (outbound connections) to retrieve policy data. If this port is blocked or filtered (for example, networks using a DNS Application Layer Gateway), use this setting to switch to TCP Port 5353.
Additional syslog source IP(s): Typically, logs will be sent over syslog by the device itself. If logs are sent by another IP address (for example, after being processed by a SIEM, or in High-Availability configurations), that IP address should be configured in this field.
Log rotate size: the TSCM will upload logs after 15 minutes and when the log file size is reached. For systems under very heavy network traffic with many blocked connections, lowering this value will cause logs to be uploaded more often.
Enable policy updates: this setting can be used to temporarily disabled policy updates by the TSCM. This is not recommended but can be used if device configuration changes needed to be suspended.
Syslog Forward: if you want the TSCM to forward the logs to another systems (in addition to uploading them to ThreatSTOP’s cloud for reporting), enter yes. The CLI will prompt for the IP address, Port and protocol (UDP or TCP) that logs should be forwarded to.
Log Upload Proxy: If your environment requires using a proxy to reach HTTPs URLs, you can specify the address of a proxy. The proxy must support HTTPs using the CONNECT protocol. The proxy address must be http://address:port, where address is either an IP address or a fully-qualified domain name. HTTPs proxies are not supported. If you provide a proxy URL, the TSCM configuration will also prompt you for an optional user and password. Provide them if the proxy requires authentication.
HA/cluster setup: See the High-Availability section below
Custom password prompt: if you have customized the ASA configuration to change the ssh password prompt (Password:), you can configure the value that the TSCM should look for when connecting to the ASA.
At this time, the TSCM has succesfully configured the device entry.
You can view the list of devices linked on the TSCM image:
$ tsadmin list | Device name | Type | Device ID | Management IP | Log upload ID | Log | Log uploads | | tstest | asa | tdid_abcd1234 | 172.21.50.3 | tdid_abcd1234 | 100k | enabled |
- From this point on, the TSCM will retrieve policy data (IP subnets) and configure them on the ASA, every hour.
- To force the initial update and proceed with testing, run the following command
$ tsadmin update <device name>
This will create (if not already created) and populate the two Object Groups defined in the device settings.
To verify that the Object Group have been created, open an SSH session to the device and execute the following commands:
enable configure terminal show running-config object-group id <Object Group name>
Step 4: ASA configuration
With the Object Groups populated, the last step is to configure the ASA. Open an SSH session and execute the following commands.
enable configure terminal (config)# access-list global_access extended permit ip object-group threatstop-allow any (config)# access-list global_access extended permit ip any object-group threatstop-allow (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 end
Enabling Log forwarding
To configure the device to send logs to the TSCM, enter the following:
enable configure terminal logging enable logging timestamp logging host inside <TSCM IP address> end
You can test that the policy is correctly applied by pinging bad.threatstop.com (188.8.131.52) through the device, a test IP included in all policies. The ping command should fail.
Logging and Reporting
If log upload is enabled, the TSCM will now upload logs every 15 minutes, as long as there were connections blocked by the policy since the last upload. The logs can be analyzed in the IP Defense Reports 15 minutes after they’ve been uploaded.
To check that the log upload feature is able to reach the server:
- After applying the ACLs, generate log entries by trying to reach our test address through the device. The command should fail to connect.
- Run the following command on the TSCM to rotate and upload the log file
$ tsadmin logs
If the command doesn’t find a log file to upload, it will exit immediately:
threatstop@tsclient:~$ tsadmin logs [INFO ] : Starting log upload client [INFO ] : Log upload client exited
- Log files are stored in /var/log/threatstop/devices/<device name>/syslog.
- If no log file is present, check the syslog forwarding configuration on the device and check that the ACL is applied.
threatstop@tsclient:~$ tsadmin logs [INFO ] : Starting log upload client [INFO ] : [Uploader] Loading device configuration [INFO ] : Processing logs for device [devicename] [INFO ] : Starting ThreatSTOP logupload operation v2.00 at 24/05/2018 19:34:05 [INFO ] : Verifying log file [/var/log/threatstop/devices/isr135/syslog.1] stats [INFO ] : Processing [/var/log/threatstop/devices/devicename/syslog.1] log file [INFO ] : Start sending data [INFO ] : Preparing connection data [INFO ] : Connecting to https://logs.threatstop.com:443/logupload.pl [INFO ] : Upload was successful [200 OK] [INFO ] : Completed processing for device [isr135] [INFO ] : Finish ThreatSTOP logupload operation at 24/05/2018 19:34:10 after 00:00:05 [INFO ] : Log upload client exited
If the command attempts to upload a log but fails, check the connectivity of the TSCM to ThreatSTOP’s log service, described in the connectivity section of this document.
Support for multiple devices
If your Cisco ASA is part of a High-Availability cluster, the TSCM can connect to each device in the cluster to keep the Object Groups up-to-date. The devices must have the same set of credentials.
- Use advanced mode (–advanced) when adding (tsadmin add) or configuring (tsadmin configure) the device settings
- Enter the IP address(es) of the additional nodes in the HA cluster when prompted for this question: Is this device part of an HA/cluster setup?
- Configure the same IP address(es) as Syslog IP to allow the TSCM to receive logs from the additional nodes
- Repeat the configuration steps on the additional ASA device(s) to apply the Object Groups and forward logs
To view the current settings on the TSCM, run
$ tsadmin show <device name>
- To update the configuration of the device, run the tsadmin ‘configure’ command:
$ tsadmin configure <device name>
The configure command also supports the –advanced option enable the advanced settings described in the configuration section of this document.
To update the TIP and retrieve new versions of the ThreatSTOP software, login as threatstop and run the following command:
$ sudo apt-get update && sudo apt-get -y dist-upgrade
- To disable the integration, the first step is the deletion of the device on the TSCM. This will stop any policy updates or changes to the ASA device.
$ tsadmin remove <devicename>
- The second step is the removal of the Object Groups on the ASA.
enable configure terminal (config)#no access-list global_access extended permit ip object-group threatstop-allow any (config)#no access-list global_access extended permit ip any object-group threatstop-allow (config)#no access-list global_access extended deny ip object-group threatstop-block any (config)#no access-list global_access extended deny ip any object-group threatstop-block end
- If log forwarding was enabled, turn it off with one of the following commands:
- If you have log forwarded to several servers
enable configure terminal no logging host inside <TSCM IP Address>
- or, to disable logging entirely:
enable configure terminal no logging
- If you have log forwarded to several servers
- The last step is to delete the device entry on the Portal, using the Device List page. This step will caused the log data from the device to be unavailable in the Reporting interface of the Portal. If needed, you can recreate a new device entry for the same device, with the same or different settings. Note that the new entry will have a different Device ID for linking the TSCM.
- Failure to retrieve policy: tsadmin add fails with this error: “block or allow list [name] could not be fetched from ThreatSTOP DNS servers.” There are two common causes:
- A network connectivity problem using DNS over TCP (Outbound connection to ts-dns.threatstop.com on Port 53).
- the policy is not available yet. It typically takes 15 minutes for new devices and new policies to be activated in the Policy Service.
If the network connectivity is ok, and 15 minutes have elapsed since the device entry was created, please contact ThreatSTOP Support at email@example.com.
- Some versions of the Cisco ASA software include a DNS Application Layer Gateway (ALG) enabled by default, which interferes with ThreatSTOP’s DNS updates, creating failures to retrieve the policy data. The ALG can be disabled with these commands:
no ip nat service alg tcp dns no ip nat service alg udp dns
- If tsadmin add fails to connect to the device, check the credentials (username, password and enable password). If they are correct, check if the ssh password prompt has been changed from Cisco’s defaults (Password:).
|1.38||2018-10-09||Support for proxy-based log uploads|
|1.37||2018-10-04||Added network configuration tool||1.36||2018-08-08||Remove uncessessary duplicate IP warning; support for Firepower|
|1.35||2018-05-24||Added tsadmin option to enable advanced settings|
|1.31||2018-03-26||Fix for log upload script|
|1.30||2018-02-06||Support for Web Automation|
- Cisco ASA Module
|3.36||2018-10-09||Extended ASA version checks|
|3.35||2018-05-24||Supported for Advanced settings option|
|3.30||2018-02-14||Improve SSH connection error handling|
|3.11||2017-08-11||Support for session-style commits in ASA 9.3.2 and later|