
The flagmask and the TCP flags
------------------------------

The first version of Perro logged all TCP packets that arrived to
the machine. That was really annoying, because when I was using http/ftp/
telnet/ssh/etc, all TCP packets were logged, producing megabytes of logs.

The second version of the tcp logger had the command line switch "-s" to
log only packets with the TCP flag SYN set to on. That was good, but lot
of attacks, like stealth FIN port scanning were missed, because some
scanning methods used the FIN, RST, URG, PUSH, etc flags to detect open
TCP ports.

Now I changed this behavior, I deleted the "-s" switch of perrotcp
and introduced a new command line switch: "-f flagmask".
Using this option, perrotcp will only log the packets that have
any of the "flagmask" bits set to ON.

There are six TCP flags, each one, of 1 bit long. See the TCP header:

------------ From RFC 793 (TRANSMISSION CONTROL PROTOCOL) --------------

                            TCP Header Format

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          Source Port          |       Destination Port        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        Sequence Number                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Acknowledgment Number                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Data |           |U|A|P|R|S|F|                               |
   | Offset| Reserved  |R|C|S|S|Y|I|            Window             |
   |       |           |G|K|H|T|N|N|                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           Checksum            |         Urgent Pointer        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Options                    |    Padding    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                             data                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

---------------------------------------------------------------------------

The TCP flags are between the "Reserved" and the "Window" field.


Then how do I know what flagmask I need?
----------------------------------------

You must put a 1 at the flag position that you want to log, and a 0
at all others.

Examples:

1) Suppose that you need to log only packets with the SYN flag on. To do
   it you must put a 1 at the SYN flag position and zeros at all other
   positions:

   +-+-+-+-+-+-+
   |U|A|P|R|S|F|
   |R|C|S|S|Y|I|
   |G|K|H|T|N|N|
   +-+-+-+-+-+-+
    0 0 0 0 1 0

   Then, the flagmask is 2, because "0 0 0 0 1 0" is a binary number
   and it is 2 in base 10.

   DUMMY explanation:
   
    Write this at the command line:

       # perrotcp -lw -f 2
                     ^^^^^ <- "-f flagmask"

   Now all packets that arrives that have the SYN flag on will be logged,
   all other packets will be omited.
   

2) Now suppose that you want to log SYN and stealth FIN scannings, you
   must put a 1 at SYN and FIN positions, 0 at all others:

   +-+-+-+-+-+-+
   |U|A|P|R|S|F|
   |R|C|S|S|Y|I|
   |G|K|H|T|N|N|
   +-+-+-+-+-+-+
    0 0 0 0 1 1  

   Then flagmask == 3.

   Command line:
      # perrotcp -lw -f 3
   
3) Detecting SYN, stealth FIN and Xmas FIN, URG, PUSH scanning:

   +-+-+-+-+-+-+
   |U|A|P|R|S|F|
   |R|C|S|S|Y|I|
   |G|K|H|T|N|N|
   +-+-+-+-+-+-+
    1 0 1 0 1 1

   Then flagmask == 43.

   Command line:
      # perrotcp -lw -f 43

--------------------------------------------------------------------------

Use the following table to understand more easily what flagmask
you will need:

+---+---+---+---+---+---+----------+-------------------+
|URG|ACK|PSH|RST|SYN|FIN| flagmask | Log only          |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 0 | 0 | 0 | 1 |        1 | FIN               |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 0 | 0 | 1 | 0 |        2 | SYN               |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 0 | 0 | 1 | 1 |        3 | SYN or FIN        |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 0 | 1 | 0 | 0 |        4 | RST               |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 0 | 1 | 0 | 1 |        5 | RST or FIN        |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 0 | 1 | 1 | 0 |        6 | RST or SYN        |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 0 | 1 | 1 | 1 |        7 | RST or SYN or FIN |
+---+---+---+---+---+---+----------+-------------------+
| 0 | 0 | 1 | 0 | 0 | 0 |        8 | PSH               |
+---+---+---+---+---+---+----------+-------------------+
.... and so on..
....
+---+---+---+---+---+---+----------+-------------------+
| 0 | 1 | 0 | 0 | 0 | 0 |       16 | ACK               |
+---+---+---+---+---+---+----------+-------------------+
.....
.....
+---+---+---+---+---+---+----------+-------------------+
| 1 | 0 | 0 | 0 | 0 | 0 |       32 | URG               |
+---+---+---+---+---+---+----------+-------------------+
.....
....
+---+---+---+---+---+---+----------+-------------------+
| 1 | 1 | 1 | 1 | 1 | 1 |       63 | Log all           |
+---+---+---+---+---+---+----------+-------------------+

----------------------------------------------------------------------------

NULL scanning (all flags set to 0):
-----------------------------------

Someone told me that NULL scanning will always get logged, I looked at the
code, tested it, and found that it is true (It is a bug, or... feature).
But when I was going to modify the code, I realized that the programs that
put zeros at the TCP flags were NULL scanners, so there is no need to ignore
those packets. (and I was lazy to think & do the modification).

----------------------------------------------------------------------------

Final words:
------------

I put the line "perrotcp -lw -f 43" at the script LaunchLoggers, to detect
SYN, stealth FIN, and Xmas FIN, URG, PUSH scannings (as said above NULL
scanning will always get logged). So if you didn't understand this file,
you could use the "factory" default.

