Unleash the Power of Dockerized Analyzers in 5 Minutes

One of the big improvements you’ll notice in Cortex 3 is the support for dockerized analyzers. And amongst some of their benefits, the installation process has been significantly simplified. So let’s assume you do not want to bang your head against Python, or other library dependencies. Then read one for a way to set up analyzers and run them quickly.

The following instructions have been tested on Ubuntu 18.04. If you already have a Cortex instance up and running, you can jump directly to the docker installation section below.

Install System Packages

Prerequisites

  • Ensure your system contains the required packages:
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common
  • Oh, and Cortex should have access to the internet 😉

Cortex

Configure your system to install packages from TheHive-Project repositories.

echo 'deb https://dl.bintray.com/thehive-project/debian-stable any main' | sudo tee -a /etc/apt/sources.list.d/thehive-project.list
sudo apt-key adv --keyserver hkp://pgp.mit.edu --recv-key 562CBC1C

Install Cortex:

sudo apt-get update
sudo apt-get install cortex

The Cortex files will be put in /opt/cortex. The Cortex binary will be executed using the cortex account.

The configuration file is /etc/cortex/application.conf.

The Cortex log file is /var/log/cortex/application.log.

Docker

We recommend reading the Docker documentation to install the software.

For Ubuntu 18.04, you can run the following commands:

wget -O- https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
sudo apt-get update
sudo apt-get install docker-ce

Use Docker with Cortex

Start by giving the cortex account the permission to run Docker.

usermod -a -G docker cortex

Next, in the Cortex configuration file (/etc/cortex/application.conf) ensure jobs will be executed using Docker:

job {
runner = [docker]
}

Follow the Standard Analyzer Catalog

If you are a complete Cortex noob, please read the Quick Start Guide.

Configure Cortex to get the catalog with up-to-date versions of analyzers. Edit /etc/cortex/application.conf to set the catalog URLs in the analyzer configuration section as shown below:

## ANALYZERS
#
analyzer {
  urls = ["https://dl.bintray.com/thehive-project/cortexneurons/analyzers.json"]
[..]
}

Once Cortex is configured, restart the service with the following command, wait a few seconds and you should be able to connect to Cortex on https://<cortex_host&gt;:9001 et voilà!

sudo service restart cortex

Important Note: The catalog analyzers.json contains information regarding versions of analyzers we consider stable and that are updated with bug fixes. This is typically synchronised with our master branch on Github. When you are using this catalog, you are de facto benefiting from the latest analyzer updates without needing to refresh anything in Cortex or setup again the configuration to get the latest version.

We also provide two additional catalogs:

  • analyzers-stable.json which strictly follows versions of analyzers if you do not want any uncontrolled updates. What does that mean in practice? You will have to click on the Refresh button in Cortex to update your analyzers, disable old ones and enable new versions. Moreover, you will also have to setup again their configuration. Typically, if you installed and setup Cortex with this catalog and the current version of FileInfo analyzers is 6.0, you won’t benefit from the next version, let’s say 6.1, unless you refresh Cortex.
  • analyzers-devel.jsonwhich contains information about new analyzers or version of analyzers that contains code that has been reviewed but not tested enough (or even not tested at all at times) to be deemed ready for production environments. This is typically synchronized with the develop branch of our Github repository.

Same goes for responders. All available catalogs for Cortex are published on bintray so you can choose the one that better fits your needs (or your risk/gambling profile :p).

DigitalShadows Feeder 2.4.5

DigitalShadows2TH 2.4.5, a new version of the DigitalShadows feeder for TheHive, has been released with major improvements.

Source : https://www.bustle.com

Dockerise All The Things!

The most notable one is that you can now use it with docker. Run docker pull thehiveproject/ds2th and create a homedir for configuration and logs.

$ DS2TH_HOMEDIR = /opt/thehive_feeders/Digitalshadows2TH/
$ docker pull thehiveproject/ds2th:latest
$ mkdir -p $DS2TH_HOMEDIR/{config,log}
$ wget -O $DS2TH_HOMEDIR/config/config.py\
https://raw.githubusercontent.com/TheHive-Project/DigitalShadows2TH/master/config.py.template

Edit the config.py before runing the docker command below:

$ docker run --rm --net=host --mount\
type=bind,source="$DS2TH_HOMEDIR"/config,target=/app/config --mount type=bind,source="$DS2TH_HOMEDIR"/log,target=/app/log certbdf/ds2th <OPTIONS>
Quick Installation

If that sounds still complicated, worry not! We also wrote a little program that helps you prepare the environment and install everything. We ensured that it works well on Ubuntu 18.04. The program uses two environment variables to set up everything: FEEDERS_SYSACCOUNT and FEEDERS_HOMEDIR :

$ export FEEDERS_SYSACCOUNT=thehive
$ export FEEDERS_HOMEDIR=/opt/thehive_feeders

There are also sane, default settings in case you did not set any value. DigitalShadows2TH’s home directory will be set to /opt/thehive_feeders/DigitalShadows2TH. To use the script, run the following command line and follow the instructions:

 $ wget -qO- https://raw.githubusercontent.com/TheHive-Project/DigitalShadows2TH/mater/INSTALL/install_with_docker.sh | sudo -E bash -

