Cortex4py 2 is Out!

Cortex, a free, open source software allows security analysts and threat hunters to analyze and enrich observables (IP addresses, hashes, domains, …) collected in the course of an investigation or received from third parties, for example through MISP, the de facto standard for threat sharing.

On March 29, 2018, we released Cortex 2, a major improvement over the previous version which brought, among other cool features, authentication, caching, multi-tenancy (RBAC) and rate limiting. Instead of deploying several Cortex 1 instances behind reverse proxies which would implement authentification, administrators can deploy a single Cortex 2, create multiple organizations and serve the needs of various information security populations while enjoying extra features.

On May 31, 2018, we published a brand new API guide so that developers can take advantage of the powerful REST API of the product. Sadly, Cortex4py, the FOSS Python library we provide to interact with the API was not compatible with Cortex 2. Until today.

Thanks to the hard work of our dear Nabil Adouani, we are happy to announce the immediate availability of Cortex4py 2.0.0, a complete rewrite of the library in Python 3. Cortex4py 2.0.0 is fully compatible with Cortex 2. However, it doesn’t work with Cortex 1.

While TheHive, the highly popular free and open source Security Incident Response Platform (SIRP) we develop has native support for many Cortex 2 instances, Python developers can leverage Cortex4py to interact with Cortex 2, manage organizations, users, analyzer configurations and analyze observables at scale from alternative SIRPs, SIEMs or custom scripts thanks to the 83 analyzers Cortex 2 has as of June 18, 2018.

Screen Shot 2018-06-18 at 20.01.27.png
Cortex 2: there is more than one way to interact with it

Use It

To install Cortex4py, use PIP3:

$ sudo -H pip3 install cortex4py

If you are using Python on a Windows operating system, please forgo the sudo command.

Usage

Cortex4py 2 comes with a usage guide which includes many examples. For example, if you want to fetch the last 10 successful jobs that have been executed against domain names and display the result summaries of those 10 jobs you could write something like:

Screen Shot 2018-06-18 at 19.58.45.png
Sample Python3 code to retrieve Cortex analyzer results

Migrating from Cortex4py 1

If you have already written scripts using Cortex4py 1.x (for Cortex 1), we tried to keep the already available methods. However, we recommend you adapt your code to leverage the new Cortex4py 2 classes and methods as soon as feasible. Moreover, the existing scripts must be updated to support authentication if you intend to use them with Cortex 2. Please read the Cortex4py 2 usage guide for more information.

Support

Cortex 2.0.0 is brand new software. As such, it might contain bugs and limitations. If you find any or encounter problems, please ask on our user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We are here to help.

Cortex 2, TheHive and a Whole Slew of Updates

After announcing Cortex 2.0.0 and TheHive 3.0.7, the first version of your favorite SIRP that is (supposedly) compatible with the brand-new version of Cortex, last week, we thought it was time to relax and enjoy the upcoming, long Easter weekend, the sunny sky of Paris (if you can pierce the veil of the Forever Grey Cloud™ that is hanging over the city of lights), and great jazz music. Heck, I even tweeted about it … only to be proven wrong by Life (and Murphy).

We literally field tested Cortex 2 for 3 weeks, we squashed bugs here and there, until almost the very last minute before the release. And yet, our QA needs to be improved by leaps and bounds as we had to release Cortex 2.0.1 one day after unveiling 2.0.0 to correct some additional bugs. And then some members of the core team and of our growing user community took it for a spin. And all hell broke lose. Well, almost 🙂

good_code
Source: XKCD

Session collisions (when TheHive and Cortex 2 are used on the same machine), analyzer malfunctions, connectivity problems … issues that were not identified during the testing phase, even in a production environment, where everything worked as expected. And we call this ‘Computer Science’. Right, right…

So we worked hard, took out our Code Hammer (it’s like Thor’s but cyber) and blasted away all the bugs that we found out or that were reported to us (arigato gozaimasu!) and we are happy to announce the immediate availability of Cortex 2.0.2, TheHive 3.0.8, Cortexutils 1.2.3 and Cortex-Analyzers 1.9.2.

TL;DR Install or upgrade Cortex 2.0.2, update Cortexutils, git pull the Cortex-analyzers repo to get the latest version of the repository, upgrade to TheHive 3.0.8, follow the Quick Start Guide and have a drink.

If you have time (which is admittedly quite scarce nowadays), please read on the changelogs:

What’s Next?

