]> git.ipfire.org Git - thirdparty/suricata.git/commitdiff
doc: update MQTT configuration
authorSascha Steinbiss <satta@debian.org>
Sun, 12 May 2024 21:14:37 +0000 (23:14 +0200)
committerVictor Julien <victor@inliniac.net>
Tue, 9 Jul 2024 10:15:21 +0000 (12:15 +0200)
doc/userguide/output/eve/eve-json-output.rst
doc/userguide/partials/eve-log.yaml

index e7c9005bac2a533c3b00a8d47384aaf4f8cdb49b..ba42ac56be5fdec3ac9f4a93124776272feec25b 100644 (file)
@@ -281,6 +281,29 @@ YAML::
 The logger is disabled by default since ARP can generate a large
 number of events.
 
+MQTT
+~~~~
+
+EVE-JSON output for MQTT consists of one object per MQTT transaction, with some common and various type-specific fields.
+Two aspects can be configured:
+
+YAML::
+
+        - mqtt:
+            # passwords: yes           # enable output of passwords
+            # string-log-limit: 1kb    # limit size of logged strings in bytes.
+                                       # Can be specified in kb, mb, gb. Just a number
+                                       # is parsed as bytes. Default is 1KB.
+                                       # Use a value of 0 to disable limiting.
+                                       # Note that the size is also bounded by
+                                       # the maximum parsed message size (see
+                                       # app-layer configuration)
+
+The default is to output passwords in cleartext and not to limit the size of
+message payloads. Depending on the kind of context the parser is used in (public
+output, frequent binary transmissions, ...) this can be configured for regular
+``mqtt`` events.
+
 Drops
 ~~~~~
 
index df31c09141e449ca3001363f600cc6355a4248bc..b0104e9a48320a25bb64b189d69c02de1ca50a4d 100644 (file)
@@ -4,8 +4,8 @@ outputs:
       enabled: yes
       filetype: regular #regular|syslog|unix_dgram|unix_stream|redis
       filename: eve.json
-      # Enable for multi-threaded eve.json output; output files are amended
-      # with an identifier, e.g., eve.9.json
+      # Enable for multi-threaded eve.json output; output files are amended with
+      # an identifier, e.g., eve.9.json
       #threaded: false
       #prefix: "@cee: " # prefix to prepend to each log entry
       # the following are valid when type: syslog above
@@ -13,6 +13,7 @@ outputs:
       #facility: local5
       #level: Info ## possible levels: Emergency, Alert, Critical,
                    ## Error, Warning, Notice, Info, Debug
+      #ethernet: no  # log ethernet header in events when available
       #redis:
       #  server: 127.0.0.1
       #  port: 6379
@@ -24,14 +25,48 @@ outputs:
       # Redis pipelining set up. This will enable to only do a query every
       # 'batch-size' events. This should lower the latency induced by network
       # connection at the cost of some memory. There is no flushing implemented
-      # so this setting as to be reserved to high traffic suricata.
+      # so this setting should be reserved to high traffic Suricata deployments.
       #  pipelining:
       #    enabled: yes ## set enable to yes to enable query pipelining
-      #    batch-size: 10 ## number of entry to keep in buffer
+      #    batch-size: 10 ## number of entries to keep in buffer
 
       # Include top level metadata. Default yes.
       #metadata: no
 
+      # include the name of the input pcap file in pcap file processing mode
+      pcap-file: false
+
+      # Community Flow ID
+      # Adds a 'community_id' field to EVE records. These are meant to give
+      # records a predictable flow ID that can be used to match records to
+      # output of other tools such as Zeek (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
+
+      # HTTP X-Forwarded-For support by adding an extra field or overwriting
+      # the source or destination IP address (depending on flow direction)
+      # with the one reported in the X-Forwarded-For HTTP header. This is
+      # helpful when reviewing alerts for traffic that is being reverse
+      # or forward proxied.
+      xff:
+        enabled: no
+        # Two operation modes are available: "extra-data" and "overwrite".
+        mode: extra-data
+        # Two proxy deployments are supported: "reverse" and "forward". In
+        # a "reverse" deployment the IP address used is the last one, in a
+        # "forward" deployment the first IP address is used.
+        deployment: reverse
+        # Header name where the actual IP address will be reported. If more
+        # than one IP address is present, the last IP address will be the
+        # one taken into consideration.
+        header: X-Forwarded-For
+
       types:
         - alert:
             # payload: yes             # enable dumping payload in Base64
@@ -39,66 +74,77 @@ outputs:
             # payload-printable: yes   # enable dumping payload in printable (lossy) format
             # payload-length: yes      # enable dumping payload length
             # packet: yes              # enable dumping of packet (without stream segments)
