Snort 3 User Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 305

Download
Open PDF In Browser	View PDF

Snort 3 User Manual

i

Snort 3 User Manual

Snort 3 User Manual

ii

REVISION HISTORY
NUMBER

DATE

DESCRIPTION

NAME

Snort 3 User Manual

iii

Contents
1

Overview

1

1.1

First Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

1.2

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3

1.2.1

Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

1.2.2

Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

1.2.3

Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

1.2.4

Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

1.2.5

Converting Your 2.X Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6

1.3.1

Basic Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6

1.3.2

Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6

1.3.3

Files and Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6

1.3.4

Performance Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7

1.3

2

3

Concepts

7

2.1

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7

2.2

Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8

2.3

Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9

2.4

Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.5

Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5.1

Snort 2 Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.5.2

Snort 3 Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.6

Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.7

Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.7.1

Rule Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.7.2

Fast Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.7.3

Rule Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Tutorial

13

3.1

Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.2

Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.3

Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.4

Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.5

Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.6

Common Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.7

Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Snort 3 User Manual

4

Usage

iv

19

4.1

Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.2

Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.3

Sniffing and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.4

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.5

IDS mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4.6

Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4.7

Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.8

DAQ Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.9

Logger Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.10 Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.11 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5

Features
5.1

24

AppId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.1.1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.1.2

Dependency Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.1.3

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.1.4

Session Application Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.1.5

AppId Usage Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.1.6

Open Detector Package (ODP) Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.1.7

User Created Application Detectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.1.8

Application Detector Creation Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.2

Binder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

5.3

Byte rule options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.3.1

byte_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.3.2

byte_jump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.3.3

byte_extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Other options which use byte_extract variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

5.3.4

byte_math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

5.3.5
5.4

Testing Numerical Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

DCE Inspectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.4.1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5.4.2

Quick Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5.4.3

Target Based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Snort 3 User Manual

v

5.4.4

Reassembling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5.4.5

SMB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Finger Print Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
File Inspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5.4.6

TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

5.4.7

UDP

5.4.8

Rule Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

dce_iface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
dce_opnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
dce_stub_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
byte_test and byte_jump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.5

5.6

File Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.5.1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

5.5.2

Quick Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

5.5.3

Pre-packaged File Magic Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5.5.4

File Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5.5.5

File Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5.5.6

File Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.6.1

HA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

5.6.2

Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Connector (parent plugin class) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
TcpConnector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
FileConnector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

5.6.3
5.7

Side Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.7.1

Configuring the inspector to block exploits and attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
ftp_server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
ftp_client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
ftp_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

5.8

HTTP Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.8.1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

5.8.2

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
request_depth and response_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
gzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
normalize_utf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
decompress_pdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
decompress_swf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
normalize_javascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Snort 3 User Manual

vi

URI processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.8.3

Detection rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
http_uri and http_raw_uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
http_header and http_raw_header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
http_trailer and http_raw_trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_cookie and http_raw_cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_true_ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_client_body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_raw_body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_stat_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_stat_msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
http_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
http_raw_request and http_raw_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
file_data and packet data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5.8.4
5.9

Timing issues and combining rule options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

HTTP/2 Inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.10 Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.10.2 Base Tracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.10.3 Flow Tracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.10.4 FlowIP Tracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.10.5 CPU Tracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.10.6 Formatters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.11 POP and IMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.11.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
b64_decode_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
qp_decode_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
bitenc_decode_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
uu_decode_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.12 Port Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.12.2 Scan levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.12.3 Tuning Portscan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.13 Sensitive Data Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.13.1 Hyperscan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.13.2 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Snort 3 User Manual

vii

Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Threshold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Obfuscating Credit Cards and Social Security Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.13.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.13.4 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.14 SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.14.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.14.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
normalize and normalize_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ignore_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
ignore_tls_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
max_command_line_len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
max_header_line_len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
max_response_line_len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
alt_max_command_line_len . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
invalid_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
valid_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
data_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
binary_data_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
auth_cmds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
xlink2state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
b64_decode_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
qp_decode_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
bitenc_decode_depth * default to 25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
uu_decode_depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Log Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.14.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.15 Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.15.1 Configuring the inspector to block exploits and attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.16 Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6

Basic Modules

69

6.1

active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

6.2

alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

6.3

attribute_table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

6.4

classifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

6.5

daq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

6.6

decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

6.7

detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Snort 3 User Manual

viii

6.8

event_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

6.9

event_queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

6.10 high_availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.11 host_cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.12 host_tracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.13 hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6.14 inspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6.15 ips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.16 latency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.17 memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6.18 network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6.19 output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6.20 packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6.21 process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6.22 profiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6.23 rate_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.24 references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.25 rule_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.26 search_engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.27 side_channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.28 snort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.29 suppress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7

Codec Modules

86

7.1

arp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

7.2

auth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

7.3

ciscometadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

7.4

eapol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

7.5

erspan2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

7.6

erspan3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

7.7

esp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

7.8

eth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

7.9

fabricpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

7.10 gre . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.11 gtp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.12 icmp4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
7.13 icmp6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
7.14 igmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.15 ipv4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Snort 3 User Manual

ix

7.16 ipv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.17 llc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
7.18 mpls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
7.19 pbb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
7.20 pgm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
7.21 pppoe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.22 tcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.23 token_ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.24 udp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.25 vlan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.26 wlan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
8

9

Connector Modules

96

8.1

file_connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

8.2

tcp_connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Inspector Modules

97

9.1

appid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

9.2

arp_spoof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

9.3

back_orifice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

9.4

binder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

9.5

data_log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

9.6

dce_http_proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

9.7

dce_http_server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

9.8

dce_smb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

9.9

dce_tcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

9.10 dce_udp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
9.11 dnp3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
9.12 dns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
9.13 dpx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.14 file_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.15 file_log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9.16 ftp_client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.17 ftp_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.18 ftp_server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.19 gtp_inspect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.20 http2_inspect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.21 http_inspect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.22 imap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Snort 3 User Manual

x

9.23 modbus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.24 normalizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.25 packet_capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.26 perf_monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.27 pop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.28 port_scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.29 reg_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.30 reputation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.31 rpc_decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
9.32 sip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
9.33 smtp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
9.34 ssh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
9.35 ssl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
9.36 stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
9.37 stream_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
9.38 stream_icmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
9.39 stream_ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
9.40 stream_tcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
9.41 stream_udp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
9.42 stream_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
9.43 telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
9.44 wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
10 IPS Action Modules

140

10.1 react . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
10.2 reject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
10.3 rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
11 IPS Option Modules

141

11.1 ack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
11.2 appids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
11.3 asn1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
11.4 base64_decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
11.5 bufferlen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
11.6 byte_extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
11.7 byte_jump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
11.8 byte_math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
11.9 byte_test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
11.10classtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Snort 3 User Manual

xi

11.11content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
11.12cvs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
11.13dce_iface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
11.14dce_opnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
11.15dce_stub_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
11.16detection_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.17dnp3_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.18dnp3_func . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.19dnp3_ind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.20dnp3_obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.21dsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.22file_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.23file_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.24flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.25flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.26flowbits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
11.27fragbits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
11.28fragoffset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
11.29gid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
11.30gtp_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.31gtp_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.32gtp_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.33http2_frame_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.34http2_frame_header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.35http_client_body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.36http_cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.37http_header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.38http_method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.39http_raw_body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.40http_raw_cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
11.41http_raw_header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
11.42http_raw_request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
11.43http_raw_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
11.44http_raw_trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
11.45http_raw_uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
11.46http_stat_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
11.47http_stat_msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
11.48http_trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
11.49http_true_ip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Snort 3 User Manual

xii

11.50http_uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
11.51http_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.52icmp_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.53icmp_seq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.54icode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.55id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.56ip_proto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.57ipopts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.58isdataat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.59itype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.60md5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
11.61metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
11.62modbus_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
11.63modbus_func . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
11.64modbus_unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
11.65msg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.66mss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.67pcre . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.68pkt_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.69pkt_num . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.70priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
11.71raw_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
11.72reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
11.73regex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
11.74rem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
11.75replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
11.76rev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
11.77rpc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
11.78sd_pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
11.79seq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
11.80service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
11.81session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
11.82sha256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
11.83sha512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
11.84sid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
11.85sip_body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
11.86sip_header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
11.87sip_method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
11.88sip_stat_code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Snort 3 User Manual

xiii

11.89so . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
11.90soid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
11.91ssl_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
11.92ssl_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
11.93stream_reassemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
11.94stream_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
11.95tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
11.96target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
11.97tos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
11.98ttl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
11.99urg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
11.100window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
11.101wscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12 Search Engine Modules

165

13 SO Rule Modules

165

14 Logger Modules

165

14.1 alert_csv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
14.2 alert_ex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
14.3 alert_fast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
14.4 alert_full . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
14.5 alert_json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
14.6 alert_sfsocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
14.7 alert_syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
14.8 alert_unixsock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
14.9 log_codecs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
14.10log_hext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
14.11log_pcap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
14.12unified2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
15 DAQ Configuration and Modules

168

15.1 Building the DAQ Library and Its Bundled DAQ Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
15.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
15.2.1 Command Line Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
15.2.2 Configuration File Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
15.2.3 Interaction With Multiple Packet Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
15.3 DAQ Modules Included With Snort 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
15.3.1 Socket Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
15.3.2 File Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
15.3.3 Hext Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Snort 3 User Manual

16 Snort 3 vs Snort 2

xiv

173

16.1 Features New to Snort 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
16.2 Features Improved over Snort 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
16.3 Build Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
16.4 Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
16.5 Conf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
16.6 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
16.7 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
16.8 Sensitive Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
17 Snort2Lua

179

17.1 Snort2Lua Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
17.1.1 Usage: snort2lua [OPTIONS]. . . -c  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Options: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Required option: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Default values: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
17.2 Known Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
17.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
18 Extending Snort

182

18.1 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
18.2 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
18.3 Inspectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
18.4 Codecs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
18.5 IPS Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
18.6 Developers Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
18.7 Piglet Test Harness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
18.8 Piglet Lua API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
18.8.1 Plugin Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Interface Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
19 Coding Style

193

19.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
19.2 C++ Specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
19.3 Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
19.4 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
19.5 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
19.6 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
19.7 Macros (aka defines) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
19.8 Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
19.9 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
19.10Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
19.11Uncrustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Snort 3 User Manual

20 Reference

xv

198

20.1 Build Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
20.2 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
20.3 Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
20.4 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
20.5 Counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
20.6 Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
20.7 Builtin Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
20.8 Command Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
20.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
20.10Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
20.11Module Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
20.12Plugin Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
20.13Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
20.13.1 Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
20.13.2 Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
20.13.3 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
20.13.4 snort2lua . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
20.13.5 Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
20.14LibDAQ and DAQ Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
20.14.1 Building the DAQ Library and DAQ Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
20.14.2 PCAP Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
20.14.3 AFPACKET Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Fanout (Kernel Loadbalancing) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
20.14.4 NFQ Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
20.14.5 IPQ Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.14.6 IPFW Module

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

20.14.7 Dump Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.14.8 Netmap Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
FreeBSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
20.14.9 Notes on iptables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
20.14.10Notes on FreeBSD::IPFW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
20.14.11Notes on OpenBSD::IPFW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Snort 3 User Manual

,,_
o" )~
’’’’

1

1 / 290

-*> Snort++ <*Version 3.0.0 (Build 243) from 2.9.11
By Martin Roesch & The Snort Team
http://snort.org/contact#team
Copyright (C) 2014-2018 Cisco and/or its affiliates. All rights reserved.
Copyright (C) 1998-2013 Sourcefire, Inc., et al.

Overview

Snort 3.0 is an updated version of the Snort Intrusion Prevention System (IPS) which features a new design that provides a
superset of Snort 2.X functionality with better throughput, detection, scalability, and usability. Some of the key features of Snort
3.0 are:
• Support multiple packet processing threads
• Use a shared configuration and attribute table
• Autodetect services for portless configuration
• Modular design
• Plugin framework with over 200 plugins
• More scalable memory profile
• LuaJIT configuration, loggers, and rule options
• Hyperscan support
• Rewritten TCP handling
• New rule parser and syntax
• Service rules like alert http
• Rule "sticky" buffers

Snort 3 User Manual

2 / 290

• Way better SO rules
• New HTTP inspector
• New performance monitor
• New time and space profiling
• New latency monitoring and enforcement
• Piglets to facilitate component testing
• Inspection Events
• Automake and Cmake
• Autogenerate reference documentation
Additional features are on the road map:
• Use a shared network map
• Support hardware offload for fast pattern acceleration
• Provide support for DPDK and ODP
• Support pipelining of packet processing
• Support proxy mode
• Multi-tennant support
• Incremental reload
• New serialization of perf data and events
• Enhanced rule processing
• Windows support
• Anomaly detection
• and more!
The remainder of this section provides a high level survey of the inputs, processing, and outputs available with Snort 3.0.
Snort++ is the project that is creating Snort 3.0. In this manual "Snort" or "Snort 3" refers to the 3.0 version and earlier versions
will be referred to as "Snort 2" where the distinction is relevant.

1.1

First Steps

Snort can be configured to perform complex packet processing and deep packet inspection but it is best start simply and work up
to more interesting tasks. Snort won’t do anything you didn’t specifically ask it to do so it is safe to just try things out and see
what happens. Let’s start by just running Snort with no arguments:
$ snort
That will output usage information including some basic help commands. You should run all of these commands now to see what
is available:
$ snort -V
$ snort -?
$ snort --help

Snort 3 User Manual

3 / 290

Note that Snort has extensive command line help available so if anything below isn’t clear, there is probably a way to get the
exact information you need from the command line.
Now let’s examine the packets in a capture file (pcap):
$ snort -r a.pcap
Snort will decode and count the packets in the file and output some statistics. Note that the output excludes non-zero numbers so
it is easy to see what is there.
You may have noticed that there are command line options to limit the number of packets examined or set a filter to select
particular packets. Now is a good time to experiment with those options.
If you want to see details on each packet, you can dump the packets to console like this:
$ snort -r a.pcap -L dump
Add the -d option to see the TCP and UDP payload. Now let’s switch to live traffic. Replace eth0 in the below command with an
available network interface:
$ snort -i eth0 -L dump
Unless the interface is taken down, Snort will just keep running, so enter Control-C to terminate or use the -n option to limit the
number of packets.
Generally it is better to capture the packets for later analysis like this:
$ snort -i eth0 -L pcap -n 10
Snort will write 10 packets to log.pcap.# where # is a timestamp value. You can read these back with -r and dump to console or
pcap with -L. You get the idea.
Note that you can do similar things with other tools like tcpdump or Wireshark however these commands are very useful when
you want to check your Snort setup.
The examples above use the default pcap DAQ. Snort supports non-pcap interfaces as well via the DAQ (data acquisition) library.
Other DAQs provide additional functionality such as inline operation and/or higher performance. There are even DAQs that
support raw file processing (ie without packets), socket processing, and plain text packets. To load external DAQ libraries and
see available DAQs or select a particular DAQ use one of these commands:
$ snort --daq-dir  --daq-list
$ snort --daq-dir  --daq 
Be sure to put the --daq-dir option ahead of the --daq-list option or the external DAQs won’t appear in the list.
To leverage intrusion detection features of Snort you will need to provide some configuration details. The next section breaks
down what must be done.

1.2

Configuration

Effective configuration of Snort is done via the environment, command line, a Lua configuration file, and a set of rules.
Note that backwards compatibility with Snort 2 was sacrificed to obtain new and improved functionality. While Snort 3 leverages
some of the Snort 2 code base, a lot has changed. The configuration of Snort 3 is done with Lua, so your old conf won’t work as
is. Rules are still text based but with syntax tweaks, so your 2.X rules must be fixed up. However, snort2lua will help you convert
your conf and rules to the new format.

Snort 3 User Manual

1.2.1

4 / 290

Environment

LUA_PATH must be set based on your install:
LUA_PATH=$install_prefix/include/snort/lua/\?.lua\;\;
SNORT_LUA_PATH must be set to load auxiliary configuration files if you use the default snort.lua. For example:
export SNORT_LUA_PATH=$install_prefix/etc/snort

1.2.2

Command Line

A simple command line might look like this:
snort -c snort.lua -R cool.rules -r some.pcap -A cmg
To understand what that does, you can start by just running snort with no arguments by running snort --help. Help for all
configuration and rule options is available via a suitable command line. In this case:
-c snort.lua is the main configuration file. This is a Lua script that is executed when loaded.
-R cool.rules contains some detection rules. You can write your own or obtain them from Talos (native 3.0 rules are not yet
available from Talos so you must convert them with snort2lua). You can also put your rules directly in your configuration file.
-r some.pcap tells Snort to read network traffic from the given packet capture file. You could instead use -i eth0 to read from a
live interface. There many other options available too depending on the DAQ you use.
-A cmg says to output intrusion events in "cmg" format, which has basic header details followed by the payload in hex and text.
Note that you add to and/or override anything in your configuration file by using the --lua command line option. For example:
--lua ’ips = { enable_builtin_rules = true }’
will load the built-in decoder and inspector rules. In this case, ips is overwritten with the config you see above. If you just want
to change the config given in your configuration file you would do it like this:
--lua ’ips.enable_builtin_rules = true’

1.2.3

Configuration File

The configuration file gives you complete control over how Snort processes packets. Start with the default snort.lua included in
the distribution because that contains some key ingredients. Note that most of the configurations look like:
stream = { }
This means enable the stream module using internal defaults. To see what those are, you could run:
snort --help-config stream
Snort is organized into a collection of builtin and plugin modules. If a module has parameters, it is configured by a Lua table of
the same name. For example, we can see what the active module has to offer with this command:
$ snort --help-module active
What: configure responses
Type: basic

Snort 3 User Manual

5 / 290

Configuration:
int active.attempts = 0: number of TCP packets sent per response (with
varying sequence numbers) { 0:20 }
string active.device: use ’ip’ for network layer responses or ’eth0’ etc
for link layer
string active.dst_mac: use format ’01:23:45:67:89:ab’
int active.max_responses = 0: maximum number of responses { 0: }
int active.min_interval = 255: minimum number of seconds between
responses { 1: }
This says active is a basic module that has several parameters. For each, you will see:
type module.name = default: help { range }
For example, the active module has a max_responses parameter that takes non-negative integer values and defaults to zero. We
can change that in Lua as follows:
active = { max_responses = 1 }
or:
active = { }
active.max_responses = 1
If we also wanted to limit retries to at least 5 seconds, we could do:
active = { max_responses = 1, min_interval = 5 }

1.2.4

Rules

Rules determine what Snort is looking for. They can be put directly in your Lua configuration file with the ips module, on the
command line with --lua, or in external files. Generally you will have many rules obtained from various sources such as Talos
and loading external files is the way to go so we will summarize that here. Add this to your Lua configuration:
ips = { include = ’rules.txt’ }
to load the external rules file named rules.txt. You can only specify one file this way but rules files can include other rules files
with the include statement. In addition you can load rules like:
$ sort -c snort.lua -R rules.txt
You can use both approaches together.
1.2.5

Converting Your 2.X Configuration

If you have a working 2.X configuration snort2lua makes it easy to get up and running with Snort 3. This tool will convert your
configuration and/or rules files automatically. You will want to clean up the results and double check that it is doing exactly what
you need.
snort2lua -c snort.conf
The above command will generate snort.lua based on your 2.X configuration. For more information and options for more
sophisticated use cases, see the Snort2Lua section later in the manual.

Snort 3 User Manual

1.3

6 / 290

Output

Snort can produce quite a lot of data. In the following we will summarize the key aspects of the core output types. Additional
data such as from appid is covered later.
1.3.1

Basic Statistics

At shutdown, Snort will output various counts depending on configuration and the traffic processed. Generally, you may see:
• Packet Statistics - this includes data from the DAQ and decoders such as the number of packets received and number of UDP
packets.
• Module Statistics - each module tracks activity via a set of peg counts that indicate how many times something was observed
or performed. This might include the number of HTTP GET requests processed and the number of TCP reset packets trimmed.
• File Statistics - look here for a breakdown of file type, bytes, signatures.
• Summary Statistics - this includes total runtime for packet processing and the packets per second. Profiling data will appear
here as well if configured.
Note that only the non-zero counts are output. Run this to see the available counts:
$ snort --help-counts

1.3.2

Alerts

If you configured rules, you will need to configure alerts to see the details of detection events. Use the -A option like this:
$ snort -c snort.lua -r a.pcap -A cmg
There are many types of alert outputs possible. Here is a brief list:
• -A cmg is the same as -A fast -d -e and will show information about the alert along with packet headers and payload.
• -A u2 is the same as -A unified2 and will log events and triggering packets in a binary file that you can feed to other tools
for post processing. Note that Snort 3 does not provide the raw packets for alerts on PDUs; you will get the actual buffer that
alerted.
• -A csv will output various fields in comma separated value format. This is entirely customizable and very useful for pcap
analysis.
To see the available alert types, you can run this command:
$ snort --list-plugins | grep logger

1.3.3

Files and Paths

Note that output is specific to each packet thread. If you run 4 packet threads with u2 output, you will get 4 different u2 files.
The basic structure is:
/[][][]
where:
• logdir is set with -l and defaults to ./

Snort 3 User Manual

7 / 290

• run_prefix is set with --run-prefix else not used
• id# is the packet thread number that writes the file; with one packet thread, id# (zero) is omitted without --id-zero
• X is / if you use --id-subdir, else _ if id# is used
• name is based on module name that writes the file
Additional considerations:
• There is no way to explicitly configure a full path to avoid issues with multiple packet threads.
• All text mode outputs default to stdout
1.3.4

Performance Statistics

Still more data is available beyond the above.
• By configuring the perf_monitor module you can capture a configurable set of peg counts during runtime. This is useful to
feed to an external program so you can see what is happening without stopping Snort.
• The profiler module allows you to track time and space used by module and rules. Use this data to tune your system for best
performance. The output will show up under Summary Statistics at shutdown.

2

Concepts

This section provides background on essential aspects of Snort’s operation.

2.1

Terminology

• basic module: a module integrated into Snort that does not come from a plugin.
• binder: inspector that maps configuration to traffic
• builtin rules: codec and inspector rules for anomalies detected internally.
• codec: short for coder / decoder. These plugins are used for basic protocol decoding, anomaly detection, and construction of
active responses.
• data module: an adjunct configuration plugin for use with certain inspectors.
• dynamic rules: plugin rules loaded at runtime. See SO rules.
• fast pattern: the content in an IPS rule that must be found by the search engine in order for a rule to be evaluated.
• fast pattern matcher: see search engine.
• hex: a type of protocol magic that the wizard uses to identify binary protocols.
• inspector: plugin that processes packets (similar to the Snort 2 preprocessor)
• IPS: intrusion prevention system, like Snort.
• IPS action: plugin that allows you to perform custom actions when events are generated. Unlike loggers, these are invoked
before thresholding and can be used to control external agents or send active responses.
• IPS option: this plugin is the building blocks of IPS rules.
• logger: a plugin that performs output of events and packets. Events are thresholded before reaching loggers.

Snort 3 User Manual

8 / 290

• module: the user facing portion of a Snort component. Modules chiefly provide configuration parameters, but may also provide
commands, builtin rules, profiling statistics, peg counts, etc. Note that not all modules are plugins and not all plugins have
modules.
• peg count: the number of times a given event or condition occurs.
• plugin: one of several types of software components that can be loaded from a dynamic library when Snort starts up. Some
plugins are coupled with the main engine in such a way that they must be built statically, but a newer version can be loaded
dynamically.
• search engine: a plugin that performs multipattern searching of packets and payload to find rules that should be evaluated.
There are currently no specific modules, although there are several search engine plugins. Related configuration is done with
the basic detection module. Aka fast pattern matcher.
• SO rule: a IPS rule plugin that performs custom detection that can’t be done by a text rule. These rules typically do not have
associated modules. SO comes from shared object, meaning dynamic library.
• spell: a type of protocol magic that the wizard uses to identify ASCII protocols.
• text rule: a rule loaded from the configuration that has a header and body. The header specifies action, protocol, source and
destination IP addresses and ports, and direction. The body specifies detection and non-detection options.
• wizard: inspector that applies protocol magic to determine which inspectors should be bound to traffic absent a port specific
binding. See hex and spell.

2.2

Modules

Modules are the building blocks of Snort. They encapsulate the types of data that many components need including parameters,
peg counts, profiling, builtin rules, and commands. This allows Snort to handle them generically and consistently. You can learn
quite a lot about any given module from the command line. For example, to see what stream_tcp is all about, do this:
$ snort --help-config stream_tcp
Modules are configured using Lua tables with the same name. So the stream_tcp module is configured with defaults like this:
stream_tcp = { }
The earlier help output showed that the default session tracking timeout is 30 seconds. To change that to 60 seconds, you can
configure it this way:
stream_tcp = { session_timeout = 60 }
Or this way:
stream_tcp = { }
stream_tcp.session_timeout = 60
More on parameters is given in the next section.
Other things to note about modules:
• Shutdown output will show the non-zero peg counts for all modules. For example, if stream_tcp did anything, you would see
the number of sessions processed among other things.
• Providing the builtin rules allows the documentation to include them automatically and also allows for autogenerating the rules
at startup.
• Only a few module provide commands at this point, most notably the snort module.

Snort 3 User Manual

2.3

9 / 290

Parameters

Parameters are given with this format:
type name = default: help { range }
The following types are used:
• addr: any valid IP4 or IP6 address or CIDR
• addr_list: a space separated list of addr values
• bit_list: a list of consecutive integer values from 1 to the range maximum
• bool: true or false
• dynamic: a select type determined by loaded plugins
• enum: a string selected from the given range
• implied: an IPS rule option that takes no value but means true
• int: a whole number in the given range
• interval: a set of ints (see below)
• ip4: an IP4 address or CIDR
• mac: an ethernet address with the form 01:02:03:04:05:06
• multi: one or more space separated strings from the given range
• port: an int in the range 0:65535 indicating a TCP or UDP port number
• real: a real number in the given range
• select: a string selected from the given range
• string: any string with no more than the given length, if any
The parameter name may be adorned in various ways to indicate additional information about the type and use of the parameter:
• For Lua configuration (not IPS rules), if the name ends with [] it is a list item and can be repeated.
• For IPS rules only, names starting with ~ indicate positional parameters. The names of such parameters do not appear in the
rule.
• IPS rules may also have a wild card parameter, which is indicated by a *. Used for unquoted, comma-separated lists such as
service and metadata.
• The snort module has command line options starting with a -.
Some additional details to note:
• Table and variable names are case sensitive; use lower case only.
• String values are case sensitive too; use lower case only.
• Numeric ranges may be of the form low:high where low and high are bounds included in the range. If either is omitted, there
is no hard bound. E.g. 0: means any x where x >= 0.
• Strings may have a numeric range indicating a length limit; otherwise there is no hard limit.
• bit_list is typically used to store a set of byte, port, or VLAN ID values.
• interval takes the form [operator]i, j<>k, or j<⇒k where i,j,k are integers and operator is one of =, !, != (same as !), <, ⇐, >,
>=. j<>k means j < int < k and j<⇒k means j ⇐ int ⇐ k.

Snort 3 User Manual

2.4

10 / 290

Plugins

Snort uses a variety of plugins to accomplish much of its processing objectives, including:
• Codec - to decode and encode packets
• Inspector - like Snort 2 preprocessors, for normalization, etc.
• IpsOption - for detection in Snort rules
• IpsAction - for custom actions
• Logger - for handling events
• Mpse - for fast pattern matching
• So - for dynamic rules
The power of plugins is that they have a very focused purpose and can be created with relative ease. For example, you can extend
the rule language by writing your own IpsOption and it will plug in and function just like existing options. The extra directory
has examples of each type of plugin.
Most plugins can be built statically or dynamically. By default they are all static. There is no difference in functionality between
static or dynamic plugins but the dynamic build generates a slightly lighter weight binary. Either way you can add dynamic
plugins with --plugin-path and newer versions will replace older versions, even when built statically.
A single dynamic library may contain more than one plugin. For example, an inspector will typically be packaged together with
any associated rule options.

2.5

Operation

Snort is a signature-based IPS, which means that as it receives network packets it reassembles and normalizes the content so that
a set of rules can be evaluated to detect the presence of any significant conditions that merit further action. A rough processing
flow is as follows:

The steps are:
1. Decode each packet to determine the basic network characteristics such as source and destination addresses and ports.
A typical packet might have ethernet containing IP containing TCP containing HTTP (ie eth:ip:tcp:http). The various
encapsulating protocols are examined for sanity and anomalies as the packet is decoded. This is essentially a stateless
effort.
2. Preprocess each decoded packet using accumulated state to determine the purpose and content of the innermost message.
This step may involve reordering and reassembling IP fragments and TCP segments to produce the original application
protocol data unit (PDU). Such PDUs are analyzed and normalized as needed to support further processing.
3. Detection is a two step process. For efficiency, most rules contain a specific content pattern that can be searched for such
that if no match is found no further processing is necessary. Upon start up, the rules are compiled into pattern groups such
that a single, parallel search can be done for all patterns in the group. If any match is found, the full rule is examined
according to the specifics of the signature.
4. The logging step is where Snort saves any pertinent information resulting from the earlier steps. More generally, this is
where other actions can be taken as well such as blocking the packet.

Snort 3 User Manual

2.5.1

11 / 290

Snort 2 Processing

The preprocess step in Snort 2 is highly configurable. Arbitrary preprocessors can be loaded dynamically at startup, configured
in snort.conf, and then executed at runtime. Basically, the preprocessors are put into a list which is iterated for each packet.
Recent versions have tweaked the list handling some, but the same basic architecture has allowed Snort 2 to grow from a sniffer,
with no preprocessing, to a full-fledged IPS, with lots of preprocessing.
While this "list of plugins" approach has considerable flexibility, it hampers future development when the flow of data from one
preprocessor to the next depends on traffic conditions, a common situation with advanced features like application identification.
In this case, a preprocessor like HTTP may be extracting and normalizing data that ultimately is not used, or appID may be
repeatedly checking for data that is just not available.
Callbacks help break out of the preprocess straitjacket. This is where one preprocessor supplies another with a function to call
when certain data is available. Snort has started to take this approach to pass some HTTP and SIP preprocessor data to appID.
However, it remains a peripheral feature and still requires the production of data that may not be consumed.
2.5.2

Snort 3 Processing

One of the goals of Snort 3 is to provide a more flexible framework for packet processing by implementing an event-driven
approach. Another is to produce data only when needed to minimize expensive normalizations. However, the basic packet
processing provides very similar functionality.
The basic processing steps Snort 3 takes are similar to Snort 2 as seen in the following diagram. The preprocess step employs
specific inspector types instead of a generalized list, but the basic procedure includes stateless packet decoding, TCP stream
reassembly, and service specific analysis in both cases. (Snort 3 provides hooks for arbitrary inspectors, but they are not central
to basic flow processing and are not shown.)

However, Snort 3 also provides a more flexible mechanism than callback functions. By using inspection events, it is possible for
an inspector to supply data that other inspectors can process. This is known as the observer pattern or publish-subscribe pattern.
Note that the data is not actually published. Instead, access to the data is published, and that means that subscribers can access
the raw or normalized version(s) as needed. Normalizations are done only on the first access, and subsequent accesses get the
previously normalized data. This results in just in time (JIT) processing.
A basic example of this in action is provided by the extra data_log plugin. It is a passive inspector, ie it does nothing until it
receives the data it subscribed for (other in the above diagram). By adding the following to your snort.lua configuration, you will
get a simple URI logger.
data_log = { key = ’http_raw_uri’ }
Inspection events coupled with pluggable inspectors provide a very flexible framework for implementing new features. And JIT
buffer stuffers allow Snort to work smarter, not harder. These capabilities will be leveraged more and more as Snort development
continues.

2.6

Rules

Rules tell Snort how to detect interesting conditions, such as an attack, and what to do when the condition is detected. Here is an
example rule:

Snort 3 User Manual

12 / 290

alert tcp any any -> 192.168.1.1 80 ( msg:"A ha!"; content:"attack"; sid:1; )
The structure is:
action proto source dir dest ( body )
Where:
action - tells Snort what to do when a rule "fires", ie when the signature matches. In this case Snort will log the event. It can also
do thing like block the flow when running inline.
proto - tells Snort what protocol applies. This may be ip, icmp, tcp, udp, http, etc.
source - specifies the sending IP address and port, either of which can be the keyword any, which is a wildcard.
dir - must be either unidirectional as above or bidirectional indicated by <>.
dest - similar to source but indicates the receiving end.
body - detection and other information contained in parenthesis.
There are many rule options available to construct as sophisticated a signature as needed. In this case we are simply looking for
the "attack" in any TCP packet. A better rule might look like this:
alert http
(
msg:"Gotcha!";
flow:established, to_server;
http_uri:"attack";
sid:2;
)
Note that these examples have a sid option, which indicates the signature ID. In general rules are specified by gid:sid:rev notation,
where gid is the generator ID and rev is the revision of the rule. By default, text rules are gid 1 and shared-object (SO) rules are
gid 3. The various components within Snort that generate events have 1XX gids, for example the decoder is gid 116. You can
list the internal gids and sids with these commands:
$ snort --list-gids
$ snort --list-builtin
For details on these and other options, see the reference section.

2.7

Pattern Matching

Snort evaluates rules in a two-step process which includes a fast pattern search and full evaluation of the signature. More details
on this process follow.
2.7.1

Rule Groups

When Snort starts or reloads configuration, rules are grouped by protocol, port and service. For example, all TCP rules using
the HTTP_PORTS variable will go in one group and all service HTTP rules will go in another group. These rule groups are
compiled into multipattern search engines (MPSE) which are designed to search for all patterns with just a single pass through
a given packet or buffer. You can select the algorithm to use for fast pattern searches with search_engine.search_method which
defaults to ac_bnfa, which balances speed and memory. For a faster search at the expense of significantly more memory, use
ac_full. For best performance and reasonable memory, download the hyperscan source from Intel.

Snort 3 User Manual

2.7.2

13 / 290

Fast Patterns

Fast patterns are content strings that have the fast_pattern option or which have been selected by Snort automatically to be used
as a fast pattern. Snort will by default choose the longest pattern in the rule since that is likely to be most unique. That is not
always the case so add fast_pattern to the appropriate content option for best performance. The ideal fast pattern is one which,
if found, is very likely to result in a rule match. Fast patterns that match frequently for unrelated traffic will cause Snort to work
hard with little to show for it.
Certain contents are not eligible to be used as fast patterns. Specifically, if a content is negated, then if it is also relative to another
content, case sensitive, or has non-zero offset or depth, then it is not eligible to be used as a fast pattern.
2.7.3

Rule Evaluation

For each fast pattern match, the corresponding rule(s) are evaluated left-to-right. Rule evaluation requires checking each detection
option in a rule and is a fairly costly process which is why fast patterns are so important. Rule evaluation aborts on the first nonmatching option.
When rule evaluation takes place, the fast pattern match will automatically be skipped if possible. Note that this differs from
Snort 2 which provided the fast_pattern:only option to designate such cases. This is one less thing for the rule writer to worry
about.

3

Tutorial

The section will walk you through building and running Snort. It is not exhaustive but, once you master this material, you should
be able to figure out more advanced usage.

3.1

Dependencies

Required:
• autotools or cmake to build from source
• daq from http://www.snort.org for packet IO
• g++ >= 4.8 or other recent C++11 compiler
• dnet from https://github.com/dugsong/libdnet.git for network utility functions
• hwloc from https://www.open-mpi.org/projects/hwloc/ for CPU affinity management
• LuaJIT from http://luajit.org for configuration and scripting
• OpenSSL from https://www.openssl.org/source/ for SHA and MD5 file signatures, the protected_content rule option, and SSL
service detection
• pcap from http://www.tcpdump.org for tcpdump style logging
• pcre from http://www.pcre.org for regular expression pattern matching
• pkgconfig from https://www.freedesktop.org/wiki/Software/pkg-config/ to locate build dependencies
• zlib from http://www.zlib.net for decompression (>= 1.2.8 recommended)
Optional:
• asciidoc from http://www.methods.co.nz/asciidoc/ to build the HTML manual
• cpputest from http://cpputest.github.io to run additional unit tests with make check

Snort 3 User Manual

14 / 290

• dblatex from http://dblatex.sourceforge.net to build the pdf manual (in addition to asciidoc)
• flatbuffers from https://google.github.io/flatbuffers/ for enabling the flatbuffers serialization format
• hyperscan >= 4.4.0 from https://github.com/01org/hyperscan to build new the regex and sd_pattern rule options and hyperscan
search engine
• iconv from https://ftp.gnu.org/pub/gnu/libiconv/ for converting UTF16-LE filenames to UTF8 (usually included in glibc)
• lzma >= 5.1.2 from http://tukaani.org/xz/ for decompression of SWF and PDF files
• safec from https://sourceforge.net/projects/safeclib/ for runtime bounds checks on certain legacy C-library calls
• source-highlight from http://www.gnu.org/software/src-highlite/ to generate the dev guide
• w3m from http://sourceforge.net/projects/w3m/ to build the plain text manual
• uuid from uuid-dev package for unique identifiers

3.2

Building

• Optionally built features are listed in the reference section.
• Create an install path:
export my_path=/path/to/snorty
mkdir -p $my_path
• If you are using a github clone with autotools, do this:
autoreconf -isvf
• Now do one of the following:
a. To build with cmake and make, run configure_cmake.sh. It will automatically create and populate a new subdirectory
named build.
./configure_cmake.sh --prefix=$my_path
cd build
make -j 8
make install
ln -s $my_path/conf $my_path/etc
b. You can also specify a cmake project generator:
./configure_cmake.sh --generator=Xcode --prefix=$my_path
c. Or use ccmake directly to configure and generate from an arbitrary build directory like one of these:
ccmake -G Xcode /path/to/Snort++/tree
open snort.xcodeproj
ccmake -G "Eclipse CDT4 - Unix Makefiles" /path/to/Snort++/tree
run eclipse and do File > Import > Existing Eclipse Project
• To build with g++ on OS X where clang is installed, do this first:
export CXX=g++

Snort 3 User Manual

3.3

15 / 290

Running

First set up the environment:
export LUA_PATH=$my_path/include/snort/lua/\?.lua\;\;
export SNORT_LUA_PATH=$my_path/etc/snort/
Then give it a go:
• Get some help:
$my_path/bin/snort --help
$my_path/bin/snort --help-module suppress
$my_path/bin/snort --help-config | grep thread
• Examine and dump a pcap:
$my_path/bin/snort -r 
$my_path/bin/snort -L dump -d -e -q -r 
• Verify config, with or w/o rules:
$my_path/bin/snort -c $my_path/etc/snort/snort.lua
$my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample. ←rules
• Run IDS mode. To keep it brief, look at the first n packets in each file:
$my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample. ←rules \
-r  -A alert_test -n 100000
• Let’s suppress 1:2123. We could edit the conf or just do this:
$my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample. ←rules \
-r  -A alert_test -n 100000 --lua "suppress = { { gid = 1, sid = 2123 } ←}"
• Go whole hog on a directory with multiple packet threads:
$my_path/bin/snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample. ←rules \
--pcap-filter \*.pcap --pcap-dir  -A alert_fast -n 1000 --max-packet- ←threads 8

