﻿**************************** HostStatsNemea module ****************************

Table of Contents
=================

	1. Module description
	2. How it works
	3. How to use

1. Module description
=====================

HostStatsNemea module calculates statistics about network traffic of each 
individual host (IP address) in the network. The statistics are searched 
for suspicious behavior using a simple ruleset. This suspicious behavior 
is stored in a log file.

Currently there are rules for detection of hosts scanning network and for
detection of DoS attackers and victims.


Input interface:    1 ("<COLLECTOR_FLOW>,DIRECTION_FLAGS")
Output interface:   1 ("EVENT_TYPE,TIMESLOT,SRC_IP,DST_IP,SRC_PORT,DST_PORT,
                        PROTOCOL,EVENT_SCALE") (more details below)
Output: log file with detected events

Note: DIRECTION_FLAGS are used to determine the type of flow (request, response,
single flow, not recognize). This UniREC item is generated by FlowDirection
module (recommended) or DedupAggregator module (not implemented yet).

The content of items of the output interface:
Some items may not be filled and these items are set to "zero" value such
as "0.0.0.0" for IPs and "0" for others.
	- EVENT_TYPE - a number of detected event: PORTSCAN(0), PORTSCAN_H(1), 
		PORTSCAN_V(2), DOS(3), DDOS(4), BRUTEFORCE(5), OTHER(6)
	- TIMESLOT - a time of the first occurrence in the reporting period
	- EVENT_SCALE - a intensity of event
	- other items have usual meaning


2. How it works
===============

The module collect global and specific statistics about network traffic of each
IP address. Global statistics means all incoming/outgoing flows/packet/bytes,
incoming/outgoing flows with SYN/ACK/FIN/RST/PSH/URG, the approximate number of
addresses this address communicated with. Some of these statistics are also 
extended by the flow type (e.g. in request flows, in response flows etc.). 
The entire structure of the record (hosts_record_t) is in the source file 
“src/hoststats.h”. Specific statistics (subprofiles) are created according 
to the communication protocol (e.g. SSH, DNS) and the structure of record 
depends on each subprofile. Specific statistics (subprofiles) are available
from the global statistics of each IP address that are stored in cuckoo hash
table.

Note: DNS subprofiles are still in development and therefore are
disabled in a configuration file.

The module consists of two basic threads – manipulating and checking.
    The checking thread periodically checks the statistics data in the table 
by defined period. When a statistic record is too long in the table (active
timeout) or it wasn't updated during specific time (inactive timeout), record is
searched for suspicious behavior using the simple ruleset and added to a list
to remove. Period and active/inactive timeout can be set in the configuration 
file.
    The manipulating thread receives data from the TRAP and updates the global
statistics and statistics in active subprofiles. This thread also removes 
statistics records from the table defined by the list to remove.


3. How to use
=============

Edit the configuration file “hoststats.conf” and especially the line 
"detection-log" with the folder path to save the event log. Use FlowDirection
(recommended) or DedupAggregator (not ready yet) output as an input for this
module and then run module: 

    ./hoststatsnemea -i <trap_interface>

Example:
	Run this module:
	./hoststatsnemea -i "tt;localhost,12346;12347,5"

	Run flowdirection module:
	./flowdirection -i "tt;localhost,12345;12346,5" -u "<COLLECTOR_FLOW>"