OwlH Documentation home¶

About OwlH¶

v0.14.x

This picture will summarize the process we are working in.

Getting Started with OwlH¶

Components¶

OwlH will help to integrate and manage multiple NIDS solutions, providing a centralized management solution. To accomplish this, we deploy different components.

OwlH provides flexibility and scalability to be integrated with 3rd party solutions as Moloch for forensics and many others. You can grow as needed in your network.

OwlH Master¶

Is an appliance running the centralized management API. All centralized stuff happens here. configurations, synchronizations.

see more about OwlH Master

OwlH Node¶

Is an appliance that will include NIDS software as Suricata and/or Zeek. This appliance will be able to listen network traffic, analyze it and forward analysis results to an storage and visualization platform like ELK or Splunk. It also helps with network traffic transport in our Software TAP configuration

see more about OwlH Node

OwlH UI¶

The graphical User Interface that will provide an easy access and visualization of all management capabilities

see more about OwlH User Interface

OwlH Client¶

Small and light weight client used to transport traffic from servers to an OwlH Node or OwlH Master when there is no way to access directly network traffic, ex. Cloud environments.

see more about OwlH Client

Check our Github repos

Capabilities¶

NIDS and Traffic analysis support¶

Suricata Management

Zeek Management

Moloch Management

Top capabilities¶

OpenRules

Analyzer

Groups

Traffic transport and management¶

Software TAP NODE side

Software TAP MASTER side

Traffic dispatcher MASTER side

Traffic Forwarder CLIENT side (Linux - Windows)

OwlH Plugins¶

MAC management

Known Ports management

DNS data exfiltration analysis

Others¶

RBAC management

User Authentication using LDAP

Change Control records

Internal incident records

OwlH software update

Architecture¶

Standard data flow¶

Inside OwlH Node¶

Traffic analysis by NIDS

NIDS output analysis and enrichment with OwlH Analyzer

Used ports¶

Thanks to our flexible architecture, we can adapt to any scenario. Here we have some samples of running environments:

Scenarios

Check our Github repos

Install OwlH¶

OwlH Installer¶

Install your OwlH components and related services with OwlH Installer.

OwlH Installer

Install components¶

Standard Installation¶

Review your scenario an use these guides to help you to deploy

OwlH Master

OwlH Node

OwlH UI

OwlH Client

Advanced Installation¶

See more installation options available.

Advanced installation

Configure¶

User Interface - APP

API description

Visualization¶

OwlH dashboards integration Wazuh-ELK

Appendices¶

main requirements

Update and upgrade OwlH¶

OwlH components¶

OwlH Master

OwlH Node

OwlH UI

OwlH Client

User Manual¶

First configuration¶

User Interface¶

Access to your UI/APP
Register a node
Create a ruleset for suricata
- Create a ruleset source
- Create a local ruleset
- Apply ruleset to a node or group of nodes

Analyzer¶

Enable Analyzer

Suricata¶

Configure Suricata

Zeek¶

Configure Zeek as standalone

Wazuh¶

Configure Wazuh to read the OwlH Analyzer output alerts.json file

Configuration Files¶

API service configuration files¶

Node configuration¶

appname = OwlHnode
runmode = dev
autorender = false
copyrequestbody = true
EnableDocs = true
ListenTCP4 = true
EnableHTTP = false
EnableHTTPS = true
HTTPSAddr = "0.0.0.0"
HTTPSPort = 50002
HTTPSCertFile = "conf/certs/ca.crt"
HTTPSKeyFile = "conf/certs/ca.key"
EnableDocs = true

Master configuration¶

appname = OwlHmaster
runmode = dev
autorender = false
copyrequestbody = true
EnableDocs = true
ListenTCP4 = true
EnableHTTP = false
EnableHTTPS = true
HTTPSAddr = "0.0.0.0"
HTTPSPort = 50001
HTTPSCertFile = "conf/certs/ca.crt"
HTTPSKeyFile = "conf/certs/ca.key"
EnableDocs = true

Main Configuration files (main.conf)¶

there are main.conf files in owlh node and owlh master

you can find details about each file here:

Master Main Configuration file¶

this is master main.conf file description

If you need help¶

email our support team - support@owlh.net
join OwlH slack - OwlH Slack workspace
ask for professional support and services - prohelp@owlh.net

OwlH - current v0.14.x - Mar - OwlH Changelog

documentation last updated - Jul 06, 2020

Node Main Configuration file¶

Global settings¶

Suricata¶

Zeek¶

Wazuh¶

Software TAP¶

Data Bases¶

Analyzer¶

analyzer

If you need help¶

email our support team - support@owlh.net
join OwlH slack - OwlH Slack workspace
ask for professional support and services - prohelp@owlh.net

OwlH - current v0.14.x - Mar - OwlH Changelog

documentation last updated - Jul 06, 2020

Analyzer configuration file¶

{
  "enable":true,
  "outputfile":"/var/log/owlh/alerts.json",
  "prefilterfile":"conf/prefilters.json",
  "postfilterfile":"conf/postfilters.json",
  "tagsfile":"conf/tags.json",
  "srcfiles": [
      "/var/log/suricata/eve.json",
      "/usr/local/zeek/logs/current/conn.log",
      "/usr/local/zeek/logs/current/dns.log"
  ],
  "feedfiles": [
      {
          "feedfile":"/usr/local/owlh/src/owlhnode/conf/feeds/otx.feed",
          "workers":4
      },
      {
          "feedfile":"/tmp/local.feed"
      },
      {
          "feedfile":"/usr/local/owlh/src/owlhnode/conf/feeds/xforce.feed",
          "workers":4
      },
      {
          "feedfile":"/usr/local/owlh/src/owlhnode/conf/feeds/falcon.feed",
          "workers":4
      }
  ]
}

OwlH API¶

The OwlH API is an open source RESTful API that allows for interaction with the OwlH Master and OwlH Node components from a web browser, command line tool like cURL or any script or program that can make web requests. The OwlH UI and APP relies on this totally. Use the API to easily perform everyday actions like adding a node, restarting the services or looking up status details.

OwlH MASTER RESTful API¶

Note

Work in progress.

OwlH NODE RESTful API¶

Note

Work in progress.

Troubleshooting¶

Warning

work in progress…

Note

If you are missing something in this documentation, please say hello in our slack #doc channel and let us know what is missing or should be good to have.

join OwlH slack - OwlH Slack workspace

OwlH Node¶

Suricata doesn’t create alerts

OwlH Master¶

OwlH UI¶

Looking for…¶

OwlH and Suricata¶

As usual, please keep in contact if there is any clarification or help needed.

email our support team - support@owlh.net
join OwlH slack - OwlH Slack workspace
ask for professional support and services - prohelp@owlh.net

Main steps¶

Install Suricata from OwlH Script
Default settings when you install from OwlH script
- configuration files
- rules folder
- bpf file and folder
- socket - PID files
Choose between Suricata management models
- Manage by OwlH
- Expert mode

Suricata output with OwlH¶

Standard eve.json

Socket output

Suricata Rules¶

Use OpenRules to:

create local rulesets based on 3rd party rulesets and custom rules

synchronize each local ruleset with one or mode nodes

schedule ruleset update

edit rules from User Interface

enable or disable rules

search rules and find where are rules installed and stored

see OpenRules

OwlH and Zeek¶

Integration Logical Diagram¶

Components¶

OwlH Node - Zeek IDS and Wazuh Agent
Wazuh Manger
Logstash Server
Elastic and Kibana Server

Let’s see what we need to modify on each component to be able to manage this Bro and Wazuh integration.

Configure - Zeek - OwlH Node¶

This system will require Bro working of course, and Wazuh agent installed. OwlH instructions will help to configure both Bro and Wazuh agent.

Zeek Logs Output format to JSON¶

Option 1 - Modify ASCII writer output¶

you can load the json_logs.bro configuration that will tell ASCII writer to write output in JSON format. You must include following line in your .bro configuration files. It can be /etc/bro/site/local.bro or you can follow our recomendation and write the configs in owlh.bro file (please, see below).