For more examples, see the usage section.

3.4

Tips

One of the goals of Snort 3 is to make it easier to configure your sensor. Here is a summary of tips and tricks you may find useful.
General Use
• Snort tries hard not to error out too quickly. It will report multiple semantic errors.

Snort 3 User Manual

16 / 290

• Snort always assumes the simplest mode of operation. Eg, you can omit the -T option to validate the conf if you don’t provide
a packet source.
• Warnings are not emitted unless --warn-* is specified. --warn-all enables all warnings, and --pedantic makes such warnings
fatal.
• You can process multiple sources at one time by using the -z or --max-threads option.
• To make it easy to find the important data, zero counts are not output at shutdown.
• Load plugins from the command line with --plugin-path /path/to/install/lib.
• You can process multiple sources at one time by using the -z or --max-threads option.
• Unit tests are configured with --enable-unit-tests. They can then be run with snort --catch-test [tags]|all.
Lua Configuration
• Configure the wizard and default bindings will be created based on configured inspectors. No need to explicitly bind ports in
this case.
• You can override or add to your Lua conf with the --lua command line option.
• The Lua conf is a live script that is executed when loaded. You can add functions, grab environment variables, compute values,
etc.
• You can also rename symbols that you want to disable. For example, changing normalizer to Xnormalizer (an unknown
symbol) will disable the normalizer. This can be easier than commenting in some cases.
• By default, symbols unknown to Snort are silently ignored. You can generate warnings for them with --warn-unknown. To
ignore such symbols, export them in the environment variable SNORT_IGNORE.
Writing and Loading Rules
Snort rules allow arbitrary whitespace. Multi-line rules make it easier to structure your rule for clarity. There are multiple ways
to add comments to your rules:
• The # character starts a comment to end of line. In addition, all lines between #begin and #end are comments.
• The rem option allows you to write a comment that is conveyed with the rule.
• C style multi-line comments are allowed, which means you can comment out portions of a rule while testing it out by putting
the options between /* and */.
There are multiple ways to load rules too:
• Set ips.rules or ips.include.
• include statements can be used in rules files.
• Use -R to load a rules file.
• Use --stdin-rules with command line redirection.
• Use --lua to specify one or more rules as a command line argument.
Output Files
To make it simple to configure outputs when you run with multiple packet threads, output files are not explicitly configured.
Instead, you can use the options below to format the paths:
/[][][]

Snort 3 User Manual

• logdir is set with -l and defaults to ./
• run_prefix is set with --run-prefix else not used
• id# is the packet thread number that writes the file; with one packet thread, id# (zero) is omitted without --id-zero
• X is / if you use --id-subdir, else _ if id# is used
• name is based on module name that writes the file
• all text mode outputs default to stdout

3.5

Help

Snort has several options to get more help:
-? list command line options (same as --help)
--help this overview of help
--help-commands [] output matching commands
--help-config [] output matching config options
--help-counts [] output matching peg counts
--help-module  output description of given module
--help-modules list all available modules with brief help
--help-plugins list all available plugins with brief help
--help-options [] output matching command line options
--help-signals dump available control signals
--list-buffers output available inspection buffers
--list-builtin [] output matching builtin rules
--list-gids [] output matching generators
--list-modules [] list all known modules
--list-plugins list all known modules
--show-plugins list module and plugin versions
--help* and --list* options preempt other processing so should be last on the
command line since any following options are ignored. To ensure options like
--markup and --plugin-path take effect, place them ahead of the help or list
options.
Options that filter output based on a matching prefix, such as --help-config
won’t output anything if there is no match. If no prefix is given, everything
matches.
Report bugs to bugs@snort.org.

3.6

Common Errors

FATAL: snort_config is required
• add this line near top of file:
require(’snort_config’)

PANIC: unprotected error in call to Lua API (cannot open snort_defaults.lua: No such file or directory)
• export SNORT_LUA_PATH to point to any dofiles
ERROR can’t find xyz

17 / 290

Snort 3 User Manual

18 / 290

• if xyz is the name of a module, make sure you are not assigning a scalar where a table is required (e.g. xyz = 2 should be xyz
= { }).
ERROR can’t find x.y
• module x does not have a parameter named y. check --help-module x for available parameters.
ERROR invalid x.y = z
• the value z is out of range for x.y. check --help-config x.y for the range allowed.
ERROR: x = { y = z } is in conf but is not being applied
• make sure that x = { } isn’t set later because it will override the earlier setting. same for x.y.
FATAL: can’t load lua/errors.lua: lua/errors.lua:68: = expected near ’;’
• this is a syntax error reported by Lua to Snort on line 68 of errors.lua.
ERROR: rules(2) unknown rule keyword: find.
• this was due to not including the --script-path.
WARNING: unknown symbol x
• if you any variables, you can squelch such warnings by setting them in an environment variable SNORT_IGNORE. to ignore
x, y, and z:
export SNORT_IGNORE="x y z"

3.7

Gotchas

• A nil key in a table will not caught. Neither will a nil value in a table. Neither of the following will cause errors, nor will they
actually set http_server.post_depth:
http_server = { post_depth }
http_server = { post_depth = undefined_symbol }
• It is not an error to set a value multiple times. The actual value applied may not be the last in the table either. It is best to avoid
such cases.
http_server =
{
post_depth = 1234,
post_depth = 4321
}
• Snort can’t tell you the exact filename or line number of a semantic error but it will tell you the fully qualified name.
• The dump DAQ will not work with multiple threads unless you use --daq-var file=/dev/null. This will be fixed in at some point
to use the Snort log directory, etc.
• configure will use clang by default if it is installed.To compile with g instead:
export CXX=g++

Snort 3 User Manual

19 / 290

• If you build with hyperscan on OS X and see:
dyld: Library not loaded: @rpath/libhs.4.0.dylib
when you try to run src/snort, export DYLD_LIBRARY_PATH with the path to
libhs. You can also do:
install_name_tool -change @rpath/libhs.4.0.dylib \
/path-to/libhs.4.0.dylib src/snort

4

Usage

For the following examples "$my_path" is assumed to be the path to the Snort install directory. Additionally, it is assumed that
"$my_path/bin" is in your PATH.

4.1

Environment

LUA_PATH is used directly by Lua to load and run required libraries. SNORT_LUA_PATH is used by Snort to load supplemental
configuration files.
export LUA_PATH=$my_path/include/snort/lua/\?.lua\;\;
export SNORT_LUA_PATH=$my_path/etc/snort

4.2

Help

Print the help summary:
snort --help
Get help on a specific module ("stream", for example):
snort --help-module stream
Get help on the "-A" command line option:
snort --help-options A
Grep for help on threads:
snort --help-config | grep thread
Output help on "rule" options in AsciiDoc format:
snort --markup --help-options rule

Note
Snort stops reading command-line options after the "--help-" and "--list-" options, so any other options should be placed before
them.

Snort 3 User Manual

4.3

20 / 290

Sniffing and Logging

Read a pcap:
snort -r /path/to/my.pcap
Dump the packets to stdout:
snort -r /path/to/my.pcap -L dump
Dump packets with application data and layer 2 headers
snort -r /path/to/my.pcap -L dump -d -e

Note
Command line options must be specified separately. "snort -de" won’t work. You can still concatenate options and their
arguments, however, so "snort -Ldump" will work.

Dump packets from all pcaps in a directory:
snort --pcap-dir /path/to/pcap/dir --pcap-filter ’*.pcap’ -L dump -d -e
Log packets to a directory:
snort --pcap-dir /path/to/pcap/dir --pcap-filter ’*.pcap’ -L dump -l /path/to/log/ ←dir

4.4

Configuration

Validate a configuration file:
snort -c $my_path/etc/snort/snort.lua
Validate a configuration file and a separate rules file:
snort -c $my_path/etc/snort/snort.lua -R $my_path/etc/snort/sample.rules
Read rules from stdin and validate:
snort -c $my_path/etc/snort/snort.lua --stdin-rules < $my_path/etc/snort/sample. ←rules
Enable warnings for Lua configurations and make warnings fatal:
snort -c $my_path/etc/snort/snort.lua --warn-all --pedantic
Tell Snort where to look for additional Lua scripts:
snort --script-path /path/to/script/dir

Snort 3 User Manual

4.5

21 / 290

IDS mode

Run Snort in IDS mode, reading packets from a pcap:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap
Log any generated alerts to the console using the "-A" option:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A alert_full
Capture separate stdout, stderr, and stdlog files (out has startup and shutdown output, err has warnings and errors, and log has
alerts):
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A csv \
1>out 2>err 3>log
Add or modify a configuration from the command line using the "--lua" option:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A cmg \
--lua ’ips = { enable_builtin_rules = true }’

Note
The "--lua" option can be specified multiple times.

Run Snort in IDS mode on an entire directory of pcaps, processing each input source on a separate thread:
snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
--pcap-filter ’*.pcap’ --max-packet-threads 8
Run Snort on 2 interfaces, eth0 and eth1:
snort -c $my_path/etc/snort/snort.lua -i "eth0 eth1" -z 2 -A cmg
Run Snort inline with the afpacket DAQ:
snort -c $my_path/etc/snort/snort.lua --daq afpacket -i "eth0:eth1" \
-A cmg

4.6

Plugins

Load external plugins and use the "ex" alert:
snort -c $my_path/etc/snort/snort.lua \
--plugin-path $my_path/lib/snort_extra \
-A alert_ex -r /path/to/my.pcap
Test the LuaJIT rule option find loaded from stdin:
snort -c $my_path/etc/snort/snort.lua \
--script-path $my_path/lib/snort_extra \
--stdin-rules -A cmg -r /path/to/my.pcap << END
alert tcp any any -> any 80 (
sid:3; msg:"found"; content:"GET";
find:"pat=’HTTP/1%.%d’" ; )
END

Snort 3 User Manual

4.7

22 / 290

Output Files

To make it simple to configure outputs when you run with multiple packet threads, output files are not explicitly configured.
Instead, you can use the options below to format the paths:
/[][][]
Log to unified in the current directory:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2
Log to unified in the current directory with a different prefix:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2 \
--run-prefix take2
Log to unified in /tmp:
snort -c $my_path/etc/snort/snort.lua -r /path/to/my.pcap -A unified2 -l /tmp
Run 4 packet threads and log with thread number prefix (0-3):
snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
--pcap-filter ’*.pcap’ -z 4 -A unified2
Run 4 packet threads and log in thread number subdirs (0-3):
snort -c $my_path/etc/snort/snort.lua --pcap-dir /path/to/pcap/dir \
--pcap-filter ’*.pcap’ -z 4 -A unified2 --id-subdir

Note
subdirectories are created automatically if required. Log filename is based on module name that writes the file. All text mode
outputs default to stdout. These options can be combined.

4.8

DAQ Alternatives

Process hext packets from stdin:
snort -c $my_path/etc/snort/snort.lua \
--daq-dir $my_path/lib/snort/daqs --daq hext -i tty << END
$packet 10.1.2.3 48620 -> 10.9.8.7 80
"GET / HTTP/1.1\r\n"
"Host: localhost\r\n"
"\r\n"
END
Process raw ethernet from hext file:
snort -c $my_path/etc/snort/snort.lua \
--daq-dir $my_path/lib/snort/daqs --daq hext \
--daq-var dlt=1 -r 
Process a directory of plain files (ie non-pcap) with 4 threads with 8K buffers:
snort -c $my_path/etc/snort/snort.lua \
--daq-dir $my_path/lib/snort/daqs --daq file \
--pcap-dir path/to/files -z 4 -s 8192

Snort 3 User Manual

23 / 290

Bridge two TCP connections on port 8000 and inspect the traffic:
snort -c $my_path/etc/snort/snort.lua \
--daq-dir $my_path/lib/snort/daqs --daq socket

4.9

Logger Alternatives

Dump TCP stream payload in hext mode:
snort -c $my_path/etc/snort/snort.lua -L hext
Output timestamp, pkt_num, proto, pkt_gen, dgm_len, dir, src_ap, dst_ap, rule, action for each alert:
snort -c $my_path/etc/snort/snort.lua -A csv
Output the old test format alerts:
snort -c $my_path/etc/snort/snort.lua \
--lua "alert_csv = { fields = ’pkt_num gid sid rev’, separator = ’\t’ }"

4.10

Shell

You must build with --enable-shell to make the command line shell available.
Enable shell mode:
snort --shell 
You will see the shell mode command prompt, which looks like this:
o")~
(The prompt can be changed with the SNORT_PROMPT environment variable.)
You can pause immediately after loading the configuration and again before exiting with:
snort --shell --pause 
In that case you must issue the resume() command to continue. Enter quit() to terminate Snort or detach() to exit the shell. You
can list the available commands with help().
To enable local telnet access on port 12345:
snort --shell -j 12345 
The command line interface is still under development. Suggestions are welcome.

