Cortex API Documentation

TheHive can interact with one or several Cortex instances to analyze observables and aid you in your investigation in the best possible way while taking into account your OPSEC needs. But you don’t need TheHive to unleash the power of Cortex.

Cortex can be used as a standalone product. You can run analyzers on observables you supply using its simple yet useful Web UI. And if you are not using TheHive, you can bridge your SIRP (Security Incident Response Platform) or any other tool with Cortex thanks to its REST API. To do so, please read the API documentation that we have published. And in a very few days, things will get easier as we will release Cortex4py, a Python API client for Cortex.

Let us know if you have any questions or problems on our user forum, on Gitter, or by sending us an email at support@thehive-project.org. We will be more than happy to help you!

TheHive4py 1.1.0 Released

The French chefs at TheHive code kitchen have just updated TheHive4py, our Python API client for TheHive. Version 1.1.0 lets you add an attachment to a task log but also observables, including files, to a case.

Moreover, TheHive4py 1.1.0 supports searching and you can look up cases by using string keywords.

To update your existing package, please use PIP. Shall you encounter any difficulties, do not hesitate to ask on our user forum or contact us at support@thehive-project.org. You can also join our Gitter channel and have a chat with us.

We will continue improving the client to cover most, if not all API calls. TheHive4py will also undergo significant changes in the upcoming weeks to be compatible with Mellifera, our next major release of TheHive, which will feature a brand new alerting framework.

 

Buckfast 1 Released

The French chefs of TheHive Project code kitchen have been pretty busy as of late. After updating most Cortex analyzers and adding PassiveTotal, we have released TheHive4py 1.0.0 last week, shortly followed by a minor update to this new Python API client for you favorite Security Incident Response Platform. Last week, we have also published Cortex 1.0.1.  And here comes Buckfast 1 (TheHive 2.10.1).

This new release fixes a regression introduced by the previous one where the Flow, our Twitter-like live stream feature, won’t open in a new window. Buckfast 1 also fixes an issue related to newly added observable datatypes that non-admins can’t use unless TheHive service is restarted.

Moreover, the OTXQuery analyzer will now display an error in the long report in case the job fails. Pagination buttons were also introduced at the top of a case’s task list to make it easier for analysts to sift through tasks.  We have also removed the Run all analyzers button next to each observable in the observables tab. We deemed this change necessary to avoid cases where analysts would hit it without really thinking about what they are doing. For certain datatypes this could run all of the current 13 analyzers, some of which need a subscription and may eat the team’s query quota pretty fast.

Buckfast 1 can be run from any URL path and not just from the root directory. It will also close all open tasks in merged cases as they are absorbed in the new case resulting from the merge operation. We have fixed other things and added some additional minor features. Please consult the full changelog.

If you are running Buckfast 0 or a previous version, please follow the updating instructions. It is actually extremely simple to update TheHive. If you are doing a fresh installation, we have you covered as well.

Should you encounter any difficulties, please do not hesitate to read the FAQ, ask questions on the user forum or contact us directly at support@thehive-project.org.

Bon appétit !

 

Cortex 1.0.1 Released

If you use Cortex and have been wondering why the Web UI kept scrolling to the bottom of a page once you run an analyzer, that’s because of a tiny but annoying oversight.

Cortex 1.0.1 has been released to fix this issue. To update your current Cortex installation, follow the instructions of the Installation Guide. Before doing so, you may want to grab any job reports that were not executed via TheHive. Cortex 1 has no persistence and restarting the service will wipe out any existing reports.

Enjoy!

Introducing TheHive4py

Following popular demand, the chefs at TheHive Project‘s code kitchen added some icing on an already tasty cake.

We are happy to announce the immediate availability of a Python API client for TheHive dubbed (surprise surprise!) TheHive4py.

What Is It?

TheHive4py allows analysts to create cases in TheHive out of different sources such as… drum roll…email.

For example, a SOC may ask its constituency to send suspicious email reports to a specific mailbox that a script polls at regular intervals. When a new email is received, the script parses it then calls TheHive4py to create a corresponding case in TheHive. Once the case has been created, SOC analysts will get a notification thanks to TheHive’s Flow so they can start investigating the new case.

Work in Progress

TheHive4py is a work in progress. It is considered beta software though we are using it on a regular basis for the use case outlined above. The client doesn’t leverage yet the richness of TheHive’s REST API (which is partially documented) but it should be sufficient in most situations. If not, please feel free to contribute and submit pull requests or request missing features if you are not comfortable with Python.

Use It

To install the client, PIP is your friend as indicated on the GitHub repository.

Mellifera and the Alerting Framework

TheHive4py will be enhanced in order to take advantage of the alerting framework that will be included in Mellifera, the next major version of TheHive (v 2.11).

The alerting framework will allow Mellifera and later releases to receive ‘alerts’ not only from multiple MISP instances, which is already possible with Buckfast and earlier, but also from mailboxes, SIEMs, and other services. Analysts will be able to develop programs that include TheHive4py in order to send an ‘alert’ to TheHive. Mellifera’s Web UI will then allow analysts to pick interesting ‘alerts’ and transform them into cases by a click of a button using pre-defined templates.

Our current target date for releasing Mellifera and the alerting framework is the end of April 2017.

How Much Does it Cost?

TheHive4py is released under an AGPL license as all the other products we publish to help the cyberdefense 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.

Updated Cortex Analyzers + 1

Rejoice! The French chefs of TheHive Project have released an enhanced set of analyzers for Cortex.