-            # http-body: yes           # Requires metadata; enable dumping of http body in Base64
-            # http-body-printable: yes # Requires metadata; enable dumping of http body in printable format
+            # metadata: no             # enable inclusion of app layer metadata with alert. Default yes
+            # http-body: yes           # Requires metadata; enable dumping of HTTP body in Base64
+            # http-body-printable: yes # Requires metadata; enable dumping of HTTP body in printable format
+            # websocket-payload: yes   # Requires metadata; enable dumping of WebSocket Payload in Base64
+            # websocket-payload-printable: yes # Requires metadata; enable dumping of WebSocket Payload in printable format
 
             # Enable the logging of tagged packets for rules using the
             # "tag" keyword.
             tagged-packets: yes
-
-            # Configure the metadata to be logged along with an
-            # alert. The following shows the default configuration
-            # which is used if this field is not provided or simply
-            # set to a truthful value. Setting of this section is only
-            # required if you wish to enable/disable specific fields.
-            #metadata:
-
-              # Include the decoded application layer (ie. http, dns)
-              app-layer: true
-
-              # Log the current state of the flow record.
-              flow: true
-
-              rule:
-                # Log the metadata field from the rule in a structured
-                # format.
-                metadata: true
-
-                # Log the raw rule text.
-                raw: false
-
-            # HTTP X-Forwarded-For support by adding an extra field or overwriting
-            # the source or destination IP address (depending on flow direction)
-            # with the one reported in the X-Forwarded-For HTTP header. This is
-            # helpful when reviewing alerts for traffic that is being reverse
-            # or forward proxied.
-            xff:
-              enabled: no
-              # Two operation modes are available, "extra-data" and "overwrite".
-              mode: extra-data
-              # Two proxy deployments are supported, "reverse" and "forward". In
-              # a "reverse" deployment the IP address used is the last one, in a
-              # "forward" deployment the first IP address is used.
-              deployment: reverse
-              # Header name where the actual IP address will be reported, if more
-              # than one IP address is present, the last IP address will be the
-              # one taken into consideration.
-              header: X-Forwarded-For
+            # Enable logging the final action taken on a packet by the engine
+            # (e.g: the alert may have action 'allowed' but the verdict be
+            # 'drop' due to another alert. That's the engine's verdict)
+            # verdict: yes
+        # app layer frames
+        - frame:
+            # disabled by default as this is very verbose.
+            enabled: no
+            # payload-buffer-size: 4kb # max size of frame payload buffer to output in eve-log
+        - 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.
+            #
+            # Anomalies are reported for the following:
+            # 1. Decode: Values and conditions that are detected while
+            # decoding individual packets. This includes invalid or
+            # unexpected values for low-level protocol lengths as well
+            # as stream related events (TCP 3-way handshake issues,
+            # unexpected sequence number, etc).
+            # 2. Stream: This includes stream related events (TCP
+            # 3-way handshake issues, unexpected sequence number,
+            # etc).
+            # 3. Application layer: These denote application layer
+            # specific conditions that are unexpected, invalid or are
+            # unexpected given the application monitoring state.
+            #
+            # By default, anomaly logging is enabled. When anomaly
+            # logging is enabled, applayer anomaly reporting is
+            # also enabled.
+            enabled: yes
+            #
+            # Choose one or more types of anomaly logging and whether to enable
+            # logging of the packet header for packet anomalies.
+            types:
+              # decode: no
+              # stream: no
+              # applayer: yes
+            #packethdr: no
         - http:
             extended: yes     # enable this for extended logging information
-            # custom allows additional http fields to be included in eve-log
+            # custom allows additional HTTP fields to be included in eve-log.
             # the example below adds three additional fields when uncommented
             #custom: [Accept-Encoding, Accept-Language, Authorization]
+            # set this value to one and only one from {both, request, response}
+            # to dump all HTTP headers for every HTTP request and/or response
+            # dump-all-headers: none
         - dns:
-            # Use version 2 logging with the new format:
-            # dns answers will be logged in one single event
-            # rather than an event for each of the answers.
-            # Without setting a version the version
-            # will fallback to 1 for backwards compatibility.
-            version: 2
+            # This configuration uses the new DNS logging format,
+            # the old configuration is still available:
+            # https://docs.suricata.io/en/latest/output/eve/eve-json-output.html#dns-v1-format
+
+            # As of Suricata 5.0, version 2 of the eve dns output
+            # format is the default.
+            #version: 2
 
             # Enable/disable this logger. Default: enabled.
-            #enabled: no
+            #enabled: yes
 
             # Control logging of requests and responses:
             # - requests: enable logging of DNS queries
@@ -111,32 +157,18 @@ outputs:
             # - detailed: array item per answer
             # - grouped: answers aggregated by type
             # Default: all