4.11

Signals

Note
The following examples assume that Snort is currently running and has a process ID of .

Modify and Reload Configuration:
echo ’suppress = { { gid = 1, sid = 2215 } }’ >> $my_path/etc/snort/snort.lua
kill -hup 

Snort 3 User Manual

24 / 290

Dump stats to stdout:
kill -usr1 
Shutdown normally:
kill -term 
Exit without flushing packets:
kill -quit 
List available signals:
snort --help-signals

Note
The available signals may vary from platform to platform.

5

Features

This section explains how to use key features of Snort.

5.1

AppId

Network administrators need application awareness in order to fine tune their management of the ever-growing number of applications passing traffic over the network. Application awareness allows an administrator to create rules for applications as needed
by the business. The rules can be used to take action based on the application, such as block, allow or alert.
5.1.1

Overview

The AppId inspector provides an application level view when managing networks by providing the following features:
• Network control: The inspector works with Snort rules by providing a set of application identifiers (AppIds) to Snort rule
writers.
• Application usage awareness: The inspector outputs statistics to show how many times applications are being used on the
network.
• Custom applications: Administrators can create their own application detectors to detect new applications. The detectors are
written in Lua and interface with Snort using a well-defined C-Lua API.
• Open Detector Package (ODP): A set of pre-defined application detectors are provided by the Snort team and can be downloaded from snort.org.
5.1.2

Dependency Requirements

For proper functioning of the AppId inspector, at a minimum stream flow tracking must be enabled. In addition, to identify
TCP-based or UDP-based applications then the appropriate stream inspector must be enabled, e.g. stream_tcp or stream_udp.
In addition, in order to identify HTTP-based applications, the HTTP inspector must be enabled. Otherwise, only non-HTTP
applications will be identified.
AppId subscribes to the inspection events published by other inspectors, such as the HTTP and SSL inspectors, to gain access to
the data needed. It uses that data to help determine the application ID.

Snort 3 User Manual

5.1.3

25 / 290

Configuration