This will modify output and will store just json output, you won’t have ASCII output.

@load tuning/json_logs.zeek

Zeek Event Enritchment to help Wazuh ruleset¶

It is a good idea to help wazuh rules to do their job, to include a field that will identify what kind of log line we are analyzing. Bro output doesn’t include that info per line by default, so we are going to help wazuh by including the field ‘bro_engine’ that will tell wazuh what kind of log is it.

We are using redef function to include a custom field for each ::Info record of each Protocol. Here are just a few of them, we will include more by default in next releases.

redef record DNS::Info += {
    bro_engine:    string    &default="DNS"    &log;
};
redef record Conn::Info += {
    bro_engine:    string    &default="CONN"    &log;
};
redef record Weird::Info += {
    bro_engine:    string    &default="WEIRD"    &log;
};
redef record SSL::Info += {
    bro_engine:    string    &default="SSL"    &log;
};
redef record SSH::Info += {
    bro_engine:    string    &default="SSH"    &log;
};

Loading Zeek customizations at Zeek start¶

We include all OwlH customizations in OwlH_*.bro files, that helps to have a clear view of what OwlH does as well as we hope it will simplify configuration management.

Under /etc/bro/site we will create two files

owlh.bro - Will include JSON call and @load for bro_engine field definition.
owlh_types.bro - Will include all redef statments

You will only need to load OwlH.bro at the end of your local.bro file to include all these configurations

@load /etc/bro/site/OwlH.bro

owlh.bro looks like:

@load tuning/json-logs.zeek
@load owlh.zeek

and owlh.zeek:

redef record DNS::Info += {
    bro_engine:    string    &default="DNS"    &log;
};
redef record Conn::Info += {
    bro_engine:    string    &default="CONN"    &log;
};
redef record Weird::Info += {
    bro_engine:    string    &default="WEIRD"    &log;
};
redef record SSL::Info += {
    bro_engine:    string    &default="SSL"    &log;
};
redef record SSH::Info += {
    bro_engine:    string    &default="SSH"    &log;
};

Review your Kibana Dashboard¶

for integration with wazuh-elk you will need to verify that OwlH filebeat Module is loaded in Wazuh Manager servers and OwlH elasticsearch template and kibana dashboards are loaded.

Configure and integrate with Wazuh-ELk

And that’s all folks.

OwlH and Moloch¶

Configure Moloch¶

Install it on Master

Install in a remote server

Moloch in Master¶

Configure Moloch to read from owlh interface

Configure STAP on Master to collect socket and replay to owlh interface

Moloch in remote server¶

Configure NFS to publish a PCAP folder

Configure Master to connect to Moloch server PCAP folder

Configure OwlH Master Dispatcher to include Moloch PCAP folder in the pool

Configure STAP on Master to collect socket and write to PCAP

Use Cases¶

What do you want to achieve with NIDS platform in your Network?

BASIC¶

Monitor a single server traffic

Monitor traffic from one or multiple network segments using a SPAN/Mirror Port

ADVANCED¶

I have some remote/cloud servers but I can’t use SPAN/Mirror facilities and I need to monitor server’s traffic

Transport traffic from remote servers in cloud environment for analysis, storage and forensic

We have an hybrid cloud (AWS, Google Cloud, AZURE) and on-premises environment and need a centralized NIDS management and security view

INTEGRATE WITH WAZUH¶

Integrate with Wazuh

This will help you:

Just send default Suricata alerts to Wazuh-ELK

Unify Suricata and Zeek outputs, send to Wazuh-ELK and visualize with some cool dashboard

CHANGELOG¶

As per our latest version, in OwlH solution you may find:

OwlH - current v0.14.x - Mar - OwlH Changelog

If you need help¶

email our support team - support@owlh.net
join OwlH slack - OwlH Slack workspace
ask for professional support and services - prohelp@owlh.net

OwlH - current v0.14.x - Mar - OwlH Changelog

documentation last updated - Jul 06, 2020

email our support team - support@owlh.net
join OwlH slack - OwlH Slack workspace

documentation last updated - Jul 06, 2020