1 files changed, 108 insertions, 0 deletions
diff --git a/doc/userguide/rules/xbits.rst b/doc/userguide/rules/xbits.rst
new file mode 100644
index 0000000..6d45d7b
--- /dev/null
+++ b/doc/userguide/rules/xbits.rst
@@ -0,0 +1,108 @@
+Xbits Keyword
+=============
+
+Set, unset, toggle and check for bits stored per host or ip_pair.
+
+Syntax::
+
+    xbits:<set|unset|isset|isnotset|toggle>,<name>,track <ip_src|ip_dst|ip_pair>;
+    xbits:<set|unset|isset|toggle>,<name>,track <ip_src|ip_dst|ip_pair> \
+        [,expire <seconds>];
+    xbits:<set|unset|isset|toggle>,<name>,track <ip_src|ip_dst|ip_pair> \
+        [,expire <seconds>];
+
+Notes
+~~~~~
+
+-  No difference between using ``hostbits`` and ``xbits``
+   with ``track ip_<src|dst>``
+
+-  If you ``set`` on a client request and use
+   ``track ip_dst``, if you want to match on the server response,
+   you check it (``isset``) with ``track ip_src``.
+
+-  To not alert, use ``noalert;``
+
+- the ``toggle`` option will flip the value of the xbits.
+
+-  See also:
+
+   -  `https://blog.inliniac.net/2014/12/21/crossing-the-streams-in-suricata/ <https://blog.inliniac.net/2014/12/21/crossing-the-streams-in-suricata/>`_
+   -  `http://www.cipherdyne.org/blog/2013/07/crossing-the-streams-in-ids-signature-languages.html <http://www.cipherdyne.org/blog/2013/07/crossing-the-streams-in-ids-signature-languages.html>`_
+
+YAML settings
+-------------
+
+Bits that are stored per host are stored in the Host table. This means that
+host table settings affect hostsbits and xbits per host.
+
+Bits that are stored per IP pair are stored in the IPPair table. This means
+that ippair table settings, especially memcap, affect xbits per ip_pair.
+
+Threading
+---------
+
+Due to subtle timing issues between threads the order of sets and checks
+can be slightly unpredictable.
+
+Unix Socket
+-----------
+
+Hostbits can be added, removed and listed through the unix socket.
+
+Add::
+
+    suricatasc -c "add-hostbit <ip> <bit name> <expire in seconds>"
+    suricatasc -c "add-hostbit 1.2.3.4 blacklist 3600"
+
+If a hostbit is added for an existing hostbit, it's expiry timer is updated.
+
+Remove::
+
+    suricatasc -c "remove-hostbit <ip> <bit name>"
+    suricatasc -c "remove-hostbit 1.2.3.4 blacklist"
+
+List::
+
+    suricatasc -c "list-hostbit <ip>"
+    suricatasc -c "list-hostbit 1.2.3.4"
+
+This results in::
+
+    {
+        "message":
+        {
+           "count": 1,
+           "hostbits":
+                [{
+                    "expire": 89,
+                    "name": "blacklist"
+                }]
+        },
+        "return": "OK"
+    }
+
+Examples
+--------
+
+Creating a SSH blacklist
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Below is an example of rules incoming to a SSH server.
+
+The first 2 rules match on a SSH software version often used in bots.
+They drop the traffic and create an 'xbit' 'badssh' for the source ip.
+It expires in an hour::
+
+    drop ssh any any -> $MYSERVER 22 (msg:"DROP libssh incoming";   \
+      flow:to_server,established; ssh.softwareversion:"libssh";     \
+      xbits:set, badssh, track ip_src, expire 3600; sid:4000000005;)
+    drop ssh any any -> $MYSERVER 22 (msg:"DROP PUTTY incoming";    \
+      flow:to_server,established; ssh.softwareversion:"PUTTY";      \
+      xbits:set, badssh, track ip_src, expire 3600; sid:4000000007;)
+
+Then the following rule simply drops any incoming traffic to that server
+that is on that 'badssh' list::
+
+    drop ssh any any -> $MYSERVER 22 (msg:"DROP BLACKLISTED";       \
+      xbits:isset, badssh, track ip_src; sid:4000000006;)