Cisco ISR integration (TSCM with Web Automation)

Overview

This document describes how to integrate ThreatSTOP’s Policy and Reporting services with a Cisco ISR device:

• Automated retrieval and updates of IP Defense policies from ThreatSTOP’s systems to the ISR.
• Automated collection and upload of log files from the ISR to ThreatSTOP’s systems.

System view

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 ISR using an SSH connection. Optionally, the ISR 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 ISR. (click to expand)

Web Automation features

This document provides the steps when using the Web Automation features of ThreatSTOP. For the command line-based installation, please read this document instead. The Web Automation features are:

• Client configuration settings are managed on the ThreatSTOP portal, instead of using the TSCM command line.
• Changes to the policy selection are automatically propagated from the portal to the TSCM
• The TSCM reports problems applying policies or uploading logs to the ThreatSTOP Portal, providing more visibility into potentials system or network problems.

Compatibility

ISR Compatibility

• The current version of TSCM is compatible with all ISR devices and IOS versions.

• It is also compatible with IOS/XE.

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

Current version of TSCM

The current version of the TSCM virtual machine is 1.50. 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 ISR module is 3.41 (included with TSCM 1.50 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.

Link Command:

$ tsadmin add --type auto --device_id=[Device ID] --auto_key=[Device Key]

Prerequisites

System

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.

Connectivity

To retrieve its configuration and policy, and to upload log data, the TSCM needs the following connectivity:

• DNS over TCP - Policy service
  • Hostname: ts-dns.threatstop.com
  • IP Range: 192.124.129.0/24
  • Outbound TCP port 53 or 5353
• DNS over TLS - Configuration service
  • Hostname: ts-ctp.threatstop.com
  • IP Range: 204.68.97.208/28
  • Outbound TCP port 5353
• HTTPS - Log service
  • Hostname: logs.threatstop.com
  • IP range: 204.68.99.208/28
  • Outbound TCP port 443
  • Direct Connection or via Proxy
• NTP
  • Hostname: ntp.ubuntu.com
  • Outbound UDP port 123

It must also be able to communicate with the Cisco device:

• SSH
  • TCP Port 22
  • From the TSCM to the ISR
• Syslog
  • TCP or UDP Port 514
  • From the ISR to the TSCM

Cisco ISR credentials

To perform this installation, you need an account reachable via SSH on the ISR as well as the Enable password for the device.

Setup

Integration ThreatSTOP with a Cisco ISR device using Web Automation is performed in 4 steps:

1. Configuring the device settings on the Admin Portal
2. Downloading and loading the VM image
3. Linking the TSCM to the Portal device configuration
4. Apply ACLs and configure log forwarding on the ISR

Step 1: Portal

During this step, you will create a device entry on the Admin Portal. You will select a device type (Cisco ISR) and enter the configuration settings. A minimum configuration only requires a handful of settings but optional, advanced options are also available.

To create a Cisco ISR device entry:

• Log into the Admin Portal with your ThreatSTOP account
• Browse to the Device page and click Add Device
• Select the ISR model:
  • Type: IP Defense
  • Manufacturer: Cisco
  • Model: ISR
  • Integration Type: TSCM with Web Automation

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.

• Internal IP address: This is the internal address of the device. The TSCM will communicate with the ISR via SSH using this IP address. Note: Authentication credentials are documented below.

• Note: An optional field to store a note of your choice about the device - location, identifiers, model…

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

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

• Enable Log Upload: 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.

• Maximum Policy Size: select the highest number of ACLs supported by your ISR. If the policy becomes larger than this setting, the TSCM will truncate it down to the Maximum Policy Size.

Upon saving the form, a device entry will be created in ThreatSTOP’s cloud.

Advanced Settings

The TSCM supports the following advanced settings, which cover uncommon ISR configurations or network environments.

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

• Syslog IP address: Typically, logs will sent over syslog by the device itself. If logs are sent by another IP address (for example, after being processed by a SIEM), that IP address should be configured in this field.

• Log file 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.

• Custom password prompt: if you have customized the ISR configuration to change the ssh password prompt (username@ip_address’s password:), you can configure the value that the TSCM should look for when connecting to the ISR.

• SSH Options: some versions of IOS only support older ssh encryption ciphers. If tsadmin fails to connect with ssh, attempt to ssh directly from the TSCM console. If ssh shows a cypher error (Unable to negotiate with [ip address] port 22: no matching cipher found. Their offer: aes128-cbc,3des-cbc,aes192-cbc,aes256-cbc), enter one of the supported cipher in this field (-c [cipher name])

• Compress Configuration: compress the system configuration when saving it to the device’s flash memory. Useful for large policies where the uncompressed config might not fit on the flash memory of smaller device (Refer to Cisco’s documentation of the feature). Set to Compress/Uncompress to compress/uncompress the configuration (regardless of the current setting) or set to Leave untouched to keep the device’s current setting.

• 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 during the TSCM installation. Provide them if the proxy requires authentication.

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: Link the TSCM to the Device entry

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.

• Login with the threatstop account using ssh
• Obtain the Device ID and Device Key from the device configuration page. You can copy them to your clipboard by clicking the icon. The Device ID is the string tdid_ followed by 8 alpha-numerical characters.

• Validate that the TSCM can reach the ISR using SSH

  ssh admin@<ISR 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 your password
• Run the following command:

$ tsadmin add --type auto --device_id=[Device ID] --auto_key=[Device Key]

• The tsadmin command will first retrieve the device settings from the ThreatSTOP Portal. If the command fails, check the Troubleshooting section.

• Once the configuration is retrieved, tsadmin will prompt for credentials for the ISR device. They will be used to connect to the device but will not be stored outside of the TSCM image.
  • a username (typically, admin)
  • a password
  • the enable password
• tsadmin will verify the connectivity to the device. If you are prompted to access an SSH Host key, please proceed.

At this time, the TSCM has succesfully linked itself to the device entry, and validated its ability to reach the ISR device.

Sample session:

$ tsadmin add --type auto --device_id=tdid_abcd1234 --auto_key=BTFDWvEepY2z3LcSjmp3lgW+jUiVjAIF6lYvd2cnCikKO855YiUKfhmEcWvK1Ztouw==
Web Automation - Retrieving configuration from ThreatSTOP Portal
Next, please provide credentials for the Cisco ISR device (not stored on the portal)
Device username : admin
Device password :
Cisco "enable" password :
[INFO ] : Assuming device default user name and password prompts
[INFO ] : Validating access with DNS server
[INFO ] : Assuming device default user name and password prompts
[INFO ] : Checking connectivity to the Cisco ISR at 172.21.50.3
Successfully added tstest

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      | isr  | 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 ISR, 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
show running-config | include object-group network

The output should contain the threatstop-allow and threatstop-block groups.

Step 4: ISR configuration

With the Object Groups populated, the last step is to configure the ISR. Your ACL configuration may vary. The goal is to apply the allow and block groups to all inbound and outbound traffic (from the internal networks to the internet, and vice versa.)

As an example, open an SSH session and execute the following commands:

• Put the blocks into access lists

  enable
  config terminal
  ip access-list extended TS-in
  permit ip object-group threatstop-allow any      ! Don’t log allows
  deny ip object-group threatstop-block any log    ! Log blocks
  permit ip any any                                ! Don’t log allows
  ip access-list extended TS-out
  permit ip any object-group threatstop-allow      ! Don’t log allows
  deny ip any object-group threatstop-block log    ! Log blocks
  permit ip any any                                ! Don’t log allows
  exit
  write mem
  

• Apply the access lists to the external interface of the device

  enable
  config terminal
  interface FastEthernet0/1
  ip access-group TS-in in
  ip access-group TS-out out
  exit
  write mem
  

You can test that the policy is correctly applied by pinging bad.threatstop.com (64.87.3.133) through the device, a test IP included in all policies. The ping command should fail.

Logging and Reporting

To configure the device to send logs to the TSCM, enter the following:

enable
config terminal
logging <TSCM IP address>
exit
write mem

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.

  curl http://bad.threatstop.com
  

• Run the following command on the TSCM to rotate and upload the log file

  $ tsadmin logs
  

If the command doesn’t file a log file, 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.

Successful upload:

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/asa135/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 [asa135]
[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.

Additional considerations

Support for multiple devices

High-Availability

No additional configuration is required to support High-Availability configurations for IOS and IOS/XE routers and switches.

Other operations

Current configuration

To view the current settings on the TSCM, run

$ tsadmin show <device name>

Configuration changes

• After the initial configuration is completed, settings can be edited on the Admin Portal and will be reflected on the device within 5 minutes, including Policy configuration changes.

• If you change the credentials on the ISR device, you will need to run tsadmin configure <device name> and update them on TSCM to allow the virtual machine to continue to connect.

Error reporting

The TSCM update process wil report failures such as:

• failure to download the policy
• failure to apply the policy on the ISR
• failure to connect to the log upload service

Failures are reported on the Device List page of the portal.

Software updates

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

Uninstall steps

• 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 ISR device.

  $ tsadmin remove <devicename>
  

• The second step is to remove the ACL from the interface. The command will vary based on which interface(s) the ACL is applied to. Given the example provided in the ISR Configuration section:

  enable
  config terminal
  interface FastEthernet0/1
  no ip access-list extended TS-in in
  no ip access-list extended TS-out out
  exit
  write mem
  

• At this point, the ACLs are not applied anymore. To remove them from the configuration, run:

  enable
  config terminal
  no ip object-group threatstop-allow
  no ip object-group threatstop-block
  exit
  write mem
  

• To remove the logging configuration

  enable
  config terminal
  no logging <TSCM IP address>
  exit
  write mem
  

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

Additional information

Troubleshooting

• Failure to link the device: tsadmin add fails with this error: “Failed to connect to Web Automation services”. The common cause is a network connectivity problem using DNS over TLS (Outbound TCP connection to ts-ctp.threatstop.com on port 5353).

• Failure to link the device: tsadmin add fails with this error: “Failed to retrieve settings using Web Automation. There are three common causes:
  • The Device ID or Device Key is not correct.
  • The system time is not correct. The virtual machine run an NTP client which must be up-to-date. Check its status with the timedatectl command.
  • The new device entry has not been activated yet. Wait 2-3 minutes and retry.
• 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 support@threatstop.com.

Version history

• TSCM

• Cisco ISR Module

Related documents

• TSCM reference
• Creating custom policies
• Command-line based version of TSCM for ISR