All existing analyzers have been updated and bugs have been fixed. In case you missed it, there’s a new PassiveTotal analyzer contributed by Antoine Brodin (Thanks!). This latest addition lets you query 8 PassiveTotal services such as Enrichment, Malware, Osint, Passive DNS, SSL Certificate details and history, Whois details and Unique resolutions.

If you are using TheHive in conjunction with Cortex, please note that there is no short or long report template for the PassiveTotal analyzer hence you’ll see the results in raw format. But don’t let your excitement wind down. Templates will be produced in the upcoming weeks. Word.

To install the new analyzers, grab the Cortex-Analyzers repository and unpack its content (or git pull the master  branch) in your existing /path/to/cortex-analyzers.

The PassiveTotal analyzer requires the passivetotal Python library, a username and an API key. Use the following command lines to install the required library:

sudo pip install passivetotal

Then edit your Cortex configuration file (/path/to/cortex/application.conf) and add the following lines in the analyzer section:

 PassiveTotal {
     key="..."
     username="..."
 }

Please note that you must restart Cortex to take the changes into account. The current version has no persistence so you’ll lose all your existing jobs.

You can find the full installation requirements for Cortex and Cortex-Analyzers on the Cortex wiki pages.

If you’d like to contribute new analyzers, please check whether somebody is already working on them. If not, get acquainted with some of the existing ones by reading their code and open an issue.

If you have any further questions, please do not hesitate to ask on our user forum or contact support@thehive-project.org.

Meet Buckfast & Cortex, the Dynamic Duo

TheHive Project chefs have been busy at the code kitchen, working on a elaborate, very palatable recipe: Buckfast (v 2.10.0), the latest and greatest iteration of your security incident response platform.

Buckfast contains many new features that will hopefully prove useful for our collective fight against cybercrime and other evil. But instead of covering all of them in detail (which will make for a long, long read), we’d like to concentrate on a few ones that we deem very interesting.

Analysis just got better

When you wanted to analyze an observable with previous versions of TheHive, you had to create a case, add the observable to it then select the analyzer(s) you wanted to run. This was rather time-consuming if your purpose was to quickly assess a domain, URL or other types of observables. Sadly, that was the only way to do it as the analysis engine was embedded in the back-end of TheHive.

This also caused some OPSEC issues. For example, if TheHive is inside your corporate network, you may be reluctant to query some services from it as your IP address will be revealed to them. You also had to think carefully on how to implement an analyzer for your sandbox (or any other tool or service) that sits on a separate network.

To address these issues but also allow fellow analysts to unleash the power of the analyzers using different security incident response platforms, we created Cortex.

Architecture.png
TheHive and Cortex Architecture

Besides MISP, Cortex is the perfect companion of TheHive. Starting from Buckfast, you may connect your instance to one or several Cortex servers depending on your OPSEC needs and security requirements.

a-cortex_jobs.png
Available reports can be accessed using the magnifying glass

TheHive comes with a report template engine that allows you to adjust the JSON output of Cortex analyzers to your taste instead of having to create your own parsers. And to give you a head start, we provide templates for all 13 analyzers that Cortex 1.0.0 is shipped with. Ain’t that sweet?

We also made enhancements to the Observables tab in TheHive Web UI to allow you to run all applicable analyzers with a single click!

Analyzers

Since the previous release of TheHive, we have added 5 new analyzers, bringing the total to 13, that you can use by deploying a Cortex instance. We have also made improvements to existing ones. You’ll find the full list on Github. The new additions, some of which were contributed by our user community, are:

  • Abuse Finder: use CERT-SG’s Abuse Finder to find the abuse contact associated with domain names, URLs, IP and email addresses.
  • OTXQuery: query AlienVault Open Threat Exchange for IPs, domains, URLs, or file hashes.
  • PassiveTotal: leverage RiskIQ’s PassiveTotal service to gain invaluable insight on observables, identify overlapping infrastructure using Passive DNS, WHOIS, SSL certificates and more.
  • URLCategory: checks the Fortinet categories of URLs.
  • Phishing Initiative: queries Phishing Initiative to assess whether a URL has been flagged a phishing site.
  • PhishTank: queries PhishTank to assess whether a URL has been flagged a phishing site.

We have also largely improved the former Olevba analyzer and renamed it File_Info. It is in fact our first meta-analyzer as it leverages a collection of tools to parse files in several formats such as OLE and OpenXML to detect VBA macros, extract their source code, generate useful information on PE, PDF files and much more.

Sorting, Filtering and Statistics

Instead of the latest open cases, Buckfast displays everything on the main page and lets you decide how you want to sort and filter the cases. For example, you can display only cases that contain specific tags or that were assigned to a particular incident handler. We have also added quick filters to display open or closed cases as well as the cases that were assigned to you.

Buckfast has also the ability to display simple statistics on cases without launching the Statistics module page.

TH-current_cases_stats.png
Statistics and Filters

 

Avatars

While previous TheHive versions allowed you to assign tasks to fellow handlers, Buckfast lets you also assign a case to a particular person which would ensure that all tasks are dealt with in a timely fashion and help analysts complete the investigation. The case assignees are now visible on the main page thanks to their avatars which they should provide in their user profile page. And before you ask for it, we won’t support animated GIFs. Seriously.

Current_cases.png
The New Main Screen of Buckfast

Download & Try

There are other interesting features that are worth detailing but we’ll keep those for another installment. In the meantime, we highly encourage you to try Buckfast, Cortex or both and let us know what you think.

If you are an existing  TheHive 2.9.x user, we urge you to upgrade to Buckfast and deploy a Cortex instance to use the analyzers.