-            #answer-format: [detailed, grouped]
-
-            # Answer types to log.
-            # Default: all
-            #answer-types: [a, aaaa, cname, mx, ns, ptr, txt]
-        - dns:
-            # Version 1 DNS logger.
-            # Deprecated: Will be removed by May 2022.
-            version: 1
+            #formats: [detailed, grouped]
 
-            enabled: no
-            # control logging of queries and answers
-            # default yes, no to disable
-            query: yes     # enable logging of DNS queries
-            answer: yes    # enable logging of DNS answers
-            # control which RR types are logged
-            # all enabled if custom not specified
-            #custom: [a, aaaa, cname, mx, ns, ptr, txt]
+            # DNS record types to log, based on the query type.
+            # Default: all.
+            #types: [a, aaaa, cname, mx, ns, ptr, txt]
         - tls:
             extended: yes     # enable this for extended logging information
             # output TLS transaction where the session is resumed using a
             # session id
             #session-resumption: no
-            # custom allows to control which tls fields that are included
-            # in eve-log
-            #custom: [subject, issuer, session_resumed, serial, fingerprint, sni, version, not_before, not_after, certificate, chain]
+            # custom controls which TLS fields that are included in eve-log
+            #custom: [subject, issuer, session_resumed, serial, fingerprint, sni, version, not_before, not_after, certificate, chain, ja3, ja3s, ja4]
         - files:
             force-magic: no   # force logging magic on all logged files
             # force logging of checksums, available hash functions are md5,
@@ -146,6 +178,9 @@ outputs:
         #    alerts: yes      # log alerts that caused drops
         #    flows: all       # start or all: 'start' logs only a single drop
         #                     # per flow direction. All logs each dropped pkt.
+            # Enable logging the final action taken on a packet by the engine
+            # (will show more information in case of a drop caused by 'reject')
+            # verdict: yes
         - smtp:
             #extended: yes # enable this for extended logging information
             # this includes: bcc, message-id, subject, x_mailer, user-agent
@@ -159,34 +194,67 @@ outputs:
             # to yes
             #md5: [body, subject]
 
-        # NFS logging.
+        #- dnp3
+        - websocket
+        - ftp
+        - ftp-data
+        - rdp
         - nfs
-        # IKE logging.
+        - smb
+        - tftp
         - ike
-        # BitTorrent DHT logging.
+        - dcerpc
+        - krb5
         - bittorrent-dht
         - ssh
         - arp:
             enabled: no
-        - stats:
-            totals: yes       # stats for all threads merged together
-            threads: no       # per thread stats
-            deltas: no        # include delta values
-            # Don't log stats counters that are zero. Default: true
-            #null-values: false    # False will NOT log stats counters: 0
+        - snmp
+        - rfb
+        - sip
+        - quic
         - dhcp:
-            # DHCP logging.
             enabled: yes
             # When extended mode is on, all DHCP messages are logged
             # with full detail. When extended mode is off (the
             # default), just enough information to map a MAC address
             # to an IP address is logged.
             extended: no
+        - mqtt:
+            # passwords: yes           # enable output of passwords
+            # string-log-limit: 1kb    # limit size of logged strings in bytes.
+                                       # Can be specified in kb, mb, gb. Just a number
+                                       # is parsed as bytes. Default is 1KB.
+                                       # Use a value of 0 to disable limiting.
+                                       # Note that the size is also bounded by
+                                       # the maximum parsed message size (see
+                                       # app-layer configuration)
+        - http2
+        - pgsql:
+            enabled: no
+            # passwords: yes           # enable output of passwords. Disabled by default
+        - stats:
+            totals: yes       # stats for all threads merged together
+            threads: no       # per thread stats
+            deltas: no        # include delta values
+            # Don't log stats counters that are zero. Default: true
+            #null-values: false    # False will NOT log stats counters: 0
         # bi-directional flows
         - flow
         # uni-directional flows
         #- netflow
 
-        # An event for logging metadata, specifically pktvars when
-        # they are set, but will also include the full metadata object.
+        # Metadata event type. Triggered whenever a pktvar is saved
+        # and will include the pktvars, flowvars, flowbits and
+        # flowints.
         #- metadata
+
+        # EXPERIMENTAL per packet output giving TCP state tracking details
+        # including internal state, flags, etc.
+        # This output is experimental, meant for debugging and subject to
+        # change in both config and output without any notice.
+        #- stream:
+        #   all: false                      # log all TCP packets
+        #   event-set: false                # log packets that have a decoder/stream event
+        #   state-update: false             # log packets triggering a TCP state update
+        #   spurious-retransmission: false  # log spurious retransmission packets