From: Victor Julien <victor@inliniac.net>
Date: Tue, 16 Oct 2018 13:33:53 +0000 (+0200)
Subject: doc/eve: add community id
X-Git-Tag: suricata-4.1.0~79
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=473688746ba34aad0288840993ffe3659b43e568;p=thirdparty%2Fsuricata.git

doc/eve: add community id
---

diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
index 7f823ca673..d990b1e79d 100644
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -3,14 +3,16 @@
 Eve JSON Output
 ===============
 
-Suricata can output alerts, http events, dns events, tls events and file info through json.
+The EVE output facility outputs alerts, metadata, file info and protocol
+specific records through JSON.
 
-The most common way to use this is through 'EVE', which is a firehose approach where all these logs go into a single file.
+The most common way to use this is through 'EVE', which is a firehose approach
+where all these logs go into a single file.
 
 .. literalinclude:: ../../partials/eve-log.yaml
 
 Each alert, http log, etc will go into this one file: 'eve.json'. This file
-can then be processed by 3rd party tools like Logstash or jq.
+can then be processed by 3rd party tools like Logstash (ELK) or jq.
 
 Output types
 ~~~~~~~~~~~~
@@ -265,3 +267,71 @@ Several flags can be specified to control the JSON output in EVE:
           escape-slash: yes
 
 All these flags are enabled by default, and can be modified per EVE instance.
+
+Community Flow ID
+~~~~~~~~~~~~~~~~~
+
+Often Suricata is used in combination with other tools like Bro/Zeek. Enabling
+the community-id option in the eve-log section adds a new ``community_id``
+field to each output.
+
+Example::
+
+    {
+      "timestamp": "2003-12-16T13:21:44.891921+0000",
+      "flow_id": 1332028388187153,
+      "pcap_cnt": 1,
+      "event_type": "alert",
+      ...
+      "community_id": "1:LQU9qZlK+B5F3KDmev6m5PMibrg=",
+      "alert": {
+        "action": "allowed",
+        "gid": 1,
+        "signature_id": 1,
+      },
+    }
+    {
+      "timestamp": "2003-12-16T13:21:45.037333+0000",
+      "flow_id": 1332028388187153,
+      "event_type": "flow",
+      "flow": {
+        "pkts_toserver": 5,
+        "pkts_toclient": 4,
+        "bytes_toserver": 338,
+        "bytes_toclient": 272,
+        "start": "2003-12-16T13:21:44.891921+0000",
+        "end": "2003-12-16T13:21:45.346457+0000",
+        "age": 1,
+        "state": "closed",
+        "reason": "shutdown",
+        "alerted": true
+      },
+      "community_id": "1:LQU9qZlK+B5F3KDmev6m5PMibrg=",
+    }
+
+Options
+"""""""
+
+The output can be enabled per instance of the EVE logger.
+
+The ``community-id`` option is boolean. If set to ``true`` it is enabled.
+The ``community-id-seed`` option specifies a unsigned 16 bit value that
+is used a seed to the hash that is calculated for the ``community-id``
+output. This must be set to the same value on all tools that output this
+record.
+
+YAML::
+
+  - eve-log:
+      # Community Flow ID
+      # Adds a 'community_id' field to EVE records. These are meant to give
+      # a records a predictable flow id that can be used to match records to
+      # output of other tools such as Bro.
+      #
+      # Takes a 'seed' that needs to be same across sensors and tools
+      # to make the id less predictable.
+
+      # enable/disable the community id feature.
+      community-id: false
+      # Seed value for the ID output. Valid values are 0-65535.
+      community-id-seed: 0