source: src/router/snort/doc/README.stream5 @ 17490

Last change on this file since 17490 was 17490, checked in by chris, 6 years ago

snort & co ; snort configure still breaks

File size: 18.4 KB
Line 
1Overview
2========
3The Stream5 preprocessor is a target-based TCP reassembly module
4for Snort.  It is intended to replace both the Stream4 and flow
5preprocessors, and it is capable of tracking sessions for both
6TCP and UDP.  With Stream5, the rule 'flow' and 'flowbits' keywords
7are usable with TCP as well as UDP traffic.
8
9Since Stream5 replaces Stream4, both cannot be used simultaneously.
10Remove the Stream4 and flow configurations from snort.conf when the
11Stream5 configuration is added.
12
13Transport Protocols
14-------------------
15TCP sessions are identified via the classic TCP "connection".  UDP
16sessions are established as the result of a series of UDP packets
17from two end points via the same set of ports.  ICMP messages are
18tracked for the purposes of checking for unreachable and service
19unavailable messages, which effectively terminate a TCP or UDP
20session.
21
22Target-Based
23------------
24Stream5, like Frag3, introduces target-based actions for handling
25of overlapping data and other TCP anomalies.  The methods for handling
26overlapping data, TCP Timestamps, Data on SYN, FIN and Reset sequence
27numbers, etc. and the policies supported by Stream5 are the results of
28extensive research with many target operating systems.
29
30Stream API
31----------
32Stream5 fully supports the Stream API (partly supported by Stream4),
33allowing other protocol normalizers/preprocessors to dynamically
34configure reassembly behavior as required by the application layer
35protocol, identify sessions that may be ignored (large data transfers,
36etc), and update the identifying information about the session
37(application protocol, direction, etc) that can later be used by rules.
38
39Anomaly Detection
40-----------------
41TCP protocol anomalies, such as data on SYN packets, data received
42outside the TCP window, etc are configured via the detect_anomalies
43option to the TCP configuration.  Some of these anomalies are
44detected on a per-target basis.  For example, a few operating systems
45allow data in TCP SYN packets, while others do not.
46
47Rule Options
48============
49Stream5 adds support for a few rule options described below.
50
51stream_size
52-----------
53The 'stream_size' rule option allows a rule to match traffic according to
54the number of bytes observed, as determined by the TCP sequence numbers.
55
56stream_size takes a number of comma-separated arguments in the following
57format:
58
59    stream_size:<direction>,<operator>,<size>
60
61Where direction is one of:
62
63    client  -   Client side traffic only
64    server  -   Sever side traffic only
65    both    -   Traffic from both sides
66    either  -   Traffic from either side
67
68Valid operators are:
69
70    =
71    <
72    >
73    !=
74    <=
75    >=
76
77For example:
78
79    stream_size:client,<,6;
80
81stream_reassemble
82-----------------
83The 'stream_reassemble' rule option allows a rule to enable or disable TCP
84stream reassembly on matching traffic.
85
86stream_reassemble takes a number of comma-separated arguments in the following
87format:
88
89    stream_reassemble:<enable|disable>,<server|client|both> [,noalert] [,fastpath]
90
91- The optional noalert parameter causes the rule to not generate an alert when it matches.
92- The optional fastpath parameter causes Snort to ignore the rest of the connection.
93
94For example:
95
96To disable TCP reassembly for client traffic when we see a HTTP 200 Ok Response message:
97
98    alert tcp any 80 -> any any (flow:to_client,established;  content:"200 OK";
99        stream_reassemble:disable,client,noalert;)
100
101Configuration
102=============
103Global Configuration
104--------------------
105Global settings for the Stream5 preprocessor
106
107- Preprocessor name: stream5_global
108- Options:
109    track_tcp <yes|no>      - Track sessions for TCP.  The default is "yes".
110    max_tcp <number>        - Max concurrent sessions for TCP.  The default
111                              is "262144", maximum is "1048576", minimum is "1".
112    memcap <bytes>          - Memcap for TCP packet storage.  The default
113                              is "8388608" (8MB), maximum is "1073741824" (1GB),
114                              minimum is "32768" (32KB).
115    track_udp <yes|no>      - Track sessions for UDP.  The default is "yes".
116    max_udp <number>        - Max concurrent sessions for UDP.  The default
117                              is "131072", maximum is "1048576", minimum is "1".
118    track_icmp <yes|no>     - Track sessions for ICMP.  The default is "no".
119    max_icmp <number>       - Max concurrent sessions for ICMP.  The default
120                              is "65536", maximum is "1048576", minimum is "1".
121    flush_on_alert          - Backwards compatibility.  Flush a TCP stream
122                              when an alert is generated on that stream.  The
123                              default is set to off.
124    show_rebuilt_packets    - Print/display packet after rebuilt (for
125                              debugging).  The default is set to off.
126    prune_log_max <bytes>   - Print a message when a session terminates that
127                              was consuming more than the specified number of
128                              bytes.  The default is "1048576" (1MB), minimum
129                              can be either "0" (disabled) or if not disabled
130                              the minimum is "1024" and maximum is "1073741824".
131    disabled                - This optional keyword is allowed with any policy
132                              to avoid packet processing. This option disables
133                              the preprocessor. When the preprocessor is disabled
134                              only the options memcap, max_tcp, max_udp and
135                              max_icmp are applied when specified with the
136                              configuration. The other options are parsed but
137                              not used. Any valid configuration may have
138                              "disabled" added to it.
139                             
140
141TCP Configuration
142-----------------
143Provides a means on a per IP address target to configure a TCP policy.
144This can have multiple occurrences, per policy that is bound to an IP
145address or network.  One default policy must be specified, and that policy
146is not bound to an IP address or network.
147
148- Preprocessor name: stream5_tcp
149- Options:
150    bind_to <ip_addr>       - IP address for this policy.  The default is set
151                              to any.
152    timeout <number (secs)> - Session timeout.  The default is "30", the
153                              minimum is "1", and the maximum is "86400"
154                              (approximately 1 day).
155    policy <policy_id>      - The Operating System policy for the target OS.
156                              The policy_id can be one the following:
157                                   first     - Favor first overlapped segment.
158                                   last      - Favor last overlapped segment.
159                                   bsd       - FreeBSD 4.x and newer
160                                               NetBSD 2.x and newer
161                                               OpenBSD 3.x and newer
162                                               AIX
163                                   linux     - Linux 2.4 and 2.6
164                                   old-linux - Linux 2.2 and earlier
165                                   windows   - Windows 98, NT, 2000, XP (and
166                                               others not specifically listed
167                                               below)
168                                   win2003   - Windows 2003 Server
169                                   vista     - Windows Vista
170                                   solaris   - Solaris 9.x and newer
171                                   hpux10    - HPUX 10
172                                   hpux      - HPUX 11 and newer
173                                   irix      - IRIX 6 and newer
174                                   macos     - MacOS 10.3 and newer
175                              The default is "bsd".
176
177    overlap_limit <number>  - Limits number of overlapping packets.
178                              The default is "0" (unlimited), the minimum is
179                              "0", and the maximum is "255".
180    max_window <number>     - Maximum allowed TCP window.  The default is "0"
181                              (unlimited), the minimum is "0", and the maximum
182                              is "1073725440" (65535 left shift 14).  That is
183                              the highest possible TCP window per RFCs.  This
184                              option is intended to prevent a DoS against
185                              Stream5 by an attacker using an abnormally large
186                              window, so using a value near the maximum is
187                              discouraged.
188    detect_anomalies        - Detect TCP protocol anomalies.  The default is set
189                              to off.
190    require_3whs [<number secs>]
191                            - Establish sessions only on completion
192                              of a SYN/SYN-ACK/ACK handshake.  The default is
193                              set to off.  The optional number of seconds
194                              specifies a startup timeout.  This allows a grace
195                              period for existing sessions to be considered
196                              established during that interval immediately
197                              after Snort is started.  The default is "0"
198                              (don't consider existing sessions established),
199                              the minimum is "0", and the maximum is "86400"
200                              (approximately 1 day).
201    use_static_footprint_sizes
202                            - Emulate Stream4 behavior for flushing
203                              reassembled packets.  The default is set to off.
204    dont_store_large_packets
205                            - A performance improvement which does not queue
206                              large packets in reassembly buffer if set.
207                              Setting this option could result in missed
208                              packets.  The default is set to off.
209    check_session_hijacking - Check for TCP session hijacking.  This check
210                              validates the hardware (MAC) address from both
211                              sides of the connect -- as established on the
212                              3-way handshake against subsequent packets
213                              received on the session.  If an ethernet layer
214                              is not part of the protocol stack received by
215                              Snort, there are no checks performed.  Alerts
216                              are generated (per 'detect_anomalies' option)
217                              for either the client or server when the MAC
218                              address for one side or the other does not match.
219                              The default is set to off.
220    dont_reassemble_async   - Don't queue packets for reassembly if traffic
221                              has not been seen in both directions.  The
222                              default is set to queue packets.
223    max_queued_bytes <bytes> - Limit the number of bytes queued for reassembly
224                              on a given TCP session to bytes.  Default is
225                              "1048576" (1MB).  A value of "0" means unlimited,
226                              with a non-zero minimum of "1024", and a maximum
227                              of "1073741824" (1GB).  A message is written to
228                              console/syslog when this limit is enforced.
229    max_queued_segs <num>   - Limit the number of segments queued for reassembly
230                              on a given TCP session.  The default is "2621",
231                              derived based on an average size of 400 bytes.
232                              A value of "0" means unlimited, with a non-zero
233                              minimum of "2", and a maximum of "1073741824"
234                              (1GB).  A message is written to console/syslog
235                              when this limit is enforced.
236    small_segments <num1> bytes <num2> [ignore_ports port list]
237                            - Configure the maximum small segments queued. 
238                              This feature requires that detect_anomalies be enabled.
239                              num1 is the number of consecutive segments that will
240                              trigger the detection rule. The default value is
241                              "0" (disabled),with a maximum of "2048". 
242                              num2 is the minimum bytes for a segment to be
243                              considered "small". The default value is "0" (disabled),
244                              with a maximum of "2048". 
245                              ignore_ports is optional, defines the list of
246                              ports in which will be ignored for this rule.
247                              The number of ports can be up to "65535".
248                              Example:
249                                small_segments 3 bytes 15 ignore_ports 33 44 55
250                              A message is written to console/syslog when this
251                              limit is enforced. The generated alert is 129:12
252    ports <client|server|both> [all|space separated port list]
253                            - Specify the client, server, or both and list of
254                              ports in which to perform reassembly.  This can
255                              appear more than once in a given config.
256                              For example:
257                                ports both 80 23
258                                ports server 37
259                                ports client 21 25
260                              The default settings are:
261                                ports client 21 23 25 42 53 80 110 111 135 136 \
262                                             137 139 143 445 513 514 1433 1521 2401 3306
263                              The minimum port allowed is "1" and the maximum
264                              allowed is "65535".
265    ignore_any_rules        - Don't process any -> any (ports) rules for
266                              TCP that attempt to match payload if there are
267                              no port specific rules for the src or destination
268                              port.  Rules that have flow or flowbits will
269                              never be ignored.  This is a performance
270                              improvement, but may result in missed attacks.
271                              Using this does not affect rules that look at
272                              protocol headers, only those with content, PCRE,
273                              or byte test options.  The default is "off". This
274                              option can be present only in default policy.
275
276If no options are specified for a given TCP policy, that is the default
277TCP policy.  If only a bind_to option is used with no other options that
278TCP policy uses all of the default values.
279
280UDP Configuration
281-----------------
282Configuration for UDP session tracking.  Since there is no target based
283binding, there should be only one occurrence of the UDP configuration.
284- Preprocessor name: stream5_udp
285- Options:
286    timeout <number (secs)> - Session timeout.  The default is "30", the
287                              minimum is "1", and the maximum is "86400"
288                              (approximately 1 day).
289    ignore_any_rules        - Don't process any -> any (ports) rules for
290                              UDP that attempt to match payload if there are
291                              no port specific rules for the src or destination
292                              port.  Rules that have flow or flowbits will
293                              never be ignored.  This is a performance
294                              improvement, but may result in missed attacks.
295                              Using this does not affect rules that look at
296                              protocol headers, only those with content, PCRE,
297                              or byte test options.  The default is "off".
298
299NOTE: with the ignore_any_rules option, a UDP rule will be ignored except when
300there is another port specific rule that may be applied to the traffic.  For
301example, if a UDP rule specifies destination port 53, the 'ignored' any -> any
302rule will be applied to traffic to/from port 53, but NOT to any other
303source or destination port.  A list of rule SIDs affected by this option are
304printed at Snort's startup.
305
306NOTE: with the ignore_any_rules option, if a UDP rule that uses any -> any
307ports includes either flow or flowbits, the ignore_any_rules option is
308effectively pointless.  Because of the potential impact of disabling a flowbits
309rule, the ignore_any_rules option will be disabled in this case.
310
311ICMP Configuration
312------------------
313NOTE: ICMP is currently untested, in minimal code form and is NOT ready
314for use in production networks.  It is not turned on by default.
315
316Configuration for ICMP session tracking.  Since there is no target based
317binding, there should be only one occurrence of the ICMP configuration.
318- Preprocessor name: stream5_icmp
319- Options:
320    timeout <number (secs)> - Session timeout.  The default is "30", the
321                              minimum is "1", and the maximum is "86400"
322                              (approximately 1 day).
323
324Example Configurations
325======================
3261) This example configuration emulates the behavior of Stream4 (with
327   UDP support enabled).
328
329preprocessor stream5_global: max_tcp 8192, track_tcp yes, \
330                            track_udp yes, track_icmp no
331preprocessor stream5_tcp: policy first, use_static_footprint_sizes
332preprocessor stream5_udp: ignore_any_rules
333
3342) This configuration maps two network segments to different reassembly
335   policies, one for Windows, one for Linux, with all other traffic falling
336   to the default policy Solaris.
337
338preprocessor stream5_global: track_tcp yes
339preprocessor stream5_tcp: bind_to 192.168.1.0/24, policy windows
340preprocessor stream5_tcp: bind_to 10.1.1.0/24, policy linux
341preprocessor stream5_tcp: policy solaris
342
343Alerts
344======
345Stream5 uses generator ID 129.  It is capable of alerting on 10
346anomalies, all of which relate to TCP anomalies.  There are no
347anomaly detection capabilities for UDP or ICMP.
348
349SID   Description
350---   -----------
3511     SYN on established session
3522     Data on SYN packet
3533     Data sent on stream not accepting data
3544     TCP Timestamp is outside of PAWS window
3555     Bad segment, overlap adjusted size less than/equal 0
3566     Window size (after scaling) larger than policy allows
3577     Limit on number of overlapping TCP packets reached
3588     Data after Reset packet
3599     Possible Hijacked Client
36010    Possible Hijacked Server
36111    TCP packet with any control flags set
36212    Limit on number of consecutive small segments reached
36313    4-way handshake detected
36414    Packet missing timestamp
Note: See TracBrowser for help on using the repository browser.