As stated in the previous post, we will release a new version of Cortex4py in order to make it compatible with Cortex 2, continue the work we started with our MISP Project friends to support MISP attribute enrichment through Cortex 2 (MISP currently only supports enrichment using Cortex 1), and perform a long-overdue overhaul of our documentation. We will also release a brand new version of TheHive4py.

Last but not least, we’ll take a hard look at ourselves and our QA. You expect us from us high quality and we hold ourselves to high standards. And we will deliver.

Support

Something does not work as expected? You have troubles installing or upgrading? Spotted new bugs? No worries, please open issues on GitHub or comment on existing ones, join our user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We are here to help.

Ali Cortex and the 40 Analyzers

Two months ago, TheHive Chefs announced that Cortex passed the 30 analyzers mark as they added HybridAnalysis, EmergingThreats and Shodan, all three contributed by our continuously growing user community.

It’s 2018 already and to wish you a very happy new DFIR year, Nils and Jérôme got out of their way and reviewed many outstanding pull requests for new analyzers and fixed several bugs. Kudos bees!

Snapseed
© Saâd Kadhi

The latest release of Cortex-Analyzers, v 1.8.0, contains not one, not two, not even three but ten new analyzers! Isn’t that good omen for a fresh new year fighting cybercrime?

The ten new analyzers, described below, are:

  1. Bluecoat: contributed by our longtime friends from CERT La Poste.
  2. C1fApp: submitted by Dimitris Lambrou.
  3. Censys.io: developed by Nils Kuhnert, now a full member of TheHive Project, on behalf of CERT-Bund.
  4. MISP WarningLists: Nils strikes again (watch out Jérôme! the youngster is gonna leave you way behind ;).
  5. Onyphe: contributed by Pierre Baudry and Adrien Barchapt. It comes in five different flavors.
  6. PayloadSecurity: submitted by Emmanuel Torquato. The analyzer comes in two flavors.
  7. Robtex: added by… Nils again! It has three flavors.
  8. SinkDB: guess who developed that one? Wow, impressive! How did you figure it out? Yes, Nils!
  9. Tor Blutmagie: contributed by Marc-André Doll.
  10. Tor Project: also contributed by Marc-André Doll.

We would like to wholeheartedly thank all the individuals and teams listed above for their invaluable contributions. So a big merci for your work!

Bluecoat

The Bluecoat analyzer queries the Symantec – previously known as Bluecoat – WebPulse site review API for the currently assigned site category of URLs or domains. The analyzer needs no further configuration. When executed through TheHive, the analyzer produces short and long reports as shown below:

firefox_2018-01-10_11-02-03

Bluecoat Analyzer
TheHive: Bluecoat 1.0 Analyzer – Short and Long Report Samples

C1fApp

The C1fApp analyzer queries the C1fApp service, an Open Source threat feed aggregation application, using the API for IP addresses, domains and URL.

Before using the analyzer, you need to create an account on the C1fApp website and get the associated API key which you’ll need to provide as a value for the key parameter of the analyzer config section of /etc/cortex/application.conf as shown below. Once you’ve done so, you’ll need to restart Cortex.

 C1fApp {
     service="query"
     key="<insert API key here>"
     url="https://www.c1fapp.com/cifapp/api/"
 }

When launched using TheHive, the analyzer produces short and long reports such as the following:

sc-short-c1fapp.png

sc-long-c1fapp.png
TheHive: C1fApp 1.0 Analyzer – Short and Long Report Samples

Censys.io

Censys.io continually monitors every reachable server and device on the Internet, so you can search for them and analyze them in real time. Using the corresponding analyzer, information about a website certificate can be obtained using the associated IP, domain or certificate hash.

In order to use this analyzer, an account at censys.io has to be registered and the API ID and secret need to be added to the Cortex configuration file:

Censys {
    uid="<Your ID here>"
    key="<Your secret here>"
}

Once done, you’ll have to restart Cortex. When ran from TheHive, the analyzer produces short and long reports such as the following:

Censys Short

Censys.io Analyzer
TheHive: Censys 1.0 Analyzer – Short and Long Report Samples

Details about the ports can be obtained with a click on the specific button.

MISP WarningLists

In order to detect false positives soon enough in the analysis process, our good friends at the MISP Project published their so called warning lists which contain lists of well-known services or indicators.

This analyzer queries observables against the MISP warning lists. Observables can be an IP address, a hash, a domain, a FQDN or a URL.

To iterate through all the warning lists, the repository itself must be available on the Cortex instance:

git clone https://github.com/MISP/misp-warninglists