Custom Case Templates

Previous versions of DigitalShadows2TH allowed only one case template to be associated with alerts created by the feeder in TheHive. Starting from DigitalShadows2TH 2.4.0, you can define a case template for each type of incidents raised by DigitalShadows in the configuration file.

The configuration pertaining to TheHive looks as follows:

TheHive = {
 'proxies':{
     'http': '',
     'https': ''
},
   'url':'THEHIVE_URL',
   'key':'THEHIVE_API_KEY',
   'templates': {
       'default':''
  }
}

Each incident type in DigitalShadows can be associated with a case template in TheHive, for example:

TheHive = {
  'proxies':{
      'http': '',
      'https': ''
  },
    'url':'THEHIVE_URL',
    'key':'THEHIVE_API_KEY',
    'templates': {
        'default':'MY_DEFAULT_CASE_TEMPLATE_FOR_DIGITALSHADOWS_INCIDENTS',
        'DATA_LEAKAGE': 'MY_DATA_LEAKAGE_CASE_TEMPLATE',
        'CYBER_THREAT': 'MY_CYBER_THREAT_CASE_TEMPLATE'
    }
}

A template can be defined for all the following DigitalShadows incident types:

  • DATA_LEAKAGE
  • CYBER_THREAT
  • PHYSICAL_SECURITY
  • SOCIAL_MEDIA_COMPLIANCE
  • BRAND_PROTECTION
  • INFRASTRUCTURE

A default template can be defined for DigitalShadows incidents. If no template is found for a specific incident type, the feeder looks for the default template. if no default template is found, an empty case will be created by when importing the alert.

Update or Install

If you are not using docker, just pull the repository and update your configuration file with the new templates part for TheHive.

Update your Repository
$ cd /opt/TheHive_feeders/DigitalShadows2TH/
$ git pull

The configuration file has changed, so you need to update yours before running the program. A new templates section has been added for TheHive and the path has changed. It is now in the config/ directory of the project.

Install and Use via the Code Repository
$ cd /opt/TheHive_feeders 
$ git clone https://github.com/TheHive-Project/DigitalShadows2TH.git

After that, follow the prerequisites and edit the configuration file. In /opt/TheHive_feeders/DigitalShadows2TH/config/ copy config.py.template to config.py and modify it.

Use cases and detailed configuration instructions can be found in the README file in the repository.

Running Into Trouble?

Shall you encounter any difficulty, please join our user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We will be more than happy to help!

Here comes the Sun (and TheHive 3.3-RC5)

On February 10, 2019, we released TheHive 3.3-RC2. It contained new features such as bulk alert merging, alert sorting, observable tag autocompletion, exporting case tags to MISP & more. Since then your favourite French code Chefs have been beesy refining TheHive 3.3 through new release candidates while getting Cortex 3 ready for prime time.

Over the weekend, Nabil decided he was not working enough already during the week. So he drained his batteries to the very last drop to release TheHive 3.3-RC5 before he crashed headfirst into his bed for a long, reparative sleep. Cumulatively since RC2, we added several features and squashed 10 bugs as described below.

Note that release candidates are beta software. You can get TheHive 3.3-RC5 from the pre-release, beta repositories. As usual, we encourage you to test it and report any bugs or issues you spot so we can address them before the final release. 

Check TheHive Installation guide for further details.

New Features

  • #485: disable clickable widgets when editing a dashboard.
  • #820: provide direct access to MISP events for those alerts that have been generated from such events.
Direct access to the MISP event from which this alert has been generated from
  • #829: improve password-protected ZIP imports.
  • #831: add auto-completion to case and observable tags in their respective Details pages.
  • #838: when you add an observable that already exists in another case, indicate whether the existing observable is an IOC or not.
  • #870: provide a link to copy the alert ID to the clipboard which allows you to easily manipulate an alert through TheHive4py.
Now the Alert ID can be directly copied to the clipboard without resorting to your browser dev mode
  • #884: add a Related Alerts tab to the Case view.
The new Related Alerts tab in Case View
  • #888: add a new UI configuration admin section. One of the first use cases of this section consist in disabling creating empty cases (i.e. cases not associated with a template). It will be gradually improved with new use cases so speak your mind!
  • #893: disable the case template selection when trying to merge multiple alerts for which no case template exists.
  • #897: mouseover text for alert preview.

Fixed Bugs

  • #856: various fixes related to alert updates and, when applicable, associated cases.
  • #869: use the observable TLP instead of the case TLP to decide whether a Cortex responder could be executed or not.
  • #871: fix log messages for MISP synchronisation.
  • #874: fix typo in alert labels (credits: Zachary Priddy).
  • #877: fix Akka version mismatch (credits: Zachary Priddy).
  • #890: the Hide Empty Case button in the new UI admin section was broken.
  • #894: when clicking on a donut or a widget in the dashboards, this should take you to the search page with predefined filters, without generating errors.
  • #895: exclude responder jobs from search results.
  • #896: dashboard clicks are not correctly translated into tag filters.

Looking for Help?

Something does not work as expected? Then please join our user forum, contact us on Gitter, or send us an email at support@thehive-project.org.