doc: add arp changes

OISF · Mar 20, 2024 · 6f6da48 · 6f6da48
1 parent 686f264
commit 6f6da48
Show file tree

Hide file tree

Showing 4 changed files with 62 additions and 0 deletions.
diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
@@ -3002,3 +3002,47 @@ Example of DHCP log entry (extended logging enabled):
     "client_id":"54:ee:75:51:e0:66",
     "dns_servers":["192.168.1.50","192.168.1.49"]
   }
+
+Event type: ARP
+-----------------
+
+Fields
+~~~~~~
+
+* "hw_type": network link protocol type
+* "proto_type": internetwork protocol for which the request is intended
+* "opcode": operation that the sender is performing (e.g. request, response)  
+* "src_mac": source MAC address
+* "src_ip": source IP address
+* "dest_mac": destination MAC address
+* "dest_ip": destination IP address
+
+Examples
+~~~~~~~~
+
+Example of ARP logging: request and response
+
+::
+
+  "arp": {
+    "hw_type": "ethernet",
+    "proto_type": "ipv4",
+    "opcode": "request",
+    "src_mac": "00:1a:6b:6c:0c:cc",
+    "src_ip": "10.10.10.2",
+    "dest_mac": "00:00:00:00:00:00",
+    "dest_ip": "10.10.10.1"
+  }
+
+::
+
+  "arp": {
+    "hw_type": "ethernet",
+    "proto_type": "ipv4",
+    "opcode": "reply",
+    "src_mac": "00:1a:6b:6c:0c:cc",
+    "src_ip": "10.10.10.2",
+    "dest_mac": "00:1d:09:f0:92:ab",
+    "dest_ip": "10.10.10.1"
+  }
+
diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
@@ -266,6 +266,20 @@ enabled, then the log gets more verbose.
 
 By using ``custom`` it is possible to select which TLS fields to log.
 
+ARP
+~~~
+
+ARP records are logged as one entry for the request, and one entry for
+the response.
+
+YAML::
+
+        - arp:
+            enabled: no
+
+The logger is disabled by default since ARP can generate a large
+number of events.
+
 Drops
 ~~~~~
 

diff --git a/doc/userguide/partials/eve-log.yaml b/doc/userguide/partials/eve-log.yaml
@@ -165,6 +165,8 @@ outputs:
         # BitTorrent DHT logging.
         - bittorrent-dht
         - ssh
+        - arp:
+            enabled: no
         - stats:
             totals: yes       # stats for all threads merged together
             threads: no       # per thread stats

diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst
@@ -50,6 +50,8 @@ Major changes
 - ``SIP_PORTS`` variable has been introduced in suricata.yaml
 - Application layer's ``sip`` counter has been split into ``sip_tcp`` and ``sip_udp``
   for the ``stats`` event.
+- Decoder and logger for ARP protocol has been introduced.
+  Given that ARP can be quite verbose and produce many events, it is disabled by default.
 
 Upgrading 6.0 to 7.0
 --------------------