We highly recommend you create a cron entry or use a similar mechanism to keep the lists fresh. While the default path for the lists is the misp-warninglists subdirectory it can be adjusted in the configuration file:

 MISPWarningLists {
     path = "/path/to/misp-warninglists/repository" # Default: "misp-warninglists"
 }

When called from TheHive, the analyzer produces short and long reports as shown below:

firefox_2018-01-10_11-01-46

MISP Warninglists Analyzer
TheHive: MISP WarningLists 1.0 Analyzer – Short and Long Report Samples

As you can see, The MISP WarningLists analyzer checks if the repository is up-to-date 😉

Onyphe

The Onyphe analyzer leverages Onyphe’s API to query the service, which provides data about the IP address space and the publicly available information in a single, handy location.

The service comes in five flavors:

  • Onyphe_Forward: retrieves forward DNS lookup information we have for the given IPv4/IPv6 address with history of changes.
  • Onyphe_Geolocate: retrieves geolocation information for the given IPv4/IPv6 address.
  • Onyphe_Ports: retrieves synscan information we have for the given IPv4/IPv6 address with history of changes.
  • Onyphe_Reverse: retrieves reverse DNS lookup information we have for the given IPv4/IPv6 address with history of changes.
  • Onyphe_Threats: retrieves Onyphe threats information on anIPv4/IPv6 address with associated history.

To use the analyzer, you need to create an account on the Onyphe website. Provide the API key associated with your account as a value for the key parameter and add the lines below to the config section of /etc/cortex/application.conf then restart the cortex service.

Onyphe {
    key = "<insert API key here>"
}

When ran from TheHive, the analyzer produces short and long reports such as the following:

sc-short-onyphe.png

sc-long-onyphe.png
TheHive: Onyphe 1.0 Analyzer – Short and Long Report Samples

PayloadSecurity

The PayloadSecurity analyzer let you submit observables to a on-premises PayloadSecurity instance. To use it, you need to create an account on the PayloadSecurity service. Provide the API/secret pair as  values for the key and secretparameters, collect the URL and environmentid of the service,  and add the lines below to the ​​config section of  /etc/cortex/application.conf. Then restart the cortex service.

PayloadSecurity {
    url = "<insert URL here>"
    key="<insert API key here>"
    secret="<insert secret here>"
    environmentid="<insert environmentid here>"
    verifyssl=True
}

When launched through TheHive, the analyzer produces short and long reports such as the following:

sc-short-payloadsecurity.png

sc-long-payloadsecurity.png
TheHive: PayloadSecurity 1.0 Analyzer – Short and Long Report Samples

Robtex

When collecting data about IPs, domains and FQDNs, Robtex can be a good source of information. According to their statistics, they logged over 20 billion DNS resource records. The corresponding analyzer comes in three flavors:

  • Robtex_Forward_PDNS_Query: checks domains/FQDNs using the Robtex Passive DNS API
  • Robtex_IP_Query: checks IPs using the Robtex IP API
  • Robtex_Reverse_PDNS_Query: checks IPs using the Robtex reverse Passive DNS API

The analyzer uses the free Robtex API which needs no subsequent configuration. However, the free API limits the rate and amount of returned data.

When executed using TheHive, the analyzer produces short and long reports such as the following:

Robtex Short

Robtex Analyzer
TheHive: Robtex 1.0 Analyzer – Short and Long Report Samples

SinkDB

SinkDB is a private service provided by abuse.ch which collects sinkholed IPs. Access to the service is allowed to trusted partners only. If you think you qualify, you can request an access using the form available on the SinkDB website. This is most likely only granted to certain CSIRTs and CERTs and not to individuals.

Provide the API key associated with your account as a value for the key parameter and add the lines below to the config section of /etc/cortex/application.conf then restart the cortex service.

SinkDB {
    key="<insert API key here>"
}

When ran from TheHive, the analyzer produces short and long reports such as the following:

SinkDB Short True

SinkDB Long
TheHive: SinkDB 1.0 Analyzer Short and Long Report Samples

Tor Blutmagie

Tor Blutmagie analyzer extracts data from torstatus.blutmagie.de  and checks if an observable is linked to a Tor node. The observable can be an IP address, a FQDN or a domain.

In order to check if an IP, domain or FQDN is a Tor exit node, this analyzer queries the Tor status service at Blutmagie.de. The analyzer uses a caching mechanism in order to save some time when doing multiple queries, so the configuration includes parameters for the cache directory and the caching duration.

