doc/userguide: add tag keyword page

Ticket: #3015.

doc/userguide/rules/index.rst

@@ -42,4 +42,5 @@ Suricata Rules
    datasets
    lua-detection
    differences-from-snort
-   multi-buffer-matching
+   multi-buffer-matching
+   tag

doc/userguide/rules/tag.rst

@@ -0,0 +1,133 @@
+Tag
+===
+
+The `tag` keyword allows tagging of the current and future packets.
+
+Tagged packets can be logged in `EVE` and conditional PCAP logging.
+
+Tagging is limited to a scope: `host` or `session` (flow). When using `host` a
+direction can be specified: `src` or `dst`. Tagging will then occur based on the
+`src` or `dst` IP address of the packet generating the alert.
+
+Tagging is further controlled by count: `packets`, `bytes` or `seconds`. If the
+count is ommited built-in defaults will be used:
+
+- for `session`: 256 packets
+- for `host`: 256 packets for the destination IP of the packet triggering the alert
+
+The `tag` keyword can appear multiple times in a rule.
+
+Syntax
+~~~~~~
+
+::
+
+    tag:<scope>[,<count>, <metric>[,<direction>]];
+
+Values for `scope`: `session` and `host`
+Values for `metric`: `packets`, `bytes`, `seconds`
+Values for `direction`: `src` and `dst`
+
+.. note:: "direction" can only be specified if scope is "host" and both "count"
+   and "metric" are also specified.
+
+Examples
+~~~~~~~~
+
+Keyword::
+
+    tag:session;                # tags next 256 packets in the flow
+    tag:host;                   # tags next 256 packets for the dst ip of the alert
+    tag:host,100,packets,src;   # tags next 100 packets for src ip of the alert
+    tag:host,3600,seconds,dst;  # tags packets for dst host for the next hour
+
+Full rule examples:
+
+.. container:: example-rule
+
+   alert dns any any -> any any (dns.query; content:"evil"; tag:host,60,seconds,src; sid:1;)
+
+.. container:: example-rule
+
+   alert http any any -> any any (http.method; content:"POST"; tag:session; sid:1;)
+
+How to Use Tags
+~~~~~~~~~~~~~~~
+
+EVE
+"""
+
+Tags can be set to generate `EVE` `tag` records:
+
+.. code-block:: yaml
+
+    outputs:
+      - eve-log:
+          enabled: yes
+          filename: eve.json
+          types:
+            - alert:
+                tagged-packets: true
+
+The tagged packets will then be logged with `event_type`: `packet`:
+
+.. code-block:: json
+
+    {
+      "timestamp": "2020-06-03T10:29:17.850417+0000",
+      "flow_id": 1576832511820424,
+      "event_type": "packet",
+      "src_ip": "192.168.0.27",
+      "src_port": 54634,
+      "dest_ip": "192.168.0.103",
+      "dest_port": 22,
+      "proto": "TCP",
+      "pkt_src": "wire/pcap",
+      "packet": "CAAn6mWJAPSNvfrHCABFAAAogkVAAIAG9rfAqAAbwKgAZ9VqABZvnJXH5Zf6aFAQEAljEwAAAAAAAAAA",
+      "packet_info": {
+        "linktype": 1
+      }
+    }
+
+EVE: :ref:`Eve JSON Output <eve-json-output>`
+
+Conditional PCAP Logging
+""""""""""""""""""""""""
+
+Using the conditional PCAP logging option the tag keyword can control which
+packets are logged by the PCAP logging.
+
+.. code-block:: yaml
+
+    outputs:
+      - pcap-log:
+          enabled: yes
+          filename: log.pcap
+          limit: 1000mb
+          max-files: 2000
+          compression: none
+          mode: normal
+          use-stream-depth: no #If set to "yes" packets seen after reaching stream inspection depth are ignored. "no" logs all packets
+          honor-pass-rules: no # If set to "yes", flows in which a pass rule matched will stop being logged.
+          # Use "all" to log all packets or use "alerts" to log only alerted packets and flows or "tag"
+          # to log only flow tagged via the "tag" keyword
+          conditional: tag
+
+PCAP Logging: :ref:`PCAP log <suricata_yaml_pcap_log>`
+
+Tracking by Host/Flow
+~~~~~~~~~~~~~~~~~~~~~
+
+When the tags are using the `session` scope, the tag is added to the
+`Flow` structure. If a packet has no flow, no tagging will happen. No
+errors/warnings are generated for this.
+
+See :ref:`Flow Settings <suricata-yaml-flow-settings>` for managing flow
+limits and resources.
+
+When tags are using the `host` scope, the tag is stored with a `Host`
+object in the host table. The Host table size will affect effectiveness
+of per host tags.
+
+See :ref:`Host Settings <suricata-yaml-host-settings>` for managing host
+table size.