=== Features New to Snort 3

Some things Snort++ can do today that Snort can not do:

* regex fast patterns, not just literals
* JSON perf monitor logs
* LuaJIT scriptable rule options and loggers
* pub/sub inspection events (currently used by sip and http_inspect to appid)
* JIT buffer stuffers (notably with new http_inspect)
* C-style comments in rules
* #begin ... #end comment blocks in rules
* rule remarks (comment is part of rule, not just in it)
* process raw files (eg read a PDF and do file processing)
* process raw payload (eg bridge 2 sockets and do inspection)
* fast pattern offload to separate thread (experimental)
* add or override any config item on command line
* set CPU affinity
* pause and resume commands

=== Features Improved over Snort 2

Some things Snort++ can do today that Snort can not do as well:

|===
| Feature             | Snort 2                              | Snort 3
| Packet Threads      | 1 per process                        | N per process
| Config Memory Use   | N processes * M GB                   | M GB total, more for packets
| Config Reload       | N processes, slower                  | 1 thread, can be pinned to separate core
| Startup             | Single threaded, slower              | Multithreaded, faster
| Plugins             | Limited to preprocs and outputs      | Full plugin system with over 230 plugins
| Plugin Examples     | DPX preproc                          | snort3_extra repo, all types, LuaJIT
| DAQ                 | 2.X, run to completion               | 3.X, vector input, multiple outstanding packets
| DAQ Modules         | Legacy modules                       | Stacked modules, IOCTLs, file, socket, text modules
| Pcap Readback Speed | X Mbits/sec for Max-Detect           | 2X with ac, 4X with hyperscan
| IP Layers           | 2 max                                | Arbitrary / configurable limits
| IP Reputation       | Complex, shared memory               | Simplified process memory
| Stream TCP          | Complex implementation               | New and improved implementation
| Service detection   | appid only, port configs required    | Autodetection, most port configs optional
| HTTP inspector      | Partly stateful                      | Fully stateful
| HTTP Evader         | 65 misses                            | 10 misses
| Port Scan Detection | High, medium, low thresholds only    | Fully configurable detection thresholds
| Config parsing      | Report one error and quit            | Report all errors
| Config syntax       | Irregular, static, limited variables | Lua, fully scriptable, arbitrary variables
| Command Line        | Some overlap with config file        | Set or override any config from command line
| Default Config      | Complex, needs tuning                | Simplified, effective default config
| Policy Examples     | None                                 | Tweaks for all standard Talos policies
| Policy Bindings     | One level                            | Nested
| Rule syntax         | Inconsistent, requires line escapes  | Uniform syntax, arbitrary whitespace
| Rule parsing        | Buggy, limited warnings              | Robust, many optional warnings
| Rule comments       | # comments only                      | #, #begin/#end, C-style, rem option
| Rule input          | Config includes only                 | Includes, external file or path, stdin
| Hyperscan           | External patch available             | Native support, regex fast patterns
| Sensitive Data      | Requires a slow, extra search        | Normal fast pattern rule
| alert file rules    | No                                   | Yes
| alert service rules | No                                   | Yes
| fast_pattern_only   | Hand optimization                    | Automatic optimization
| Fast Pattern Buffers| 6 available                          | 14 available
| Elided rule headers | No                                   | Yes (omit nets and/or ports)
| Rule sticky buffers | Some                                 | All buffers are sticky
| SO rule features    | Restricted functionality             | True superset of text rules
| Simple SO rules     | No (based on tedious C-structs)      | Yes (based on text rule)
| Dump builtin stubs  | No (SO stubs only)                   | Yes
| Runtime tracing     | No (debug traces and misc logs only) | Yes
| Event Logging       | Legacy unified2 recommended          | JSON recommended, integrates with ELK stack, etc.
| Statistics          | Limited counts, fixed perf monitor   | 2X counts, configurable perf monitor
| Control interface   | Limited binary interface             | Extensible text shell, socket access
| Documentation       | LaTeX-based PDF, READMEs             | Asciidoc text, html, and PDF (user, ref, dev, upgrade)
| Command line help   | No                                   | Extensive, supports data driven management
| Build system        | Automake, Linux, *BSD, Windows       | Cmake, Linux, *BSD, Mac
| Startup / Shutdown  | Noisy, limited                       | Clean, extensible, non-zero counts only
| Sig Quit            | Same as Sig Term and Sig Int         | Quick exit
| Source Code         | 470K lines C, avg 400 lines/file     | 389K lines C++, avg 200 lines/file
| Tests               | A few unit tests                     | Many unit tests, snort3_demo suite
| Distribution        | snort.org tarballs, ~6 month updates | github repo, ~2 week updates
|===

=== Build Options

* configure --with-lib{pcap,pcre}-* -> --with-{pcap,pcre}-*
* control socket, cs_dir, and users were deleted
* POLICY_BY_ID_ONLY code was deleted
* hardened --enable-inline-init-failopen / INLINE_FAILOPEN

=== Command Line

* --pause loads config and waits for resume before processing packets
* --require-rule-sid is hardened
* --shell enables interactive Lua shell
* -T is assumed if no input given
* added --help-config prefix to dump all matching settings
* added --script-path
* added -L none|dump|pcap
* added -z <#> and --max-packet-threads <#>
* delete --enable-mpls-multicast, --enable-mpls-overlapping-ip,
  --max-mpls-labelchain-len, --mpls-payload-type
* deleted --pid-path and --no-interface-pidfile
* deleting command line options which will be available with --lua or some such including:
  -I, -h, -F, -p, --disable-inline-init-failopen
* hardened -n < 0
* removed --search-method
* replaced "unknown args are bpf" with --bpf
* replaced --dynamic-*-lib[-dir] with --plugin-path (with : separators)
* removed -b, -N, -Z and, --perfmon-file options

=== Conf File

* Snort 3 has a default unicode.map
* Snort 3 will not enforce an upper bound on memcaps and the like within 64 bits
* Snort 3 will supply a default *_global config if not specified
  (Snort 2 would fatal; e.g. http_inspect_server w/o http_inspect_global)
* address list syntax changes: [[ and ]] must be [ [ and ] ] to avoid Lua string
  parsing errors (unless in quoted string)
* because the Lua conf is live code, we lose file:line locations in app error messages
  (syntax errors from Lua have file:line)
* changed search-method names for consistency
* delete config include_vlan_in_alerts (not used in code)
* delete config so_rule_memcap (not used in code)
* deleted --disable-attribute-table-reload-thread
* deleted config decode_*_{alerts,drops} (use rules only)
* deleted config dump-dynamic-rules-path
* deleted config ipv6_frag (not actually used)
* deleted config threshold and ips rule threshold (-> event_filter)
* eliminated ac-split; must use ac-full-q split-any-any
* frag3 -> defrag, arpspoof -> arp_spoof, sfportscan -> port_scan,
  perfmonitor -> perf_monitor, bo -> back_orifice
* limits like "1234K" are now "limit = 1234, units = 'K'"
* lua field names are (lower) case sensitive; snort.conf largely wasn't
* module filenames are not configurable: always <log-dir>/<module-name><suffix>
  (suffix is determined by module)
* no positional parameters; all name = value
* perf_monitor configuration was simplified
* portscan.detect_ack_scans deleted (exact same as include_midstream)
* removed various run modes - now just one
* frag3 default policy is Linux not bsd
* lowmem* search methods are now in snort_examples
* deleted unused http_inspect stateful mode
* deleted stateless inspection from ftp and telnet
* deleted http and ftp alert options (now strictly rule based)
* preprocessor disabled settings deleted since no longer relevant
* sessions are always created; snort config stateful checks eliminated
* stream5_tcp: prune_log_max deleted; to be replaced with histogram
* stream5_tcp: max_active_responses, min_response_seconds moved to
  active.max_responses, min_interval
* ips policies support snort variables configured based on type,
  ips = { variables = { nets = { var1 = expr1, ... }, paths = { var2 = expr2, ... }, ports = { var3 = expr3, ... } } }

=== Rules

* all rules must have a sid
* sid == 0 not allowed
* deleted activate / dynamic rules
* deleted metadata engine shared
* deleted metadata: rule-flushing (with PDU flushing rule flushing can cause
  missed attacks, the opposite of its intent)
* changed metadata:service one[, service two]; to service:one[, two];
* soid is now a non-metadata option
* metadata is now truly metadata with no impact on detection
  (Snort doesn't care about metadata internal structure / syntax)
* deleted fast_pattern:only; use fast_pattern, nocase
  (option is not added to detection tree if not required)
* changed fast_pattern:<offset>,<length> to
  fast_pattern,fast_pattern_offset <offset>,fast_pattern_length <length>
* fast pattern sensitive data with sd_pattern using hyperscan
* hyperscan regex fast patterns with regex:"<regex>", fast_pattern;
* no ; separated content suboptions
* offset, depth, distance, and within must use a space separator not colon
  (e.g. offset:5; becomes offset 5;)
* content suboptions http_* are now full options
* added sticky buffers: buffer selector options must precede contents and remain
  in effect until changed
* the following pcre options have been deleted: use sticky buffers instead
    B, U, P, H, M, C, I, D, K, S, Y
* deleted uricontent option; use sticky buffer
  uricontent:"foo" -->  http_uri; content:"foo"
* deleted urilen raw and norm; must use http_raw_uri and http_uri instead
* deleted unused http_encode option
* urilen replaced with generic bufferlen which applies to current sticky
  buffer
* added optional selector to http_header, e.g. http_header:User-Agent;
* the all new http_inspect has new buffers and rule options
* added alert file and alert service rules
  (service in body not required if there is only one and it is in header;
  alert service / file rules disable fast pattern searching of raw packets)
* rule option sequence: <stub> soid <hidden>
* arbitrary whitespace and multiline rules w/o \n
* #begin ... #end comments to easily comment out multiple lines
* add rule remarks option with rem:"arbitrary comment"
* nets and/or ports may be omitted from rule headers (matches any)
* parse all rules and output all errors before quitting
* read rules from conf, separate rules file, or stdin
* The symbol =< in a byte test is recognized as a syntax error. The correct
  symbol is \<=.


=== Output

* alert_fast includes packet data by default
* all text mode outputs default to stdout
* changed default logging mode to -L none
* deleted layer2resets and flexresp2_*
* deleted log_ascii
* general output guideline: don't print zero counts
* Snort 3 queues decoder and inspector events to the main event queue before ips policy
  is selected; since some events may not be enabled, the queue needs to be sized larger
  than with Snort 2 which used an intermediate queue for decoder events.
* deleted the intermediate http and ftp_telnet event queues
* alert_unified2 and log_unified2 have been deleted

=== Sensitive Data

The Snort 2.X SDF Preprocessor is gone, replaced by ips option `sd_pattern`.
The sd_pattern rule option is synonymous with the sd_pattern option used
for gid:138 rules, but has a different syntax. A major difference in syntax
is the use of Hyperscan pattern matching library which provides a regex
language similar to PCRE.

To facilitate continued performance, sd_pattern rule option is implemented
with Hyperscan pattern matching library. The rule option is now also utilized
as a "fast pattern" in the Snort engine which provides a significant performance
improvement over the separate detection step of earlier implementations.

The preprocessor alert SDF_COMBO_ALERT (139:1) has been removed and has no
replacement in Snort 3.X. This is because the rule offered no additional
value over gid:138 rules and was difficult to interpret the result of.

For more information, See Features > Sensitive Data Filtering for details.

=== Features Not Yet Supported by Snort 3

* Support in http_inspect for Original Client IP is limited to the
  X-Forwarded-For and True-Client-IP headers in that order. It is not
  possible to configure additional custom headers to search for Original
  Client IP.

