********************************************************************************
**************************** HeartBleed detector *******************************
********************************************************************************

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

	1. Module description
	2. Interfaces
	3. How it works
	4. Outputs
	5. How to use

Note:
Parts marked as "DEPRECATED" are related to detection, based on condition which
works only if communication is not encrypted. Since other detection conditions
are strong enough, this part of detection algorithm was removed.

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

This module detecting HeartBleed attacks on port 443. Detection is based on
following metrics:
 - difference of request and response sizes.
 (DEPRECATED>> - difference of request real size and payload size. <<DEPRECATED)
 - size of request smaller then minimal request size.
 - suspiciously large messages (responses)

Detection is based on computing attack-score for each pair of communicating
addresses. Every detected event (i.e. successful/unsuccessful attack, possible
false positive, etc) is logged in log file(s). Only events which have
attack-score high enough are reported as alert messages, sent to output
interface. Detection is made every n seconds, where n is size of time
interval of timer.

2. Interfaces
=============
Input: 1 UniRec record in format: "<COLLECTOR_FLOW>,<HEARTBEAT_FIELDS>"
Output: 1 UniRec record in format: "<WARDEN_REPORT>"

3. How it works
===============
Incoming flows (packets) are identified by target IP address (port 443) and
source IP address (possible attacker). Given pair is searched in history or new
record is added. Communication is checked for encryption. Then count of the type
of heartbeat message (request/response) and the sum of size of this type is
increased for this pair. If message was not encrypted then payload size of
message type is increased also.
If message is heartbeat request, it is tested by first detection condition:
 - size of the request smaller, then minimal size of the request - minimal size
   of request is considered as 20B: 1B (type of message) + 2B (size of message)
   + 1B (at least 1B of payload) + 16B (minimal padding size)
 (DEPRECATED>> - real size of the heartbeat message is smaller then size in the
   message - minimal difference will be always 19B at least (20B of minimal
   message size - 1B of payload). There is small tolerance added to this minimal
	difference (since padding could be bigger then 16B) <<DEPRECATED)
Detection of the heartbleed attack is checked by increment of the counter
for given condition type (i.e. request too small), if this condition is broken.
After expiration of the timer (5 minutes by default) the history of flows is
evaluated. Relevant alerts and log entries are added/sent based on this
evaluation. This step start by calculation of score for every pair
source(attacker)-target. This score represents the probability of the attack.
At first, result of introduced condition is checked. If it has been broken,
score is increased by 10 points. Next condition checks sizes of requests and
responses. Because there could be generally more requests then responses, size
of requests is corrected. If differs, there is added 1 to 10 points, based on
this difference. Last condition is checked only in case, that request massages
are missing. In this case the average size of response is checked. If is greater
then threshold (8000B by default), score is increased by 5 points. As the score
is increased, detection filed is set up also. This field identifies on which
condition is based current detection of attack. There is event reported to log
file and if the score of given pair reaches threshold (9 points by default),
alert is sent. Counters of each pair are set to initial values after detection
of the event and given flow is marked as "inactive". This flag is set to
"active" with every packet received. The flow is removed from history of flows,
if no data arrived during next time interval.

4. Outputs
==========
Module producing detection results in log files and by alert messages. Log files
are in the csv format with names "ip_address_of_attacker.log". If module is
compiled with -DGLOBAL_LOG there is "global.log", containing all logged events
also. Format of log files is:
Source IP (only global); Target IP; Request count; Request size sum;
Response count; Response size sum; Req. payload size sum*;
Resp. payload size sum*; Min. size detection count; (DEPRECATED>> Diff. size
detection count <<DEPRECATED); Score; Report count; Logged time <eol>
Alert messages contains this fields:
 - DETECTION_TIME - time of detection of the attack (time of last received
   packet of given pair)
 - WARDEN_TYPE - actually (30.5.2014) general "WT_VULNERABILITY"
 - SRC_IP - IP address of the target
 - PROTOCOL
 - DST_PORT - 443 (https)
 - EVENT_SCALE - count of responses
 - NOTE - more detailed description of the attack in format:
   "HeartBleed: attacker: <SRC_IP, requests: >=<REQ_CNT>, replies: >=<RESP_CNT>,
	 replies size: >=<RESP_SUM_SIZE>, detected_by: <LIST_OF_BROKEN_COND>"

* Set to "-1" if communication was encrypted.

5. How to use
=============
Create directory for log messages:
mkdir my_attack_dir

Run detection module with input data on localhost:7000 and sending outputs on
port 7100:
./heartbleed_detector -i "tt;localhost,7000;7100" -d "path/to/my_attack_dir/"

**************** End of HeartBleed detector README *****************************
********************************************************************************