Provide the lines below to the config section of /etc/cortex/application.conf then restart the cortex service.

TorBlutmagie {
    cache {
        duration=3600
        root=/tmp/cortex/tor_project
    }
}

When ran from TheHive, the analyzer produces short and long reports such as the following:

firefox_2018-01-10_11-01-55

Tor Blutmagie Analyzer

Tor Blutmagie Analyzer (2)
TheHive: Tor Blutmagie 1.0 Analyzer – Short and Long Report Samples

Tor Project

Tor Project analyzer has also been contributed by Marc-André Doll. As the above analyzer, this one checks if an observable is a Tor exit node. This time, however, the source of information is the official Tor network status which can be queried for IP addresses only.

The accepts another parameter, ttl, which is the threshold in seconds for exit nodes before they get discarded. Provide the lines below to the config section of /etc/cortex/application.conf then restart the cortex service.

TorProject {
    cache {
        duration=3600
        root=/tmp/cortex/tor_project
        ttl=86400
    }
}

When ran from TheHive, the analyzer produces short and long reports such as the following:

TorProject Short

Tor Project Analyzer
TheHive: Tor Project 1.0 Analyzer – Short and Long Report Samples

Additional Fixes and Improvements

  • #141: Joe Sandbox analyzer now supports API version 2
  • #158: Fix mode when creating FireHOL ipset directory
  • #162: Fix Snort alerts in Cuckoo analyzer
  • #149: Fix the VirusShare hash downloader

Please note that when we fixed the bug in the shell script of VirusShare analyzer, the original Python script was removed.

Update TheHive Report Templates

If you are using TheHive, get the last version of  the report templates and import them into TheHive.

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!

Correction: January 12, 2018
The post was updated to add the full name of the author of the PayloadSecurity analyzer.

TheHive4py 1.4.0 Released

Version 1.4.0 of the Python API client for TheHive is now available. It is compatible with the freshly released Cerana (TheHive 3.0.0).

We’d like to thank Nick Pratley, a frequent contributor, Bill Murrin, Alexander Gödeke and “srilumpa” for their code additions and documentation.

To update your existing package:

$ sudo pip install thehive4py --upgrade

If you are just getting started with TheHive4py, you can forgo the --upgrade at the end of the command above.

New Features

  • #5: Add a method to update a case, contributed by Nick Pratley
  • #34: Add a get_task_logs method in order to obtain all the task logs associated with a given taskId. Contributed by Bill Murrin
  • #37: A new, very cool case helper class by Nick Pratley
  • #39: Add support for custom fields to the case model
  • #40: Ability to run a Cortex analyzer through the API by Alexander Gödeke
  • #45: Simplify case creation when using a template by providing just its name
  • #49: Add a query builder capability to support TheHive’s DSL query syntax

Paris? Are you There?

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

Cortex Hits the 30 Analyzers Mark

Cortex has now 30 analyzers thanks to Daniil Yugoslavskiy, Davide Arcuri and Andrea Garavaglia (from LDO-CERT) as well as our longtime friend Sébastien Larinier. Their contributions, all under an AGPLv3 license, add handy ways to assess observables and obtain invaluable insight to an already solid Threat Intelligence and DFIR toolset.

In addition to these 3 new analyzers, v 1.7.0 of the Cortex-Analyzers repository also fixes a number of bugs and add a few improvements to existing analyzers as well.

To get the new release, go to your existing Cortex-Analyzers folder and run git pull.

HybridAnalysis

The HybridAnalysis analyzer has been contributed by Daniil Yugoslavskiy. It fetches Hybrid Analysis reports associated with hashes and filenames. This analyzer comes in only one flavor called HybridAnalysis_GetReport.

Requirements

You need to have or create a free Hybrid Analysis account.  Follow the instructions outlined on the Hybrid Analysis API page to generate an API key/secret pair. Provide the API key as a value for the key parameter and the secret as a value to the secret parameter, add the lines below to the config section of /etc/cortex/application.conf then restart the cortex service.

HybridAnalysis {
  secret = "mysecret"
  key = "myAPIKEY"
}

When run from TheHive, the analyzer produces short and long reports such as the following:

sc-short-hybridanalysis_1_0.png

TheHive: HybridAnalysis 1.0 Analyzer – Short and Long Report Samples
TheHive: HybridAnalysis 1.0 Analyzer – Short and Long Report Samples

EmergingThreats

