Snort 3 can log IPS events with some meta data and dump packets. Advanced
Logging feature extends that ability to log protocol-specific data, sniffing
traffic alongside with normal inspection.

==== Configurations

The module's configuration consists of two parts:

* global parameters
  ** `formatting` - log record format
  ** `connector` - Connector object through which logs will be sent. See Connectors page
     for more details.
  ** `time` - timestamp format
* protocol-targeted parameters bind the targeted service and events with
  filters and a set of fields to log
  ** `service` - protocol name
  ** `tenant_id` - a filter, apply the binding only for traffic marked with
      the tenant ID
  ** `on_events` - events in a protocol session to be logged
  ** `fields` - data fields to log (if a field is not supported it will be ignored)

Configuration from different bindings do not interfere. Among other
things it allows tenants to get independent logging configurations.

    extractor =
    {
        formatting = 'csv',
        connector = 'stdout',

        protocols =
        {
            { service = 'http', on_events = 'eot', fields = 'ts, uri, host, method' },
            { service = 'ftp', on_events = 'request', fields = 'ts, command, arg' },
            { service = 'http', on_events = 'eot', fields = 'ts, uri' },
            { service = 'conn', on_events = 'eof', fields = 'ts, uid, service' },
            { service = 'dns', on_events = 'response', fields = 'ts, uid, query, answers' }
            { service = 'weird', on_events = 'builtin', fields = 'ts, msg, gid, sid' }
            { service = 'notice', on_events = 'ips_logging', fields = 'msg, sid, refs' }
        }
    }

==== Supported Parameters

Timestamp formats:

* `snort` prints timestamp as in IPS events (see snort command line options
   `-U` and `-y`) (string `ts` field)
* `snort_yy` same as above, but using YYYY-MM-DD format (string `ts` field)
* `unix` prints UTC time in seconds (integer part) and microseconds (fractional part)
   (floating `ts` field)
* `unix_s` prints UTC time in seconds (integer `ts` field)
* `unix_us` prints UTC time in microseconds (integer `ts` field)

Services and their events:

* HTTP, HTTP2
  ** `eot` (request-response pair)
* SSH
  ** `algorithm` (key exchange with details)
  ** `exchange` (key exchange complete)
* FTP
  ** `request`
  ** `response`
  ** `eot` (a session defined by the following commands: APPE, DELE, RETR, STOR, STOU, ACCT, PORT, PASV, EPRT, EPSV)
* SSL
  ** `tls_metadata_event`
* DNS
  ** `response`
* connection (conn)
  ** `eof` (end of flow)
* file
  ** `eof` (end of file)
* internal built-in checks which failed (weird)
  ** 'builtin' (internally-detected infraction is queued for further processing)
* triggered IPS rule, whether built-in or text or SO (notice)
  ** `ips_logging` (matched rules sent to IPS logging)
  ** `context_logging` (matched rule in an IPS logger)
* QUIC
  ** `handshake` (log on handshake completion)

Common fields available for every service:

* `ts` - timestamp of the current packet, which triggers logging
* `uid` - connection id, to correlate log records related to the same flow
* `id.orig_h` - client IP address
* `id.orig_p` - client TCP port
* `id.resp_h` - server IP address
* `id.resp_p` - server TCP port
* `pkt_num` - packet number
* `tenant_id` - tenant identifier

Fields supported for HTTP:

* `method` - verb used in HTTP request
* `host` - Host header
* `uri` - URI from request
* `user_agent` - User-Agent header from client
* `referrer` - Referrer header
* `origin` - Origin header from client
* `version` - Version from request
* `status_code` - status code returned by server
* `status_msg` - status message returned by server
* `trans_depth` - number of request-response pairs seen in the session
* `request_body_len` - length of the body, decompressed and normalized, of the HTTP request
* `response_body_len` - length of the body, decompressed and normalized, of the HTTP response
* `info_code` - last informational status code returned by the server
* `info_msg` - last informational reason phrase returned by the server
* `proxied` - list with the headers associated with proxied requests
* `orig_filenames` - list with the names of the files sent by client
* `resp_filenames` - list with the names of the files sent by server
* `orig_mime_types` - list with the content types of the files sent by client
* `resp_mime_types` - list with the content types of the files sent by server

Fields supported for SSH:

