Flow Keywords
=============

Flowbits
~~~~~~~~

Flowbits consists of two parts. The first part describes the action it
is going to perform, the second part is the name of the flowbit.

There are multiple packets that belong to one flow. Suricata keeps
those flows in memory. For more information see
:ref:`suricata-yaml-flow-settings`.  Flowbits can make sure an alert
will be generated when for example two different packets match.  An
alert will only be generated when both packets match. So, when the
second packet matches, Suricata has to know if the first packet was a
match too. Flowbits marks the flow if a packet matches so Suricata
'knows' it should generate an alert when the second packet matches as
well.

Flowbits have different actions. These are:

::

  flowbits: set, name                Will set the condition/'name', if present, in the flow.
  flowbits: isset, name              Can be used in the rule to make sure it generates an alert
                                     when the rule matches and the condition is set in the flow.
  flowbits: toggle, name             Reverses the present setting. So for example if a condition is set,
                                     it will be unset and vice-versa.
  flowbits: unset, name              Can be used to unset the condition in the flow.
  flowbits: isnotset, name           Can be used in the rule to make sure it generates an alert
                                     when it matches and the condition is not set in the flow.
  flowbits: noalert                  No alert will be generated by this rule.

Example:

.. image:: flow-keywords/Flowbit_3.png

When you take a look at the first rule you will notice it would
generate an alert if it would match, if it were not for the 'flowbits:
noalert' at the end of that rule. The purpose of this rule is to check
for a match on 'userlogin' and mark that in the flow. So, there is no
need for generating an alert.  The second rule has no effect without
the first rule. If the first rule matches, the flowbits sets that
specific condition to be present in the flow. Now with the second rule
there can be checked whether or not the previous packet fulfills the
first condition. If at that point the second rule matches, an alert
will be generated.

It is possible to use flowbits several times in a rule and combine the
different functions.

Flow
~~~~

The flow keyword can be used to match on direction of the flow, so to/from
client or to/from server. It can also match if the flow is established or not.
The flow keyword can also be use to say the signature has to match on stream
only (only_stream) or on packet only (no_stream).

So with the flow keyword you can match on:

to_client
  Match on packets from server to client.
to_server
  Match on packets from client to server.
from_client
  Match on packets from client to server (same as to_server).
from_server
  Match on packets from server to client (same as to_client).
established
  Match on established connections.
not_established
  Match on packets that are not part of an established connection.
stateless
  Match on packets that are and are not part of an established connection.
only_stream
  Match on packets that have been reassembled by the stream engine.
no_stream
  Match on packets that have not been reassembled by the stream
  engine. Will not match packets that have been reeassembled.
only_frag
  Match packets that have been reassembled from fragments.
no_frag
  Match packets that have not been reassembled from fragments.

Multiple flow options can be combined, for example::

  flow:to_client, established
  flow:to_server, established, only_stream
  flow:to_server, not_established, no_frag

The determination of *established* depends on the protocol:

* For TCP a connection will be established after a three way
  handshake.

  .. image:: flow-keywords/Flow1.png

* For other protocols (for example UDP), the connection will be
  considered established after seeing traffic from both sides of the
  connection.

  .. image:: flow-keywords/Flow2.png

Flowint
~~~~~~~

For information, read the information on the :doc:`flowint` page.

stream_size
~~~~~~~~~~~

The stream size option matches on traffic according to the registered
amount of bytes by the sequence numbers.  There are several modifiers
to this keyword:

::

  >      greater than
  <      less than
  =      equal
  !=     not equal
  >=    greater than or equal
  <=    less than or equal

Format

::

  stream_size:<server|client|both|either>, <modifier>, <number>;

Example of the stream-size keyword in a rule: