******************** IPSpoofingDetector module for NEMEA **********************

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

    1. Module description
    2. How it works
    3. Detection methods
        I.   Bogon/specific prefix detector
        II.  Symetric route checking
        III. New IP address reporting
        IV.  TCP detection method
    4. How to use
    5. Compilation and linking

1. Module desctiption
=====================

    IPSpoofingDetector module implements function for checking the recieved
IPFIX data for Source IP address spoofing. Implementation of the detection 
method is based on article:

    Kováčik Michal, Kajan Michal, Žádník Martin: Detecting IP-spoofing 
    by modelling history of IP address entry points

The article is avalable at the module wiki: 
    https://homeproj.cesnet.cz/projects/traffic-analysis/wiki/IPSpoofingDetector

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

The module works only with non-transit communicaton filtered by preciding 
transit-filter module. Input is the UniRec record in <COLLECTOR_FLOW> format 
as it would have been recieved directly form collector. This record is the 
checked by implemented detection methods and flagged for possible spoofing 
accordingly. After going through all detectors the SPOOF_TYPE item is added to 
the record which holds the result of the detection.

Since the only provides information about potential spoofing the resulting data 
should be evaluated in a module that is able to correlate the result to reports 
from other modules. The result does not give precise information whterher the 
source address is spoofed or not.

3. Detection methods
====================

Based on the arcticle mentioned in description the module implements multiple 
detection methods for spoofing recognition. Currently the module uses three 
of the methods from the article which are:

    I.   Detection based on specific prefixes
    II.  Detection based on routing symmetry
    III. Detection on new IP address count reported to specific prefix
    IV.  Detection based on TCP 3-way handshake biflow

3. I. Bogon/Specific prefix filtering
=====================================
First detector in the detection line works with bogon prefixes (reserved 
address ranges, private ip addresses, loopbacks or other special addresses).
Detector simply tries match the source address from the record to any bogon 
prefix. If the match is found the detector sets the first bit in the result. 

If source IP does not match any of the bogon prefixes but the communication 
is flagged as inbound the the filter tries to match the source address to 
the prefixes from the network where the module is used. This part is based 
on the rule that source address should not be from the range of the "home" 
network. If match is found the same bit is set accordingly.

3. II. Symetric route checking
==============================

Second detector works with rule that if the flow comes from certain link then 
this link should be kept for all communication. For example if the flow comes 
from ACONET link then the flow should use this link for all communication. If 
this condtition is not met with the same flow (the flow with same IP address 
is deteceted on different links) then the second bit in the result is set. 

The filter cannot be initilaized manually so is has learn all the route "on 
the fly". It is using flows which are outbound from the network to fill the 
Link database (represented by prefixes aggregated with 24-bit prefix length 
and BitArray with 1 bit per link). The symmetry check is then performed on 
inbound traffic. To keep the database fresh the entries are updated in 
specified time period. The removal of the entries is provided by container 
itself (cuckoo hash table with disabled rehash feature provides 
pseudo-random removal of the entries).

3. III. New IP address reporting
================================

Currently last detector serves tracks all IP addresses that communicated 
with the prefix from the home network. If the source IP address did not 
communicated with the home network yet then this address is associated 
with the prefix and third bit of the SPOOF_TYPE item will be set. To 
keep the database fresh it uses set of two Bloom filters which are 
swapped every five minutes.

3. IV. TCP detection method
===========================
Every first seen incoming flow (coming to CESNET) is flagged as spoofed
and this flow is stored in hash table. Later if there is response for this flow,
24bit network prefix of this flow is stored in second hash table (table of legitimate prefixes).
Every next incoming flow which source address belongs to any of previously learned
network prefix is legitimate flow (not flagged as spoofed). 


4. How to use
=============

The module is implemented on TRAP platform so you have to specify TRAP 
interfaces correctly. Then you have to specify paths to list of bogon 
prefixes and other specific prefixes. You can also change the refresh 
time for records in symetric link database. The run command should 
look like this:

./ipspoofingdetector -i <trap_interface> -b <bogon_list_file> -c <spec_prefix_file>

Parameter description:
    -i          Trap interface specification (see README in libtrap)
    -b <path>   Text file with bogon prefixes
    -c <path>   Text file wth prefixes specific for network
    -s <num>    Setting of the refresh time for symmetric route database

Files with prefix lists should be in format:
<IPv4 address | IPv6 address>[/<prefix>]\n

If the prefix is not specified then the maximum length is used for 
accrding IP protocol version.

The module can should be connected to the transit-filter to keep the result 
as accurate as possible but you can connect the module directly to 
the collector. But keep in mind that result for transit traffic may be 
inaccurate.

5. Compilation and linking
==========================

No special compilation parameters are needed. For linking add -ltrap 
and path to unirec.o and libcuckoo_hash.a path.