* `version` - major version
* `direction` - direction of the connection (LAN/WAN outbound/inbound)
* `client.version` - the client's version string
* `client.kex_alg` - key exchange algorithms listed by client
* `client.host_key_alg` - server host key algorithms listed by client
* `client.cipher_c2s_alg` - symmetric encryption algorithms (client-to-server direction) listed by client
* `client.cipher_s2c_alg` - symmetric encryption algorithms (server-to-client direction) listed by client
* `client.mac_c2s_alg` - MAC algorithms (client-to-server direction) listed by client
* `client.mac_s2c_alg` - MAC algorithms (server-to-client direction) listed by client
* `client.compression_c2s_alg` - compression algorithms (client-to-server direction) listed by client
* `client.compression_s2c_alg` - compression algorithms (server-to-client direction) listed by client
* `server.version` - the server's version string
* `server.kex_alg` - key exchange algorithms listed by server
* `server.host_key_alg` - server host key algorithms listed by server
* `server.cipher_c2s_alg` - symmetric encryption algorithms (client-to-server direction) listed by server
* `server.cipher_s2c_alg` - symmetric encryption algorithms (server-to-client direction) listed by server
* `server.mac_c2s_alg` - MAC algorithms (client-to-server direction) listed by server
* `server.mac_s2c_alg` - MAC algorithms (server-to-client direction) listed by server
* `server.compression_c2s_alg` - compression algorithms (client-to-server direction) listed by server
* `server.compression_s2c_alg` - compression algorithms (server-to-client direction) listed by server
* `kex_alg` - key exchange algorithms in use (separated by comma if not the same: c2s, s2c)
* `host_key_alg` - server host key algorithms in use (separated by comma if not the same: c2s, s2c)
* `cipher_alg` - symmetric encryption algorithms in use (separated by comma if not the same: c2s, s2c)
* `mac_alg` - MAC algorithms in use (separated by comma if not the same: c2s, s2c)
* `compression_alg` - compression algorithms in use (separated by comma if not the same: c2s, s2c)

Fields supported for FTP:

* `command` - last command seen in a session
* `arg` - request parameters
* `user` - user name set for a session
* `reply_code` - reply code from server in response to command
* `reply_msg` - reply message from server in response to command
* `file_size` - size of the file transferred
* `data_channel.passive` - data channel mode
* `data_channel.orig_h` - IP address of data channel originator
* `data_channel.resp_h` - IP address of data channel receiving point
* `data_channel.resp_p` - TCP port of data channel receiving point

Fields supported for SSL:

* `version` - SSL/TLS version that the server chose
* `server_name` - Server Name Identifier ( SNI ) extracted from Client Hello
* `validation_status` - result of certificate validation
* `subject` - RFC2253 formatted certificate subject information
* `issuer` - RFC2253 formatted certificate issuer information
* `module_identifier` - name of snort module that populated the event
* `cipher` - SSL/TLS cipher suite that the server chose
* `curve` - named elliptic curve the server chose

Fields supported for DNS:

* `proto` - transport protocol for DNS connection
* `trans_id` - A 16 bit identifier assigned by the program that generates the query
* `query` - The domain name that is the subject of this DNS transaction
* `qclass` - A 16 bit integer that specifies the class of the query
* `qclass_name` - A descriptive name for the class of the query
* `qtype` - A 16 bit integer that specifies the type of the query
* `qtype_name` - A descriptive name for the type of the query
* `rcode` - A 16 bit integer that specifies the response code to the query
* `rcode_name` - A descriptive name for the response code to the query
* `AA` - A boolean, true when this is an Authoritative Answer to the query
* `TC` - A boolean, true when the message was truncated due to UDP PDU size limits
* `RD` - A boolean, true when the client asks the server to pursue the query recursively
* `RA` - A boolean, denotes the availability of recursive query support at the server
* `Z` - A 3 bit integer set to 0 unless DNSSEC is used (see RFC 2535)
* `answers` - The list of answers to the query
* `TTLs` - The list of caching intervals for the corresponding answers
* `rejected` - A boolean, true when the server responds with an error code and no query
* `auth` - The list of authoritative responses
* `addl` - The list of additional responses

The answers, auth, and addl lists contain all the RRs found in the corresponding message sections. Each RR is
represented by a summary of its decoding. For these RR types the decoding contains type specific information
(ip addresses, domain names, etc.): A, AAAA, BIND9 signing, CNAME, DNSKEY, DS, LOC, MX, NS, NSEC, OPT, PTR, RRSIG,
SOA, SPF, SRV, SSHFP, TXT. For these RR types: CAA, HINFO, HTTPS, NSEC3, NSEC3PARAM, SVCB, TKEY, TSIG, the decoding
contains only the name of the RR type. This is also the default decoding applied to all RR types that don't have
a type specific decoder. When the name of the type is not known it is decoded as UNKNOWN-N, where N is RR type
numeric value.

Fields supported for QUIC:

