Flowbits Detection Capability
-----------------------------

The flowbits detection plugin uses the flow preprocessor to track rule state
during a transport protocol session.  This is most useful for TCP sessions, as
it allows rules to generically track the state of an application protocol.

The general configuration of the flowbits rule option is:

    flowbits:<keyword>[bits/bats>],[<GROUP_NAME>];
    bits ::= bit[|bits]
    bats ::= bit[&bats]

<GROUP_NAME> : This specifies the group to which the flowbits belong. When the
GROUP_NAME isnt specified the flowbits belong to the default group. A particular 
flowbit can belong to more than one group. The group name should be limited to any 
alphanumeric string including periods, dashes, and underscores. 


Flowbits Keywords
-----------------

There are several keywords associated with flowbits, most of the options need a
user defined name for the specific state that is being checked.  This string
should be limited to any alphanumeric string including periods, dashes, and
underscores.  

set
---
This keyword sets bits to group for a particular flow. When no group specified, 
set the default group. This keyword always returns true.

Syntax:
    flowbits:set,bats[,group]
Usage:  
    flowbits:set,bit1,doc;
    flowbits:set,bit2&bit3,doc;
    First rule sets bit1 in doc group, second rule sets bit2 and bit3 in doc group. 
    So doc group has bit 1, bit2 and bit3 set  

setx
---
This keyword sets bits to group exclusively. This clears other bits in group. 
Group must present.This keyword always returns true.

Syntax:
    flowbits:setx,bats,group
Usage:  
    flowbits: setx, bit1, doc
    flowbits: setx, bit2&bit3, doc
    First rule sets bit1 in doc group, second rule sets bit2 and bit3 in doc group.
    So doc group has bit2 and bit3 set, because bit1 is cleared by rule 2.
    
unset
-----
This keyword clears bits specified for a particular flow or clears all bits in the 
group (Group must present). This keyword always returns true.

Syntax:
   flowbits:unset,bats
   flowbits:unset,all,group
   
Usage:  
   flowbits: unset, bit1  
   Clear bit1.
   
   flowbits: unset, bit1&bit2
   After this rule, both bit1 and bit2 are cleared.
   
   flowbits: unset, all, doc
   This clears all bits in the doc group.

toggle
------
If flowbit is set, unset it. If it is unset, set it. Toggle every bit specified or
toggle all the bits in group (Group must be present). This keyword always returns true.

Syntax:  
   flowbits:toggle,bats
   flowbits:toggle,all,group
   
Usage:
   flowbits: toggle, bit1&bit2
   If bit1 is 0 and bit2 is 1 before, after this rule, bit1 is 1 and bit2 is 0.
   
   flowbits:toggle,all,doc
   Toggle all the bits in group doc as described above. 

isset
-----
This keyword checks a bit or several bits to see if it is set.  It returns true or
false based on the following syntax.

Syntax:  
   flowbits:isset, bits => Check whether any bit is set
   flowbits:isset, bats => Check whether all bits are set
   flowbits:isset, any, group => Check whether any bit in the group is set.
   flowbits:isset, all, group => Check whether all bits in the group are set. 
   
Usage
   flowbits:isset, bit1|bit2 => If either bit1 or bit2 is set, return true
   flowbits:isset, bit1&bit2 => If both bit1 and bit2 are set, return true, otherwise false
   flowbits:isset, any, doc => If any bit in group doc is set, return true
   flowbits:isset, all, doc => If all the bits in doc group are set, return true 

isnotset
--------
This keyword is the reverse of isset.  It returns true if isset is false, it returns
false if isset is true. Isnotset works on the final result, not on individual bits.

Syntax:  
   flowbits:isnotset, bits => Check whether not any bit is set
   flowbits:isnotset, bats => Check whether not all bits are set
   flowbits:isnotset, any, group => Check whether not bit in the group is set.
   flowbits:isnotset, all, group => Check whether not all bits in the group are set. 
   
Usage
   flowbits:isnotset, bit1|bit2 => If either bit1 or bit2 is set, return true
   flowbits:isnotset, bit1&bit2 => If both bit1 and bit2 are set, return true, otherwise false
   flowbits:isnotset, any, doc => If any bit in group doc is set, return true
   flowbits:isnotset, all, doc => If all the bits in doc group are set, return true 

noalert
-------
This keyword always returns false.  It allows users to write rules that set,
unset, and toggle bit without generating an alert.  This is most useful
for writing flowbit rules that set bit on normal traffic and significantly reduces 
unwanted alerts.  There is no bit specified with this keyword.

Usage:  flowbits:noalert;

reset
-----

This keyword resets all of the states on a given flow if no group specified, otherwise, 
reset all the bits in a group. This always returns true.  There is no bit specified with
 this keyword.

Syntax: 
   flowbits:reset[,group]

Usage:  
   flowbits:reset => reset all the bits in the flow
   flowbits: reset, doc => reset all the bits in the doc group

Sample Rules
------------
alert tcp any 143 -> any any (msg:"IMAP login"; content:"OK LOGIN"; flowbits:set,logged_in;)
alert tcp any any -> any 143 (msg:"IMAP lsub"; content:"LSUB"; flowbits:isset,logged_in;)
alert tcp any any -> any 143 (msg:"IMAP LIST WITHOUT LOGIN"; content:"LIST"; flowbits:isnotset,logged_in;)
alert tcp any any -> any any (msg:"JPG transfer"; content:".JPG"; nocase; flowbits:set,http.jpg,file_type;)
