From: Jeff Lucovsky <jeff@lucovsky.org>
Date: Wed, 8 May 2019 22:40:05 +0000 (-0700)
Subject: doc: Anomaly logging documentation
X-Git-Tag: suricata-5.0.0-rc1~475
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8a94b93b7b93e00ac9729998728aae4a042dc3cf;p=thirdparty%2Fsuricata.git

doc: Anomaly logging documentation

This changeset adds discussion of anomaly log records and
the anomaly log record format.
---

diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
index 20ecc854a0..5182e05661 100644
--- a/doc/userguide/output/eve/eve-json-format.rst
+++ b/doc/userguide/output/eve/eve-json-format.rst
@@ -109,6 +109,62 @@ the signature.
        "port": 80
      },
 
+Event type: Anomaly
+-------------------
+
+Events with type "anomaly"
+
+Fields
+------
+
+* "type": Either "packet" or "stream". In rare cases, type will be "unknown".
+  When this occurs, an additional field named "code" will be present.
+* "event" The name of the anomalous event. Events of type "packet" are prefixed
+  with "decoder"; events of type "stream" are prefixed with "stream".
+* "code" If "type" is "unknown", than "code" contains the unrecognized event code.
+
+When ```packethdr``` is enabled, the first 32 bytes of the packet are included as a byte64-encoded blob in the main part of
+record.
+
+Examples
+--------
+
+::
+
+	"anomaly": {
+	  "type": "packet",
+	  "event": "decoder.icmpv4.unknown_type"
+	}
+
+	"anomaly": {
+	  "type": "packet",
+	  "event": "decoder.udp.pkt_too_small"
+	}
+
+	"anomaly": {
+	  "type": "packet",
+	  "event": "decoder.ipv4.wrong_ip_version"
+	}
+
+	{
+	  "timestamp": "1969-12-31T16:04:21.000000-0800",
+	  "pcap_cnt": 9262,
+	  "event_type": "anomaly",
+	  "src_ip": "208.21.2.184",
+	  "src_port": 0,
+	  "dest_ip": "10.1.1.99",
+	  "dest_port": 0,
+	  "proto": "UDP",
+	  "packet": "////////AQEBAQEBCABFAAA8xZ5AAP8R1+DQFQK4CgE=",
+	  "packet_info": {
+		"linktype": 1
+	  },
+	  "anomaly": {
+		"type": "packet",
+		"event": "decoder.udp.pkt_too_small"
+	  }
+	}
+
 Event type: HTTP
 ----------------
 
@@ -127,7 +183,7 @@ In addition to these fields, if the extended logging is enabled in the suricata.
 * "status": HTTP status code
 * "protocol": Protocol / Version of HTTP (ex: HTTP/1.1)
 * "http_method": The HTTP method (ex: GET, POST, HEAD)
-* "http_refer": The referer for this action
+* "http_refer": The referrer for this action
 
 In addition to the extended logging fields one can also choose to enable/add from more than 50 additional custom logging HTTP fields enabled in the suricata.yaml file. The additional fields can be enabled as following:
 
diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
index a6a11395cf..7f101b32d2 100644
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -3,7 +3,7 @@
 Eve JSON Output
 ===============
 
-The EVE output facility outputs alerts, metadata, file info and protocol
+The EVE output facility outputs alerts, anomalies, metadata, file info and protocol
 specific records through JSON.
 
 The most common way to use this is through 'EVE', which is a firehose approach
@@ -79,6 +79,27 @@ Metadata::
                 # Log the raw rule text.
                 #raw: false
 
+Anomaly
+~~~~~~~
+
+Anomalies are event records created when packets with unexpected or anomalous
+values are handled. These events include conditions such as incorrect protocol
+values, incorrect protocol length values, and other conditions which render the
+packet suspect. Other conditions may occur during the normal progression of a stream;
+these are termed ```stream``` events are include control sequences with incorrect
+values or that occur out of expected sequence.
+
+Metadata::
+
+        #- anomaly:
+            # Anomaly log records describe unexpected conditions such as truncated packets, packets with invalid
+            # IP/UDP/TCP length values, and other events that render the packet invalid for further processing
+            # or describe unexpected behavior on an established stream. Networks which experience high
+            # occurrences of anomalies may experience packet processing degradation.
+
+            # Enable dumping of packet header
+            # packethdr: no            # enable dumping of packet header
+
 HTTP
 ~~~~