The AppId feature can be enabled via configuration. To enable it with the default settings use:
appid = { }
To use an AppId as a matching parameter in an IPS rule, use the appids keyword. For example, to block HTTP traffic that
contains a specific header:
block tcp any any -> 192.168.0.1 any ( msg:"Block Malicious HTTP header";
appids:"HTTP"; content:"X-Header: malicious"; sid:18000; )
Alternatively, the HTTP application can be specified in place of tcp instead of using the appids keyword. The AppId inspector
will set the service when it is discovered so it can be used in IPS rules like this. Note that this rule also does not specify the IPs
or ports which default to any.
block http ( msg:"Block Malicious HTTP header";
content:"X-Header: malicious"; sid:18000; )
It’s possible to specify multiple applications (as many as desired) with the appids keyword. A rule is considered a match if any
of the applications on the rule match. Note that this rule does not match specific content which will reduce performance.
alert tcp any any -> 192.168.0.1 any ( msg:"Alert ";
appids:"telnet,ssh,smtp,http";
Below is a minimal Snort configuration that is sufficient to block flows based on a specific HTTP header:
require("snort_config")
dir = os.getenv(’SNORT_LUA_PATH’)
if ( not dir ) then
dir = ’.’
end
dofile(dir .. ’/snort_defaults.lua’)
local_rules =
[[
block http ( msg:"openAppId: test content match for app http";
content:"X-Header: malicious"; sid:18760; rev:4; )
]]
stream = { }
stream_tcp = { }
binder =
{
{
when =
{
proto = ’tcp’,
ports = [[ 80 8080 ]],
},
use =

Snort 3 User Manual

26 / 290

{
type = ’http_inspect’,
},
},
}
http_inspect = { }
appid = { }
ips =
{
rules = local_rules,
}

5.1.4

Session Application Identifiers

There are up to four AppIds stored in a session as defined below:
• serviceAppId - An appId associated with server side of a session. Example: http server.
• clientAppId - An appId associated with application on client side of a session. Example: Firefox.
• payloadAppId - For services like http this appId is associated with a webserver host. Example: Facebook.
• miscAppId - For some encapsulated protocols, this is the highest encapsulated application.
For packets originating from the client, a payloadAppid in a session is matched with all AppIds listed on a rule. Thereafter
miscAppId, clientAppId and serviceAppId are matched. Since Alert Events contain one AppId, only the first match is reported.
If a rule without an appids option matches, then the most specific appId (in order of payload, misc, client, server) is reported.
The same logic is followed for packets originating from the server with one exception. The order of matching is changed to make
serviceAppId come before clientAppId.
5.1.5

AppId Usage Statistics

The AppId inspector prints application network usage periodically in the snort log directory in unified2 format. File name, time
interval for statistic and file rollover are controlled by appId inspection configuration.
5.1.6

Open Detector Package (ODP) Installation

Application detectors from Snort team will be delivered in a separate package called the Open Detector Package (ODP) that can
be downloaded from snort.org. ODP is a package that contains the following artifacts:
• Application detectors in the Lua language.
• Port detectors, which are port only application detectors, in meta-data in YAML format.
• appMapping.data file containing application metadata. This file should not be modified. The first column contains application
identifier and second column contains application name. Other columns contain internal information.
• Lua library files DetectorCommon.lua, flowTrackerModule.lua and hostServiceTrackerModule.lua
A user can install the ODP package in any directory and configure this directory via the app_detector_dir option in the appid
preprocessor configuration. Installing ODP will not modify any subdirectory named custom, where user-created detectors are
located.
When installed, ODP will create following sub-directories:

Snort 3 User Manual

27 / 290

• odp/port //Cisco port-only detectors
• odp/lua //Cisco Lua detectors
• odp/libs //Cisco Lua modules
5.1.7

User Created Application Detectors

Users can detect new applications by adding detectors in the Lua language. A document will be posted on the Snort Website
with details on API. Users can also copy over Snort team provided detectors and modify them. Users can also use the detector
creation tool described in the next section.
Users must organize their Lua detectors and libraries by creating the following directory structure, under the ODP installation
directory.
• custom/port //port-only detectors
• custom/lua //Lua detectors
• custom/libs //Lua modules
The root path is specified by the "app_detector_dir" parameter of the appid section of snort.conf:
appid =
{
app_detector_dir = ’/usr/local/lib/openappid’,
}
So the path to the user-created lua files would be /usr/local/lib/openappid/custom/lua/
None of the directories below /usr/local/lib/openappid/ would be added for you.
5.1.8

Application Detector Creation Tool

For rudimentary Lua detectors, there is a tool provided called appid_detector_builder.sh. This is a simple, menu-driven bash
script which creates .lua files in your current directory, based on your choices and on patterns you supply.
When you launch the script, it will prompt for the Application Id that you are giving for your detector. This is free-form ASCII
with minor restrictions. The Lua detector file will be named based on your Application Id. If the file name already exists you
will be prompted to overwrite it.
You will also be prompted for a description of your detector to be placed in the comments of the Lua source code. This is
optional.
You will then be asked a series of questions designed to construct Lua code based on the kind of pattern data, protocol, port(s),
etc.
When complete, the Protocol menu will be changed to include the option, "Save Detector". Instead of saving the file and exiting
the script, you are allowed to give additional criteria for another pattern which may also be incorporated in the detection scheme.
Then either pattern, when matched, will be considered a valid detection.
For example, your first choices might create an HTTP detection pattern of "example.com", and the next set of choices would add
the HTTP detection pattern of "example.uk.co" (an equally fictional British counterpart). They would then co-exist in the Lua
detector, and either would cause a detection with the name you give for your Application Id.
The resulting .lua file will need to be placed in the directory, "custom/lua", described in the previous section of the README
above called "User Created Application Detectors"

Snort 3 User Manual

5.2

28 / 290

Binder

One of the fundamental differences between Snort 2 and Snort 3 concerns configuration related to networks and ports. Here is a
brief review of Snort 2 configuration for network and service related components:
• Snort’s configuration has a default policy and optional policies selected by VLAN or network (with config binding).
• Each policy contains a user defined set of preprocessor configurations.
• Each preprocessor has a default configuration and some support non-default configurations selected by network.
• Most preprocessors have port configurations.
• The default policy may also contain a list of ports to ignore.
In Snort 3, the above configurations are done in a single module called the binder. Here is an example:
binder =
{
-- allow all tcp port 22:
-- (similar to Snort 2 config ignore_ports)
{ when = { proto = ’tcp’, ports = ’22’ }, use = { action = ’allow’ } },
-- select a config file by vlan
-- (similar to Snort 2 config binding by vlan)
{ when = { vlans = ’1024’ }, use = { file = ’vlan.lua’ } },
-- use a non-default HTTP inspector for port 8080:
-- (similar to a Snort 2 targeted preprocessor config)
{ when = { nets = ’192.168.0.0/16’, proto = ’tcp’, ports = ’8080’ },
use = { name = ’alt_http’, type = ’http_inspect’ } },
-- use the default inspectors:
-- (similar to a Snort 2 default preprocessor config)
{ when = { proto = ’tcp’ }, use = { type = ’stream_tcp’ } },
{ when = { service = ’http’ }, use = { type = ’http_inspect’ } },
-- figure out which inspector to run automatically:
{ use = { type = ’wizard’ } }
}
Bindings are evaluated when a session starts and again if and when service is identified on the session. Essentially, the bindings
are a list of when-use rules evaluated from top to bottom. The first matching network and service configurations are applied.
binder.when can contain any combination of criteria and binder.use can specify an action, config file, or inspector configuration.

5.3
5.3.1

Byte rule options
byte_test

This rule option tests a byte field against a specific value (with operator). Capable of testing binary values or converting representative byte strings to their binary equivalent and testing them.
Snort uses the C operators for each of these operators. If the & operator is used, then it would be the same as using
if (data & value) { do_something(); }

Note: The bitmask option applies bitwise AND operator on the bytes converted. The result will be right-shifted by the number
of bits equal to the number of trailing zeros in the mask. This applies for the other rule options as well.

Snort 3 User Manual

29 / 290

Examples

alert tcp (byte_test:2, =, 568, 0, bitmask 0x3FF0;)
This example extracts 2 bytes at offset 0, performs bitwise and with bitmask 0x3FF0, shifts the result by 4 bits and compares to
568.
alert udp (byte_test:4, =, 1234, 0, string, dec;
msg:"got 1234!";)
alert udp (byte_test:8, =, 0xdeadbeef, 0, string, hex;
msg:"got DEADBEEF!";)

5.3.2

byte_jump

The byte_jump rule option allows rules to be written for length encoded protocols trivially. By having an option that reads the
length of a portion of data, then skips that far forward in the packet, rules can be written that skip over specific portions of
length-encoded protocols and perform detection in very specific locations.
Examples

alert tcp (content:"Begin";
byte_jump:0, 0, from_end, post_offset -6;
content:"end..", distance 0, within 5;
msg:"Content match from end of the payload";)
alert tcp (content:"catalog";
byte_jump:2, 1, relative, post_offset 2, bitmask 0x03f0;
byte_test:2, =, 968, 0, relative;
msg:"Bitmask applied on the 2 bytes extracted for byte_jump";)

5.3.3

byte_extract

The byte_extract keyword is another useful option for writing rules against length-encoded protocols. It reads in some number
of bytes from the packet payload and saves it to a variable. These variables can be referenced later in the rule, instead of using
hard-coded values.
Other options which use byte_extract variables

A byte_extract rule option detects nothing by itself. Its use is in extracting packet data for use in other rule options.
Here is a list of places where byte_extract variables can be used:
• content/uricontent: offset, depth, distance, within
• byte_test: offset, value
• byte_jump: offset, post_offset
• isdataat: offset

Snort 3 User Manual

30 / 290

Examples

alert tcp (byte_extract:1, 0, str_offset;
byte_extract:1, 1, str_depth;
content:"bad stuff", offset str_offset, depth str_depth;
msg:"Bad Stuff detected within field";)
alert tcp (content:"START"; byte_extract:1, 0, myvar, relative;
byte_jump:1, 3, relative, post_offset myvar;
content:"END", distance 6, within 3;
msg: "byte_jump - pass variable to post_offset";)
This example uses two variables.
The first variable keeps the offset of a string, read from a byte at offset 0. The second variable keeps the depth of a string, read
from a byte at offset 1. These values are used to constrain a pattern match to a smaller area.
alert tcp (content:"|04 63 34 35|", offset 4, depth 4;
byte_extract: 2, 0, var_match, relative, bitmask 0x03ff;
byte_test: 2, =, var_match, 2, relative;
msg:"Test value match, after applying bitmask on bytes extracted";)

5.3.4

byte_math

Perform a mathematical operation on an extracted value and a specified value or existing variable, and store the outcome in a
new resulting variable. These resulting variables can be referenced later in the rule, at the same places as byte_extract variables.
The syntax for this rule option is different. The order of the options is critical for the other rule options and can’t be changed. For
example, the first option is the number of bytes to extract. Here the name of the option is explicitly written, for example : bytes
2. The order is not important.
Note
Byte_math operations are performed on unsigned 32-bit values. When writing a rule it should be taken into consideration to
avoid wrap around.

Examples

alert tcp ( byte_math: bytes 2, offset 0, oper *, rvalue 10, result area;
byte_test:2,>,area,16;)
At the zero offset of the payload, extract 2 bytes and apply multiplication operation with value 10. Store result in variable area.
The area variable is given as input to byte_test value option.
Let’s consider 2 bytes of extracted data is 5. The rvalue is 10. Result variable area is 50 ( 5 * 10 ). Area variable can be used in
either byte_test offset/value options.
5.3.5

Testing Numerical Values

The rule options byte_test and byte_jump were written to support writing rules for protocols that have length encoded data. RPC
was the protocol that spawned the requirement for these two rule options, as RPC uses simple length based encoding for passing
data.
In order to understand why byte test and byte jump are useful, let’s go through an exploit attempt against the sadmind service.
This is the payload of the exploit:

Snort 3 User Manual

89
00
40
49
00
00
00
00
7f
7f
00
00
49
00
00
00
00
2e

09
00
28
54
00
00
00
00
00
00
00
00
54
00
00
00
00
2e

9c
00
3a
00
00
00
00
00
00
00
00
00
00
00
00
00
00
2f

e2
0a
10
00
00
00
00
00
01
01
1e
00
00
00
00
00
15
62

00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
00
2e
69

31 / 290

00
00
00
00
00
00
00
00
01
01
00
00
00
00
00
00
2e
6e

00
00
00
00
00
00
00
00
87
87
00
00
00
00
00
00
2f
2f

00
01
0a
00
00
00
06
04
88
88
00
3b
00
00
00
06
2e
73

00
00
4d
00
40
00
00
00
00
00
00
4d
00
00
00
73
2e
68

00
00
45
00
28
00
00
00
00
00
00
45
00
00
00
79
2f
00

00
00
54
00
3a
00
00
00
00
00
00
54
00
00
00
73
2e
00

02
01
41
00
14
00
00
00
0a
0a
00
41
00
00
00
74
2e
00

00
00
53
00
00
00
00
00
00
00
00
53
00
00
00
65
2f
00

01
00
50
00
07
00
00
00
00
00
00
50
00
00
00
6d
2e
00

87
00
4c
00
45
00
00
00
00
00
00
4c
00
00
00
00
2e
04

88
20
4f
00
df
00
00
04
04
11
00
4f
00
00
00
00
2f
1e

................
...............
@(:.....metasplo
it..............
........@(:...e.
................
................
................
................
................
................
.......;metasplo
it..............
................
................
........system..
....../../../../
../bin/sh.......

Let’s break this up, describe each of the fields, and figure out how to write a rule to catch this exploit.
There are a few things to note with RPC:
Numbers are written as uint32s, taking four bytes. The number 26 would show up as 0x0000001a.
Strings are written as a uint32 specifying the length of the string, the string, and then null bytes to pad the length of the string to
end on a 4-byte boundary. The string bob would show up as 0x00000003626f6200.
89
00
00
00
00
00
00
00

09
00
00
01
00
00
00
00

9c
00
00
87
00
00
00
00

e2
00
02
88
0a
01
01
20

##
40
00
4d

the next
28 3a 10
00 00 0a
45 54 41

-

the request id, a random uint32, unique to each request
rpc type (call = 0, response = 1)
rpc version (2)
rpc program (0x00018788 = 100232 = sadmind)
rpc program version (0x0000000a = 10)
rpc procedure (0x00000001 = 1)
credential flavor (1 = auth_unix)
length of auth_unix data (0x20 = 32)

32 bytes are the auth_unix data
- unix timestamp (0x40283a10 = 1076378128 = feb 10 01:55:28 2004 gmt)
- length of the client machine name (0x0a = 10)
53 50 4c 4f 49 54 00 00 - metasploit

00 00 00 00 - uid of requesting user (0)
00 00 00 00 - gid of requesting user (0)
00 00 00 00 - extra group ids (0)
00 00 00 00 - verifier flavor (0 = auth_null, aka none)
00 00 00 00 - length of verifier (0, aka none)
The rest of the packet is the request that gets passed to procedure 1 of sadmind.
However, we know the vulnerability is that sadmind trusts the uid coming from the client. sadmind runs any request where the
client’s uid is 0 as root. As such, we have decoded enough of the request to write our rule.
First, we need to make sure that our packet is an RPC call.
content:"|00 00 00 00|", offset 4, depth 4;

Snort 3 User Manual

32 / 290

Then, we need to make sure that our packet is a call to sadmind.
content:"|00 01 87 88|", offset 12, depth 4;
Then, we need to make sure that our packet is a call to the procedure 1, the vulnerable procedure.
content:"|00 00 00 01|", offset 20, depth 4;
Then, we need to make sure that our packet has auth_unix credentials.
content:"|00 00 00 01|", offset 24, depth 4;
We don’t care about the hostname, but we want to skip over it and check a number value after the hostname. This is where
byte_test is useful. Starting at the length of the hostname, the data we have is:
00 00 00 0a 4d 45 54 41 53 50 4c 4f 49 54 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00
We want to read 4 bytes, turn it into a number, and jump that many bytes forward, making sure to account for the padding that
RPC requires on strings. If we do that, we are now at:
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00
which happens to be the exact location of the uid, the value we want to check.
In English, we want to read 4 bytes, 36 bytes from the beginning of the packet, and turn those 4 bytes into an integer and jump
that many bytes forward, aligning on the 4-byte boundary. To do that in a Snort rule, we use:
byte_jump:4,36,align;
then we want to look for the uid of 0.
content:"|00 00 00 00|", within 4;
Now that we have all the detection capabilities for our rule, let’s put them all together.
content:"|00 00 00 00|",
content:"|00 01 87 88|",
content:"|00 00 00 01|",
content:"|00 00 00 01|",
byte_jump:4,36,align;
content:"|00 00 00 00|",

offset
offset
offset
offset

4, depth 4;
12, depth 4;
20, depth 4;
24, depth 4;

within 4;

The 3rd and fourth string match are right next to each other, so we should combine those patterns. We end up with:
content:"|00 00 00 00|",
content:"|00 01 87 88|",
content:"|00 00 00 01 00
byte_jump:4,36,align;
content:"|00 00 00 00|",

offset 4, depth 4;
offset 12, depth 4;
00 00 01|", offset 20, depth 8;
within 4;

If the sadmind service was vulnerable to a buffer overflow when reading the client’s hostname, instead of reading the length of
the hostname and jumping that many bytes forward, we would check the length of the hostname to make sure it is not too large.
To do that, we would read 4 bytes, starting 36 bytes into the packet, turn it into a number, and then make sure it is not too large
(let’s say bigger than 200 bytes). In Snort, we do:
byte_test:4,>,200,36;

Snort 3 User Manual

33 / 290

Our full rule would be:
content:"|00 00 00 00|", offset 4, depth 4;
content:"|00 01 87 88|", offset 12, depth 4;
content:"|00 00 00 01 00 00 00 01|", offset 20, depth 8;
byte_test:4,>,200,36;

5.4

DCE Inspectors

The main purpose of these inspector are to perform SMB desegmentation and DCE/RPC defragmentation to avoid rule evasion
using these techniques.
5.4.1

Overview

The following transports are supported for DCE/RPC: SMB, TCP, and UDP. New rule options have been implemented to improve
performance, reduce false positives and reduce the count and complexity of DCE/RPC based rules.
Different from Snort 2, the DCE-RPC preprocessor is split into three inspectors - one for each transport: dce_smb, dce_tcp,
dce_udp. This includes the configuration as well as the inspector modules. The Snort 2 server configuration is now split between
the inspectors. Options that are meaningful to all inspectors, such as policy and defragmentation, are copied into each inspector
configuration. The address/port mapping is handled by the binder. Autodetect functionality is replaced by wizard curses.
5.4.2

Quick Guide

A typical dcerpce configuration looks like this:
binder =
{
{
when =
{
proto = ’tcp’,
ports = ’139 445 1025’,
},
use =
{
type = ’dce_smb’,
},
},
{
when =
{
proto = ’tcp’,
ports = ’135 2103’,
},
use =
{
type = ’dce_tcp’,
},
},
{
when =
{
proto = ’udp’,
ports = ’1030’,

Snort 3 User Manual

34 / 290

},
use =
{
type = ’dce_udp’,
},
}
}
dce_smb = { }
dce_tcp = { }
dce_udp = { }
In this example, it defines smb, tcp and udp inspectors based on port. All the configurations are default.
5.4.3

Target Based

There are enough important differences between Windows and Samba versions that a target based approach has been implemented. Some important differences:
• Named pipe instance tracking
• Accepted SMB commands
• AndX command chaining
• Transaction tracking
• Multiple Bind requests
• DCE/RPC Fragmented requests - Context ID
• DCE/RPC Fragmented requests - Operation number
• DCE/RPC Stub data byte order
Because of those differences, each inspector can be configured to different policy. Here are the list of policies supported:
• WinXP (default)
• Win2000
• WinVista
• Win2003
• Win2008
• Win7
• Samba
• Samba-3.0.37
• Samba-3.0.22
• Samba-3.0.20

Snort 3 User Manual

5.4.4

35 / 290

Reassembling

Both SMB inspector and TCP inspector support reassemble. Reassemble threshold specifies a minimum number of bytes in the
DCE/RPC desegmentation and defragmentation buffers before creating a reassembly packet to send to the detection engine. This
option is useful in inline mode so as to potentially catch an exploit early before full defragmentation is done. A value of 0 s
supplied as an argument to this option will, in effect, disable this option. Default is disabled.
5.4.5

SMB

SMB inspector is one of the most complex inspectors. In addition to supporting rule options and lots of inspector rule events, it
also supports file processing for both SMB version 1, 2, and 3.
Finger Print Policy

In the initial phase of an SMB session, the client needs to authenticate with a SessionSetupAndX. Both the request and response
to this command contain OS and version information that can allow the inspector to dynamically set the policy for a session
which allows for better protection against Windows and Samba specific evasions.
File Inspection

SMB inspector supports file inspection. A typical configuration looks like this:
binder =
{
{
when =
{
proto = ’tcp’,
ports = ’139 445’,
},
use =
{
type = ’dce_smb’,
},
},
}
dce_smb =
{
smb_file_inspection = ’on’,
smb_file_depth = 0,
}
file_id =
{
enable_type = true,
enable_signature = true,
enable_capture = true,
file_rules = magics,
}
First, define a binder to map tcp port 139 and 445 to smb. Then, enable file inspection in smb inspection and set the file depth as
unlimited. Lastly, enable file inspector to inspect file type, calculate file signature, and capture file. The details of file inspector
are explained in file processing section.

Snort 3 User Manual

36 / 290

SMB inspector does inspection of normal SMB file transfers. This includes doing file type and signature through the file processing as well as setting a pointer for the "file_data" rule option. Note that the "file_depth" option only applies to the maximum
amount of file data for which it will set the pointer for the "file_data" rule option. For file type and signature it will use the
value configured for the file API. If "only" is specified, the inspector will only do SMB file inspection, i.e. it will not do any
DCE/RPC tracking or inspection. If "on" is specified with no arguments, the default file depth is 16384 bytes. An argument of
-1 to "file-depth" disables setting the pointer for "file_data", effectively disabling SMB file inspection in rules. An argument of 0
to "file_depth" means unlimited. Default is "off", i.e. no SMB file inspection is done in the inspector.
5.4.6

TCP

dce_tcp inspector supports defragmentation, reassembling, and policy that is similar to SMB.
5.4.7

UDP

dce_udp is a very simple inspector that only supports defragmentation
5.4.8

Rule Options

New rule options are supported by enabling the dcerpc2 inspectors:
• dce_iface
• dce_opnum
• dce_stub_data
New modifiers to existing byte_test and byte_jump rule options:
• byte_test: dce
• byte_jump: dce
dce_iface

For DCE/RPC based rules it has been necessary to set flow-bits based on a client bind to a service to avoid false positives. It is
necessary for a client to bind to a service before being able to make a call to it. When a client sends a bind request to the server,
it can, however, specify one or more service interfaces to bind to. Each interface is represented by a UUID. Each interface UUID
is paired with a unique index (or context id) that future requests can use to reference the service that the client is making a call to.
The server will respond with the interface UUIDs it accepts as valid and will allow the client to make requests to those services.
When a client makes a request, it will specify the context id so the server knows what service the client is making a request
to. Instead of using flow-bits, a rule can simply ask the inspector, using this rule option, whether or not the client has bound
to a specific interface UUID and whether or not this client request is making a request to it. This can eliminate false positives
where more than one service is bound to successfully since the inspector can correlate the bind UUID to the context id used in
the request. A DCE/RPC request can specify whether numbers are represented as big endian or little endian. The representation
of the interface UUID is different depending on the endianness specified in the DCE/RPC previously requiring two rules - one
for big endian and one for little endian. The inspector eliminates the need for two rules by normalizing the UUID. An interface
contains a version. Some versions of an interface may not be vulnerable to a certain exploit. Also, a DCE/RPC request can be
broken up into 1 or more fragments. Flags (and a field in the connectionless header) are set in the DCE/RPC header to indicate
whether the fragment is the first, a middle or the last fragment. Many checks for data in the DCE/RPC request are only relevant if
the DCE/RPC request is a first fragment (or full request), since subsequent fragments will contain data deeper into the DCE/RPC
request. A rule which is looking for data, say 5 bytes into the request (maybe it’s a length field), will be looking at the wrong data
on a fragment other than the first, since the beginning of subsequent fragments are already offset some length from the beginning
of the request. This can be a source of false positives in fragmented DCE/RPC traffic. By default it is reasonable to only evaluate
if the request is a first fragment (or full request). However, if the "any_frag" option is used to specify evaluating on all fragments.
Examples:

Snort 3 User Manual

dce_iface:
dce_iface:
dce_iface:
dce_iface:

37 / 290

4b324fc8-1670-01d3-1278-5a47bf6ee188;
4b324fc8-1670-01d3-1278-5a47bf6ee188,<2;
4b324fc8-1670-01d3-1278-5a47bf6ee188,any_frag;
4b324fc8-1670-01d3-1278-5a47bf6ee188,=1,any_frag;

This option is used to specify an interface UUID. Optional arguments are an interface version and operator to specify that the
version be less than (<), greater than (>), equal to (=) or not equal to (!) the version specified. Also, by default the rule will
only be evaluated for a first fragment (or full request, i.e. not a fragment) since most rules are written to start at the beginning of
a request. The "any_frag" argument says to evaluate for middle and last fragments as well. This option requires tracking client
Bind and Alter Context requests as well as server Bind Ack and Alter Context responses for connection-oriented DCE/RPC in
the inspector. For each Bind and Alter Context request, the client specifies a list of interface UUIDs along with a handle (or
context id) for each interface UUID that will be used during the DCE/RPC session to reference the interface. The server response
indicates which interfaces it will allow the client to make requests to - it either accepts or rejects the client’s wish to bind to a
certain interface. This tracking is required so that when a request is processed, the context id used in the request can be correlated
with the interface UUID it is a handle for.
hexlong and hexshort will be specified and interpreted to be in big endian order (this is usually the default way an interface UUID
will be seen and represented). As an example, the following Messenger interface UUID as taken off the wire from a little endian
Bind request:
|f8 91 7b 5a 00 ff d0 11 a9 b2 00 c0 4f b6 e6 fc|
must be written as:
5a7b91f8-ff00-11d0-a9b2-00c04fb6e6fc
The same UUID taken off the wire from a big endian Bind request:
|5a 7b 91 f8 ff 00 11 d0 a9 b2 00 c0 4f b6 e6 fc|
must be written the same way:
5a7b91f8-ff00-11d0-a9b2-00c04fb6e6fc
This option matches if the specified interface UUID matches the interface UUID (as referred to by the context id) of the DCE/RPC
request and if supplied, the version operation is true. This option will not match if the fragment is not a first fragment (or full
request) unless the "any_frag" option is supplied in which case only the interface UUID and version need match. Note that a
defragmented DCE/RPC request will be considered a full request.
Using this rule option will automatically insert fast pattern contents into the fast pattern matcher. For UDP rules, the interface UUID, in both big and little endian format will be inserted into the fast pattern matcher. For TCP rules, (1) if the rule
option "flow:to_server|from_client" is used, |05 00 00| will be inserted into the fast pattern matcher, (2) if the rule option
"flow:from_server|to_client" is used, |05 00 02| will be inserted into the fast pattern matcher and (3) if the flow isn’t known,
|05 00| will be inserted into the fast pattern matcher. Note that if the rule already has content rule options in it, the best (meaning
longest) pattern will be used. If a content in the rule uses the fast_pattern rule option, it will unequivocally be used over the above
mentioned patterns.
dce_opnum

The opnum represents a specific function call to an interface. After is has been determined that a client has bound to a specific
interface and is making a request to it (see above - dce_iface) usually we want to know what function call it is making to that
service. It is likely that an exploit lies in the particular DCE/RPC function call.
Examples:
dce_opnum:
dce_opnum:
dce_opnum:
dce_opnum:

15;
15-18;
15,18-20;
15,17,20-22;

Snort 3 User Manual

38 / 290

This option is used to specify an opnum (or operation number), opnum range or list containing either or both opnum and/or
opnum-range. The opnum of a DCE/RPC request will be matched against the opnums specified with this option. This option
matches if any one of the opnums specified match the opnum of the DCE/RPC request.
dce_stub_data

Since most DCE/RPC based rules had to do protocol decoding only to get to the DCE/RPC stub data, i.e. the remote procedure
call or function call data, this option will alleviate this need and place the cursor at the beginning of the DCE/RPC stub data. This
reduces the number of rule option checks and the complexity of the rule.
This option takes no arguments.
Example:
dce_stub_data;
This option is used to place the cursor (used to walk the packet payload in rules processing) at the beginning of the DCE/RPC
stub data, regardless of preceding rule options. There are no arguments to this option. This option matches if there is DCE/RPC
stub data.
The cursor is moved to the beginning of the stub data. All ensuing rule options will be considered "sticky" to this buffer. The first
rule option following dce_stub_data should use absolute location modifiers if it is position-dependent. Subsequent rule options
should use a relative modifier if they are meant to be relative to a previous rule option match in the stub data buffer. Any rule
option that does not specify a relative modifier will be evaluated from the start of the stub data buffer. To leave the stub data
buffer and return to the main payload buffer, use the "pkt_data" rule option.
byte_test and byte_jump

A DCE/RPC request can specify whether numbers are represented in big or little endian. These rule options will take as a new
argument "dce" and will work basically the same as the normal byte_test/byte_jump, but since the DCE/RPC inspector will know
the endianness of the request, it will be able to do the correct conversion.
Examples:
byte_test: 4,>,35000,0,relative,dce;
byte_test: 2,!=,2280,-10,relative,dce;
When using the "dce" argument to a byte_test, the following normal byte_test arguments will not be allowed: "big", "little",
"string", "hex", "dec" and "oct".
Examples:
byte_jump:4,-4,relative,align,multiplier 2,post_offset -4,dce;
When using the dce argument to a byte_jump, the following normal byte_jump arguments will not be allowed: "big", "little",
"string", "hex", "dec", "oct" and "from_beginning"

5.5

File Processing

With the volume of malware transferred through network increasing, network file inspection becomes more and more important.
This feature will provide file type identification, file signature creation, and file capture capabilities to help users deal with those
challenges.

Snort 3 User Manual

5.5.1

39 / 290

Overview

There are two parts of file services: file APIs and file policy. File APIs provides all the file inspection functionalities, such as file
type identification, file signature calculation, and file capture. File policy provides users ability to control file services, such as
enable/disable/configure file type identification, file signature, or file capture.
In addition to all capabilities from Snort 2, we support customized file policy along with file event log.
• Supported protocols: HTTP, SMTP, IMAP, POP3, FTP, and SMB.
• Supported file signature calculation: SHA256
5.5.2

Quick Guide

A very simple configuration has been included in lua/snort.lua file. A typical file configuration looks like this:
dofile(’magic.lua’)
my_file_policy =
{
{ when = { file_type_id = 0 }, use = { verdict = ’log’, enable_file_signature ←= true, enable_file_capture = true } }
{ when = { file_type_id = 22 }, use = { verdict = ’log’, ←enable_file_signature = true } },
{ when = { sha256 = " ←F74DC976BC8387E7D4FC0716A069017A0C7ED13F309A523CC41A8739CCB7D4B6" }, use = ←{ verdict = ’block’} },
}
file_id =
{
enable_type = true,
enable_signature = true,
enable_capture = true,
file_rules = magics,
trace_type = true,
trace_signature = true,
trace_stream = true,
file_policy = my_file_policy,
}
file_log =
{
log_pkt_time = true,
log_sys_time = false,
}
There are 3 steps to enable file processing:
• First, you need to include the file magic rules.
• Then, define the file policy and configure the inspector
• At last, enable file_log to get detailed information about file event

Snort 3 User Manual

5.5.3

40 / 290

Pre-packaged File Magic Rules

A set of file magic rules is packaged with Snort. They can be located at "lua/file_magic.lua". To use this feature, it is recommended that these pre-packaged rules are used; doing so requires that you include the file in your Snort configuration as such
(already in snort.lua):
dofile(’magic.lua’)
Example:
{ type = "GIF", id = 62, category = "Graphics", rev = 1,
magic = { { content = "| 47 49 46 38 37 61 |",offset = 0 } } },
{ type = "GIF", id = 63, category = "Graphics", rev = 1,
magic = { { content = "| 47 49 46 38 39 61 |",offset = 0 } } },
The previous two rules define GIF format, because two file magics are different. File magics are specified by content and offset,
which look at content at particular file offset to identify the file type. In this case, two magics look at the beginning of the file.
You can use character if it is printable or hex value in between "|".
5.5.4

File Policy

You can enabled file type, file signature, or file capture by configuring file_id. In addition, you can enable trace to see file stream
data, file type, and file signature information.
Most importantly, you can configure a file policy that can block/alert some file type or an individual file based on SHA. This
allows you build a file blacklist or whitelist.
Example:
file_policy =
{
{ when = { file_type_id = 22 }, use = { verdict = ’log’, ←enable_file_signature = true } },
{ when = { sha256 = " ←F74DC976BC8387E7D4FC0716A069017A0C7ED13F309A523CC41A8739CCB7D4B6" }, use = ←{ verdict = ’block’} },
{ when = { file_type_id = 0 }, use = { verdict = ’log’, enable_file_signature ←= true, enable_file_capture = true } }
}
In this example, it enables this policy:
• For PDF files, they will be logged with signatures.
• For the file matching this SHA, it will be blocked
• For all file types identified, they will be logged with signature, and also captured onto log folder.
5.5.5

File Capture

File can be captured and stored to log folder. We use SHA as file name instead of actual file name to avoid conflicts. You can
capture either all files, some file type, or a particular file based on SHA.
You can enable file capture through this config:
enable_capture = true,
or enable it for some file or file type in your file policy:

Snort 3 User Manual

{

when = { file_type_id = 22 }, use = { verdict = ’log’, enable_file_capture =
true } },

41 / 290

←-

The above rule will enable PDF file capture.
5.5.6

File Events

File inspect preprocessor also works as a dynamic output plugin for file events. It logs basic information about file. The log file
is in the same folder as other log files with name starting with "file.log".
Example:
file_log = { log_pkt_time = true, log_sys_time = false }
All file events will be logged in packet time, system time is not logged.
File event example:
08/14-19:14:19.100891 10.22.75.72:33734 -> 10.22.75.36:80,
[Name: "malware.exe"] [Verdict: Block] [Type: MSEXE]
[SHA: 6F26E721FDB1AAFD29B41BCF90196DEE3A5412550615A856DAE8E3634BCE9F7A]
[Size: 1039328]

5.6

High Availability

High Availability includes the HA flow synchronization and the SideChannel messaging subsystems.
5.6.1

HA

HighAvailability (or HA) is a Snort module that provides state coherency between two partner snort instances. It uses SideChannel for messaging.
There can be multiple types of HA within Snort and Snort plugins. HA implements an extensible architecture to enable plugins
to subscribe to the base flow HA messaging. These plugins can then include their own messages along with the flow cache HA
messages.
HA produces and consumes two type of messages:
• Update - Update flow status. Plugins may add their own data to the messages
• Delete - A flow has been removed from the cache
The HA module is configured with these items:
high_availability =
{
ports = "1",
enable = true,
min_age = 0.0,
min_sync = 0.0
}
The ports item maps to the SideChannel port to use for the HA messaging.
The enabled item controls the overall HA operation.

Snort 3 User Manual

42 / 290

The items min_age and min_sync are used in the stream HA logic. min_age is the number of seconds that a flow must exist
in the flow cache before sending HA messages to the partner. min_sync is the minimum time between HA status updates. HA
messages for a particular flow will not be sent faster than min_sync. Both are expressed as a floating point number of seconds.
HA messages are composed of the base stream information plus any content from additional modules. Modules subscribe HA
in order to add message content. The stream HA content is always present in the messages while the ancillary module content is
only present when requested via a status change request.
5.6.2

Connector

Connectors are a set of modules that are used to exchange message-oriented data among Snort threads and the external world.
A typical use-case is HA (High Availability) message exchange. Connectors serve to decouple the message transport from the
message creation/consumption. Connectors expose a common API for several forms of message transport.
Connectors are a Snort plugin type.
Connector (parent plugin class)

Connectors may either be a simplex channel and perform unidirectional communications. Or may be duplex and perform bidirectional communications. The TcpConnector is duplex while the FileConnector is simplex.
All subtypes of Connector have a direction configuration element and a connector element. The connector string is the key used to
identify the element for sidechannel configuration. The direction element may have a default value, for instance TcpConnector’s
are duplex.
There are currently two implementations of Connectors:
• TcpConnector - Exchange messages over a tcp channel.
• FileConnector - Write messages to files and read messages from files.
TcpConnector

TcpConnector is a subclass of Connector and implements a DUPLEX type Connector, able to send and receive messages over a
tcp session.
TcpConnector adds a few session setup configuration elements:
• setup = call or answer - call is used to have TcpConnector initiate the connection. answer is used to have TcpConnector accept
incoming connections.
• address =  - used for call setup to specify the partner
• base_port = port - used to contruct the actual port number for call and answer modes. Actual port used is (base_port +
instance_id).
An example segment of TcpConnector configuration:
tcp_connector =
{
{
connector = ’tcp_1’,
address = ’127.0.0.1’,
setup = ’call’,
base_port = 11000
},
}

Snort 3 User Manual

43 / 290

FileConnector

FileConnector implements a Connector that can either read from files or write to files. FileConnector’s are simplex and must be
configured to be CONN_TRANSMIT or CONN_RECEIVE.
FileConnector configuration adds two additional element:
• name = string - used as part of the message file name
• format = text or binary - FileConnector supports two file types
The configured name string is used to construct the actual names as in:
• file_connector_NAME_transmit and file_connector_NAME_receive
All messages for one Snort invocation are read and written to one file.
In the case of a receive FileConnector, all messages are read from the file prior to the start of packet processing. This allows the
messages to establish state information for all processed packets.
Connectors are used solely by SideChannel
An example segment of FileConnector configuration:
file_connector =
{
{
connector = ’file_tx_1’,
direction = ’transmit’,
format = ’text’,
name = ’HA’
},
{
connector = ’file_rx_1’,
direction = ’receive’,
format = ’text’,
name = ’HA’
},
}

5.6.3

Side Channel

SideChannel is a Snort module that uses Connectors to implement a messaging infrastructure that is used to communicate between
Snort threads and the outside world.
SideChannel adds functionality onto the Connector as:
• message multiplexing/demultiplexing - An additional protocol layer is added to the messages. This port number is used to
direct message to/from various SideClass instancs.
• application receive processing - handler for received messages on a specific port.
SideChannel’s are always implement a duplex (bidirectional) messaging model and can map to separate transmit and receive
Connectors.
The message handling model leverages the underlying Connector handling. So please refer to the Connector documentation.
SideChannel’s are instantiated by various applications. The SideChannel port numbers are the configuration element used to map
SideChannel’s to applications.

Snort 3 User Manual

44 / 290

The SideChannel configuration mostly serves to map a port number to a Connector or set of connectors. Each port mapping can
have at most one transmit plus one receive connector or one duplex connector. Multiple SideChannel’s may be configured and
instantiated to support multiple applications.
An example SideChannel configuration along with the corresponding Connector configuration:
side_channel =
{
{
ports = ’1’,
connectors =
{
{
connector = ’file_rx_1’,
},
{
connector = ’file_tx_1’,
}
},
},
}
file_connector =
{
{
connector = ’file_tx_1’,
direction = ’transmit’,
format = ’text’,
name = ’HA’
},
{
connector = ’file_rx_1’,
direction = ’receive’,
format = ’text’,
name = ’HA’
},
}

5.7

FTP

Given an FTP command channel buffer, FTP will interpret the data, identifying FTP commands and parameters, as well as FTP
response codes and messages. It will enforce correctness of the parameters, determine when an FTP command connection is
encrypted, and determine when an FTP data channel is opened.
5.7.1

Configuring the inspector to block exploits and attacks

ftp_server configuration

• ftp_cmds
This specifies additional FTP commands outside of those checked by default within the inspector. The inspector may be configured to generate an alert when it sees a command it does not recognize.
Aside from the default commands recognized, it may be necessary to allow the use of the "X" commands, specified in RFC 775.
To do so, use the following ftp_cmds option. Since these are rarely used by FTP client implementations, they are not included in
the defaults.

Snort 3 User Manual

45 / 290

ftp_cmds = [[ XPWD XCWD XCUP XMKD XRMD ]]

• def_max_param_len
This specifies the default maximum parameter length for all commands in bytes. If the parameter for an FTP command exceeds
that length, and the inspector is configured to do so, an alert will be generated. This is used to check for buffer overflow exploits
within FTP servers.
• cmd_validity
This specifies the valid format and length for parameters of a given command.
• cmd_validity[].len
This specifies the maximum parameter length for the specified command in bytes, overriding the default. If the parameter for that
FTP command exceeds that length, and the inspector is configured to do so, an alert will be generated. It can be used to restrict
specific commands to small parameter values. For example the USER command — usernames may be no longer than 16 bytes,
so the appropriate configuration would be:
cmd_validity =
{
{
command = ’USER’,
length = 16,
}
}

• cmd_validity[].format
format is as follows:
int
number
char 
date 

string
host_port
long_host_port
extended_host_port
2428

Param must be an integer
Param must be an integer between 1 and 255
Param must be a single char, and one of 
Param follows format specified where
# = Number, C=Char, []=optional, |=OR, {}=choice,
anything else=literal (i.e., .+- )
Param is string (effectively unrestricted)
Param must a host port specifier, per RFC 959.
Parameter must be a long host port specified, per RFC 1639
Parameter must be an extended host port specified, per RFC

←-

Examples of the cmd_validity option are shown below. These examples are the default checks (per RFC 959 and others) performed by the inspector.
cmd_validity =
{
{
command = ’CWD’,
length = 200,
},
{
command = ’MODE’,

Snort 3 User Manual

46 / 290

format = ’< char SBC >’,
},
{
command = ’STRU’,
format = ’< char FRP >’,
},
{
command = ’ALLO’,
format = ’< int [ char R int ] >’,
},
{
command = ’TYPE’,
format = [[ < { char AE [ char NTC ] | char I | char L [ number ]
} > ]],
},
{
command = ’PORT’,
format = ’< host_port >’,
},
}
A cmd_validity entry in the configuration can be used to override these defaults and/or add a check for other commands. A few
examples follow.
This allows additional modes, including mode Z which allows for zip-style compression:
cmd_validity =
{
{
command = ’MODE’,
format = ’< char ASBCZ >’,
},
}
Allow for a date in the MDTM command:
cmd_validity =
{
{
command = ’MDTM’,
format = ’< [ date nnnnnnnnnnnnnn[.n[n[n]]] ] string >’,
},
}
MDTM is an odd case that is worth discussing. . .
While not part of an established standard, certain FTP servers accept MDTM commands that set the modification time on
a file. The most common among servers that do, accept a format using YYYYMMDDHHmmss[.uuu]. Some others accept
a format using YYYYMMDDHHmmss[+|-]TZ format. The example above is for the first case (time format as specified in
https://tools.ietf.org/html/draft-ietf-ftpext-mlst-16)
To check validity for a server that uses the TZ format, use the following:
cmd_validity =
{
{
command = ’MDTM’,
format = ’< [ date nnnnnnnnnnnnnn[{+|-}n[n]] ] string >’,
},
}

Snort 3 User Manual

47 / 290

• chk_str_fmt
This causes the inspector to check for string format attacks on the specified commands.
• telnet_cmds
Detect and alert when telnet cmds are seen on the FTP command channel.
• ignore_telnet_erase_cmds
This option allows Snort to ignore telnet escape sequences for erase character (TNC EAC) and erase line (TNC EAL) when
normalizing FTP command channel. Some FTP servers do not process those telnet escape sequences.
• ignore_data_chan
When set to true, causes the FTP inspector to force the rest of snort to ignore the FTP data channel connections. NO INSPECTION other than state (inspector AND rules) will be performed on that data channel. It can be turned on to improve performance
— especially with respect to large file transfers from a trusted source — by ignoring traffic. If your rule set includes virus-type
rules, it is recommended that this option not be used.
ftp_client configuration

• max_resp_len
This specifies the maximum length for all response messages in bytes. If the message for an FTP response (everything after the
3 digit code) exceeds that length, and the inspector is configured to do so, an alert will be generated. This is used to check for
buffer overflow exploits within FTP clients.
• telnet_cmds
Detect and alert when telnet cmds are seen on the FTP command channel.
• ignore_telnet_erase_cmds
This option allows Snort to ignore telnet escape sequences for erase character (TNC EAC) and erase line (TNC EAL) when
normalizing FTP command channel. Some FTP clients do not process those telnet escape sequences.
ftp_data

In order to enable file inspection for ftp, the following should be added to the configuration:
ftp_data = {}

5.8

HTTP Inspector

One of the major undertakings for Snort 3 is developing a completely new HTTP inspector.

Snort 3 User Manual

5.8.1

48 / 290

Overview

You can configure it by adding:
http_inspect = {}
to your snort.lua configuration file. Or you can read about it in the source code under src/service_inspectors/http_inspect.
So why a new HTTP inspector?
For starters it is object-oriented. That’s good for us because we maintain this software. But it should also be really nice for
open-source developers. You can make meaningful changes and additions to HTTP processing without having to understand the
whole thing. In fact much of the new HTTP inspector’s knowledge of HTTP is centralized in a series of tables where it can be
easily reviewed and modified. Many significant changes can be made just by updating these tables.
http_inspect is the first inspector written specifically for the new Snort 3 architecture. This provides access to one of the very best
features of Snort 3: purely PDU-based inspection. The classic preprocessor processes HTTP messages, but even while doing so
it is constantly aware of IP packets and how they divide up the TCP data stream. The same HTTP message might be processed
differently depending on how the sender (bad guy) divided it up into IP packets.
http_inspect is free of this burden and can focus exclusively on HTTP. This makes it much simpler, easier to test, and less prone
to false positives. It also greatly reduces the opportunity for adversaries to probe the inspector for weak spots by adjusting packet
boundaries to disguise bad behavior.
Dealing solely with HTTP messages also opens the door for developing major new features. The http_inspect design supports
true stateful processing. Want to ask questions that involve both the client request and the server response? Or different requests
in the same session? These things are possible.
Another new feature on the horizon is HTTP/2 analysis. HTTP/2 derives from Google’s SPDY project and is in the process of
being standardized. Despite the name, it is better to think of HTTP/2 not as a newer version of HTTP/1.1, but rather a separate
protocol layer that runs under HTTP/1.1 and on top of TLS or TCP. It’s a perfect fit for the new Snort 3 architecture because a
new HTTP/2 inspector would naturally output HTTP/1.1 messages but not any underlying packets. Exactly what http_inspect
wants to input.
http_inspect is taking a very different approach to HTTP header fields. The classic preprocessor divides all the HTTP headers
following the start line into cookies and everything else. It normalizes the two pieces using a generic process and puts them in
buffers that one can write rules against. There is some limited support for examining individual headers within the inspector but
it is very specific.
The new concept is that every header should be normalized in an appropriate and specific way and individually made available
for the user to write rules against it. If for example a header is supposed to be a date then normalization means put that date in a
standard format.
5.8.2

Configuration

Configuration can be as simple as adding:
http_inspect = {}
to your snort.lua file. The default configuration provides a thorough inspection and may be all that you need. But there are some
options that provide extra features, tweak how things are done, or conserve resources by doing less.
request_depth and response_depth

These replace the flow depth parameters used by the old HTTP inspector but they work differently.
The default is to inspect the entire HTTP message body. That’s a very sound approach but if your HTTP traffic includes many very
large files such as videos the load on Snort can become burdensome. Setting the request_depth and response_depth parameters
will limit the amount of body data that is sent to the rule engine. For example:
request_depth = 10000,
response_depth = 80000,

Snort 3 User Manual

49 / 290

would examine only the first 10000 bytes of POST, PUT, and other message bodies sent by the client. Responses from the server
would be limited to 80000 bytes.
These limits apply only to the message bodies. HTTP headers are always completely inspected.
If you want to only inspect headers and no body, set the depth to 0. If you want to inspect the entire body set the depth to -1 or
simply omit the depth parameter entirely because that is the default.
These limits have no effect on how much data is forwarded to file processing.
gzip

http_inspect by default decompresses deflate and gzip message bodies before inspecting them. This feature can be turned off by
unzip = false. Turning off decompression provides a substantial performance improvement but at a very high price. It is unlikely
that any meaningful inspection of message bodies will be possible. Effectively HTTP processing would be limited to the headers.
normalize_utf

http_inspect will decode utf-8, utf-7, utf-16le, utf-16be, utf-32le, and utf-32be in response message bodies based on the ContentType header. This feature is on by default: normalize_utf = false will deactivate it.
decompress_pdf

decompress_pdf = true will enable decompression of compressed portions of PDF files encountered in a response body. http_inspect
will examine the response body for PDF files that are then parsed to locate PDF streams with a single /FlateDecode filter. The
compressed content is decompressed and made available through the file data rule option.
decompress_swf

decompress_swf = true will enable decompression of compressed SWF (Adobe Flash content) files encountered in a response
body. The available decompression modes are ’deflate’ and ’lzma’. http_inspect will search for the file signatures CWS for
Deflate/ZLIB and ZWS for LZMA. The compressed content is decompressed and made available through the file data rule
option. The compressed SWF file signature is converted to FWS to indicate an uncompressed file.
normalize_javascript

normalize_javascript = true will enable normalization of JavaScript within the HTTP response body. http_inspect looks for
JavaScript by searching for the