From: Sascha Steinbiss Date: Sun, 12 May 2024 21:14:37 +0000 (+0200) Subject: doc: update MQTT configuration X-Git-Tag: suricata-8.0.0-beta1~1046 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=53c62432c6938cb50c4890c0cf7cd709dea1709d;p=thirdparty%2Fsuricata.git doc: update MQTT configuration --- diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst index e7c9005bac..ba42ac56be 100644 --- a/doc/userguide/output/eve/eve-json-output.rst +++ b/doc/userguide/output/eve/eve-json-output.rst @@ -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 ~~~~~ diff --git a/doc/userguide/partials/eve-log.yaml b/doc/userguide/partials/eve-log.yaml index df31c09141..b0104e9a48 100644 --- a/doc/userguide/partials/eve-log.yaml +++ b/doc/userguide/partials/eve-log.yaml @@ -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