cb-taxii-connector
Connector for pulling and converting STIX information from TAXII Service Providers into CB Feeds.
You can install the pre-built RPMs via YUM by using the CB Open Source repository. (See CbOpenSource.repo and put that in /etc/yum.repos.d/)
The pre-built RPM is supported via our User eXchange (Jive) and via email to dev-support@carbonblack.com.
Introduction
This document describes how to install and use the Cb Response TAXII Connector. This connector allows for the importing of STIX data by querying one or more TAXII services and retrieving that data and then converting it into CB feeds using the CB JSON format for IOCs. The job queries for available STIX/TAXII data that is newer than the last time it asked, and by default runs every hour.
For each TAXII service, available “collections” are enumerated and a Cb Response Feed is created. For example, if you have two TAXII services and each exposes two collections, you will have four CB feeds as a result of this connector.
The following IOC types are extracted from STIX data:
- MD5 Hashes
- Domain Names
- IP-Addresses
- IP-Address Ranges
Requirements
This Cb Response TAXII Connector has the following requirements:
- Carbon Black Enterprise Response Server 5.0 (or greater) – this integration leverages API calls and feed functionality available in Cb Response 5.0 and newer. In order to check the version, you can run the following rpm command on your server:
[root@localhost ~]# rpm -qa | grep cb-enterprise
cb-enterprise-5.0.0.150122.1654-1.el6.x86_64
- Access to TAXII Service Provider – the purpose of this integration is to retrieve STIX threat information via a TAXII service, so if you do not have access to a TAXII service this integration will be of no value. Example services are SoltraEdge and HailATaxii.com
Installation
Take the following steps to install the Cb Response Taxii Connector:
- Install the CbOpenSource.repo file found in the root of this repository (place it in /etc/yum.repos.d/ on your head CB Server node.)
- Install by issuing the following command as root (or sudo): yum install python-cbtaxii -y
Upgrades
When an upgrade is available, it should be as easy as doing the following:
yum install python-cbtaxii -y
- Note Upgrading from 1.0/1.1 to 1.2, you'll need to supply auth_token=(CB Server Admin API Token) in the config file under the cbconfig directive.
Please note that a new /etc/cb/integrations/cbtaxii/cbtaxii.conf.example might be made available in some cases, at which point any new settings should be studied, understood, and applied to the production configuration file if necessary.
Configuration
You’ll need to place a configuration file in the following location:
/etc/cb/integrations/cbtaxii/cbtaxii.conf
A sample file is provided in /etc/cb/integrations/cbtaxii/cbtaxii.conf.example
, so you can rename the file with the following command:
mv /etc/cb/integrations/cbtaxii/cbtaxii.conf.example /etc/cb/integrations/cbtaxii/cbtaxii.conf
From here, one or more TAXII services can be configured. The example configuration file is placed here along with the comments it contains:
# Imports taxii/stix feeds into Carbon Black feeds
# general cbconfig options
[cbconfig]
# change this if your API port is different
#(API port is usually the same port that you login using for the UI)
server_port=443
# You NEED to set this to a CB Server Admin API Token
auth_token=
#
# Put each site into its own configuration section.
# You might just have a single site, like soltra edge or a remote taxii server
# Make sure each section like this has a unique name
#
[soltraedge]
# the address of the site (only server ip or dns; don't put https:// or a trailing slash)
# for example, site=analysis.fsisac.com
site=192.168.230.205
# change to true if you require https for your TAXII service connection
use_https=false
# by default, we validate SSL certificates. Turn this off by setting sslverify=false
ssl_verify=false
# if you need SSL certificates for authentication, set the path of the
# certificate and key here. Please leave blank to ignore.
cert_file=
key_file=
# username for auth
username=admin
# password for auth
password=avalanche
# you can optionally specify which collections to convert to feeds (comma-delimited)
collections=*
# the output path for the feeds, probably leave this alone
output_path=/usr/share/cb/integrations/cbtaxii/feeds/
# the icon link, we come with soltra and taxii icons, but if you
# have your own, this will show up
icon_link=/usr/share/cb/integrations/cbtaxii/soltra-logo.png
# automatically create CB feeds, probably leave this to true
feeds_enable=true
# do you want feed hits in CB to generate alerts? Available options
# are syslog or cb, and you can do both by putting syslog,cb
feeds_alerting=syslog,cb
# there have been a lot of indicators that are whole class Cs.
# Set this to false if you do not want to include these indicators,
# otherwise set to true
enable_ip_ranges=true
# (optional) the start date for which to start requesting data.
# Defaults to 2015-01-01 00:00:00 if you supply nothing
start_date=2015-03-01 00:00:00
# (optional) the minutes to advance for each request. This
# defaults to 15. If you don't have a lot of data, you could
# advance your requests to every 60 minutes or multiply 60 times
# number of hours, so 1440 to ask for data in daily chunks
minutes_to_advance=30
# (OPTIONAL)
# The number of reports to collect from each site, limited to 10K by default
# when ommited
reports_limit=10000
Execution
By default the linux cron daemon will run this integration every hour to check for new data from the TAXII services you
have configured. When it runs it will use the current settings found in /etc/cb/integrations/cbtaxii/cbtaxii.conf
,
so make sure you are careful when changing any of those settings.
When you first install the connector, you might not want to wait until the hour mark for the job to run. In this case, you can force the connector to run manually. As either root or cb user on the Cb Response Server, execute the following command:
/usr/share/cb/integrations/cbtaxii/cbtaxii -c /etc/cb/integrations/cbtaxii/cbtaxii.conf
It is perfectly fine to do this because the script will only allow one copy of itself to run at a time, so you don’t have to worry about the cron daemon attempting to run this while your manual instance is still executing.
Note #1: this script can take a long time to run depending on the amount of data available from the TAXII services you have configured.
Note #2: this script logs everything to /var/log/cb/integrations/cbtaxii/cbtaxii.log , so you will see very little output when you run it manually.
If you want to check that your credentials work and list the available collections, execute the same command with -l (lowercase-L):
/usr/share/cb/integrations/cbtaxii/cbtaxii -c /etc/cb/integrations/cbtaxii/cbtaxii.conf -l
Troubleshooting
If you suspect a problem, please first look at the cbtaxii connector logs found here:
/var/log/cb/integrations/cbtaxii/cbtaxii.log
(There might be multiple files as the logger "rolls over" when the log file hits a certain size).
We've seen where Soltra Edge had a user account that wasn't returning data past a particular date for a specific username. We don't know why this was the case. The customer created a new SoltraEdge user account and used those credentials in our connector and everything went back to working.
Additionally, due to STIX being a particulary verbose format, sometimes IOCs are stored in fields that we don't expect. This could result in some IOCs you see in your Taxii platform (such as SoltraEdge) but not show up in Cb Response. For this and other issues, you can export the raw XML that our connector receives so we can see how information is represented. To export, use the following command, then contact us and we'll setup a place for you to place the exported XML for our analysis.
/usr/share/cb/integrations/cbtaxii/cbtaxii -c /etc/cb/integrations/cbtaxii/cbtaxii.conf --export
Build gotchas
If this connector is going to run on Centos 6 then you need to use the source package of lxml from pip.
Use this command to grab python requirements:
pip install --no-binary lxml -r requirements.txt