* `version` - QUIC version
* `client_initial_dcid` - client initial destination connection ID
* `client_scid` - client source connection ID
* `server_scid` - server source connection ID
* `server_name` - server name indication (SNI) from client hello
* `client_protocol` - application protocol requested by client
* `history` - connection history string

Fields supported for connection:

* `duration` - connection duration in seconds
* `proto` - transport layer protocol of the connection
* `service` - connection's application protocol
* `orig_pkts` - number of packets client sent
* `resp_pkts` - number of packets server sent
* `orig_bytes` - tcp/udp payload bytes client sent
* `resp_bytes` - tcp/udp payload bytes server sent

For TCP orig_bytes and resp_bytes are calculated using first seen sequence number and next expected sequence number.
These are reset during TCP flow restart. For this case only bytes seen following the restart will be reported.

* `conn_state` - records the connection state, which varies depending on the protocol (UDP, TCP, or others):

UDP Connection States:

    ** CLT_SRV_UDP_SEEN: Packets were seen from both the client and server.
    ** CLT_UDP_SEEN: Only client packets were observed.
    ** SRV_UDP_SEEN: Only server packets were observed.

TCP Connection States:

The TCP connection state tracks both client and server states, each prefixed with CLT_ (for the client) and SRV_ (for the server).
These states follow the TCP state machine as defined by the RFC, with the addition of TCP_MID_STREAM_SENT
and TCP_MID_STREAM_REC to handle mid-stream traffic and TCP_STATE_NONE.

OTH (Other Traffic):

The OTH state is used for all non-UDP and non-TCP traffic, as well as for error cases.

* `history` - a string that tracks the connection's history. It uses letters to represent events, with
uppercase letters denoting client-side events and lowercase letters for server-side events.
Each letter appears only once for each direction, regardless of how many times the event occurs.

UDP Events: d: Packet with payload.

TCP Events: s: SYN, h: SYN-ACK, a: Pure ACK or PUSH, d: Packet with payload, f: FIN, r: Reset.

Fields supported for file:

* `filename` - filename from headers in network protocols
* `fuid` - unique file identifier
* `source` - a protocol associated with the file
* `inspector` - inspector associated with the file analysis
* `mime_type` - mime attachment type (or file type identified by file magic)
* `is_orig` - if sender was originator of the file transfer
* `seen_bytes` - number of bytes processed for analysis
* `total_bytes` - total file size in bytes
* 'duration' - duration the file was analyzed for, in seconds
* `timeout` - if file analysis timed out
* `sha256` - SHA256 digest of the file contents
* `extracted`- name of captured file
* `extracted_size` - number of bytes captured
* `extracted_cutoff` - true if the file being captured was cut off so the whole file was not logged

Fields supported for 'weird' and 'notice' logs:

* `sid` - unique signature number of the rule
* `gid` - component ID which generated the event
* `msg` - rule message
* `proto` - transport protocol
* `source` - assigned inspector

'notice' events for text rules also get the following fields:

* `action` - action of triggered event
* `refs` - references mentioned in a rule
* `rev` - particular revision number of the rule

==== Example

Adding the following lines to a default snort configuration (which supports FTP
inspection) would print some FTP logs to standard output in CSV format.

FTP sessions with basic fields:

    std_connector = { }

    extractor =
    {
        formatting = csv',
        connector = 'stdout',
        protocols =
        {
            {service = 'ftp', on_events = 'eot', fields = 'ts, command, user'}
        }
    }

Output:

    #ts,command,user
    946684800.000014,PORT,ftptest
    946684800.000016,RETR,
    946684800.000034,PORT,anonymous
    946684800.000036,RETR,
    946684800.000053,PORT,sfuser
    946684800.000055,RETR,

Or FTP requests with the same set of fields:

    std_connector = { }

    extractor =
    {
        formatting = 'csv',
        connector = 'stdout',
        protocols =
        {
            {service = 'ftp', on_events = 'request', fields = 'ts, command, user'}
        }
    }

Output:

    #ts,command,user
    946684800.000005,USER,ftptest
    946684800.000007,PASS,
    946684800.000009,SYST,
    946684800.000011,TYPE,
    946684800.000013,PORT,
    946684800.000015,RETR,
    946684800.000018,QUIT,
    946684800.000027,USER,anonymous
    946684800.000029,PASS,
    946684800.000031,TYPE,
    946684800.000033,PORT,
    946684800.000035,RETR,
    946684800.000037,SYST,
    946684800.000039,QUIT,
    946684800.000048,USER,sfuser
    946684800.000050,PASS,
    946684800.000052,PORT,
    946684800.000054,RETR,
    946684800.000057,QUIT,