The EmergingThreats analyzer has been submitted by Davide Arcuri and Andrea Garavaglia  from LDO-CERT. It leverages Proofpoint’s Emerging Threats Intelligence service to assess the reputation of various observables and obtain additional and valuable information on malware.

The service comes in three flavors:

  • EmergingThreats_DomainInfo: retrieve ET reputation, related malware, and IDS requests for a given domain.
  • EmergingThreats_IPInfo: retrieve ET reputation, related malware, and IDS requests for a given IP address.
  • EmergingThreats_MalwareInfo: retrieve ET details and info related to a malware hash.

Requirements

You need a valid Proofpoint ET Intelligence subscription.  Retrieve the API key associated with your account and provide it as a value to the key parameter, add the lines below to the config section of /etc/cortex/application.conf then restart the cortex service.

 EmergingThreats {
   key="MYETINTELKEYGOESHERE"
 }

When run from TheHive, it produces short and long reports such as the following:

sc-short-ET_1_0.png

sc-long-ET-1_1_0.png

sc-long-ET-2_1_0.png

sc-long-ET-3_1_0.png

sc-long-ET-4_1_0.png

sc-long-ET-5_1_0.png
TheHive: EmergingThreats 1.0 Analyzer – Short and Long Report Samples

Shodan

The Shodan analyzer is the first submission by Sébastien Larinier. It lets you retrieve key Shodan information on domains and IP addresses.

This analyzer comes in two flavors:

  • Shodan_Host: get Shodan information on a host.
  • Shodan_Search: get Shodan information on a domain.

Requirements

You need to create a Shodan account and retrieve the associated API Key. For
best results, it is advised to get a Membership level account, otherwise a free one can be used.

Supply the API key as the value for the key parameter, add the lines below to the config section of /etc/cortex/application.conf then restart the cortex service.

Shodan {
  key= "myawesomeapikey"
}

When run from TheHive, it produces short and long reports such as the following:

sc-short-shodan_1_0.png

sc-long-shodan_1_0.png
TheHive: Shodan 1.0 Analyzer – Short and Long Report Samples

Miscellaneous Fixes and Improvements

  • #100 : support both Cuckoo versions – by Garavaglia Andrea
  • #113 : Cuckoo Analyzer requires final slash – by Garavaglia Andrea
  • #93 : VirusTotal URL Scan Bug
  • #101 : Missing olefile in MsgParser requirements
  • #126 : PhishTank analyzer doesn’t work – by Ilya Glotov

Update TheHive Report Templates

If you are using TheHive, get the last version of  the report templates and import them into TheHive.

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!

Introducing Cortex4py

Following popular demand, the chefs at TheHive Project‘s code kitchen are happy to announce the immediate availability of Cortex4py.

What Is It?

Cortex4py is a Python API client for Cortex, a powerful observable analysis engine where observables such as IP and email addresses, URLs, domain names, files or hashes can be analyzed one by one using a Web interface or en masse through the API.

Cortex4py allows analysts to automate these operations and submit observables in bulk mode through the Cortex REST API from alternative SIRP platforms (TheHive has native support for one or multiple Cortex instances) and custom scripts.

 

Use It

To install the client, use PIP:

$ sudo pip install cortex4py

 

How Much Does it Cost?

Cortex4py is released under an AGPL license as all the other products we publish to help the IR community fight the good fight. So apart from the effort it’ll cost you to install and use, the price of our software is nada, zero, rien. But if you are willing to contribute one way or another, do not hesitate to drop us an email at support@thehive-project.org or contact us via Twitter.

Support

Something does not work as expected? You have troubles installing or upgrading? No worries, please join our  user forum, contact us on Gitter, or send us an email at support@thehive-project.org. We are here to help.

TheHive4py 1.2.2 is Here

It’s a sunny week in Paris, France (not Texas) barring the tropical rain that washed out the city earlier this morning. And when there’s sun in France, there’s happiness and… coding of course (what else?). The French Chefs of TheHive Project seem to be in a good mood (n’est-ce pas Jérôme ?), thanks to the vitamin D extra charge they got for free from the big star up above.

After updating CortexUtils and the analyzers, and releasing Mellifera 12, a new, major version of TheHive, why stop there when you can update TheHive4py as well?

Version 1.2.2 of the Python API client for TheHive is now available. It mainly fixes issues related to missing Python dependencies and adds support for creating alerts containing files for Python 3.

To update your existing package:

$ sudo pip install thehive4py --upgrade

If you are just getting started with TheHive4py, you can forgo the --upgrade at the end of the command above.

Houston? Are you There?

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