Release 4.1.0-Dev OISF
Total Page:16
File Type:pdf, Size:1020Kb
Suricata User Guide Release 4.1.0-dev OISF Sep 24, 2019 Contents 1 What is Suricata 1 1.1 About the Open Information Security Foundation............................1 2 Installation 3 2.1 Source..................................................3 2.2 Binary packages.............................................5 2.3 Advanced Installation..........................................5 3 Command Line Options 7 3.1 Unit Tests................................................. 10 4 Suricata Rules 11 4.1 Rules Format............................................... 11 4.2 Meta Keywords.............................................. 16 4.3 IP Keywords............................................... 19 4.4 TCP keywords.............................................. 23 4.5 ICMP keywords............................................. 25 4.6 Payload Keywords............................................ 29 4.7 Transformations............................................. 44 4.8 Prefiltering Keywords.......................................... 45 4.9 Flow Keywords.............................................. 49 4.10 Bypass Keyword............................................. 54 4.11 HTTP Keywords............................................. 54 4.12 File Keywords.............................................. 74 4.13 DNS Keywords.............................................. 77 4.14 SSL/TLS Keywords........................................... 78 4.15 SSH Keywords.............................................. 81 4.16 JA3 Keywords.............................................. 82 4.17 Modbus Keyword............................................ 83 4.18 DNP3 Keywords............................................. 85 4.19 ENIP/CIP Keywords........................................... 88 4.20 FTP/FTP-DATA Keywords....................................... 89 4.21 Kerberos Keywords........................................... 89 4.22 Generic App Layer Keywords...................................... 92 4.23 Xbits Keyword.............................................. 93 4.24 Thresholding Keywords......................................... 95 4.25 IP Reputation Keyword......................................... 97 i 4.26 Lua Scripting............................................... 97 4.27 Differences From Snort......................................... 99 5 Rule Management 109 5.1 Rule Management with Suricata-Update................................. 109 5.2 Rule Management with Oinkmaster................................... 111 5.3 Adding Your Own Rules......................................... 114 5.4 Rule Reloads............................................... 115 6 Making sense out of Alerts 117 7 Performance 119 7.1 Runmodes................................................ 119 7.2 Packet Capture.............................................. 123 7.3 Tuning Considerations.......................................... 125 7.4 Hyperscan................................................ 126 7.5 High Performance Configuration.................................... 128 7.6 Statistics................................................. 128 7.7 Ignoring Traffic.............................................. 131 7.8 Packet Profiling.............................................. 132 7.9 Rule Profiling............................................... 133 7.10 Tcmalloc................................................. 134 8 Configuration 135 8.1 Suricata.yaml............................................... 135 8.2 Global-Thresholds............................................ 180 8.3 Snort.conf to Suricata.yaml....................................... 184 8.4 Multi Tenancy.............................................. 188 8.5 Dropping Privileges After Startup.................................... 191 9 Reputation 193 9.1 IP Reputation............................................... 193 10 Init Scripts 197 11 Setting up IPS/inline for Linux 199 11.1 Iptables configuration.......................................... 199 12 Setting up IPS/inline for Windows 203 13 Output 205 13.1 EVE................................................... 205 13.2 Lua Output................................................ 227 13.3 Syslog Alerting Compatibility...................................... 229 13.4 Custom http logging........................................... 230 13.5 Custom tls logging............................................ 231 13.6 Log Rotation............................................... 232 14 Lua support 235 14.1 Lua usage in Suricata........................................... 235 14.2 Lua functions............................................... 235 15 File Extraction 249 15.1 Architecture............................................... 249 15.2 Settings.................................................. 249 15.3 Output.................................................. 250 ii 15.4 Rules................................................... 251 15.5 MD5................................................... 252 16 Public Data Sets 255 17 Using Capture Hardware 257 17.1 Endace DAG............................................... 257 17.2 Napatech Suricata Installation Guide.................................. 258 17.3 Myricom................................................. 262 17.4 eBPF and XDP.............................................. 263 18 Interacting via Unix Socket 271 18.1 Introduction............................................... 271 18.2 Commands in standard running mode.................................. 272 18.3 Commands on the cmd prompt...................................... 273 18.4 Pcap processing mode.......................................... 273 18.5 Build your own client.......................................... 274 19 Man Pages 277 19.1 Suricata.................................................. 277 20 Acknowledgements 283 21 Licenses 285 21.1 GNU General Public License...................................... 285 21.2 Creative Commons Attribution-NonCommercial 4.0 International Public License........... 289 21.3 Suricata Source Code.......................................... 294 21.4 Suricata Documentation......................................... 294 Index 295 iii iv CHAPTER 1 What is Suricata Suricata is a high performance Network IDS, IPS and Network Security Monitoring engine. It is open source and owned by a community-run non-profit foundation, the Open Information Security Foundation (OISF). Suricata is developed by the OISF. 1.1 About the Open Information Security Foundation The Open Information Security Foundation is a non-profit foundation organized to build community and to support open-source security technologies like Suricata, the world-class IDS/IPS engine. 1.1.1 License The Suricata source code is licensed under version 2 of the GNU General Public License. This documentation is licensed under the Creative Commons Attribution-NonCommercial 4.0 International Public License. 1 Suricata User Guide, Release 4.1.0-dev 2 Chapter 1. What is Suricata CHAPTER 2 Installation Before Suricata can be used it has to be installed. Suricata can be installed on various distributions using binary packages: Binary packages. For people familiar with compiling their own software, the Source method is recommended. Advanced users can check the advanced guides, see Advanced Installation. 2.1 Source Installing from the source distribution files gives the most control over the Suricata installation. Basic steps: tar xzvf suricata-4.1.3.tar.gz cd suricata-4.1.3 ./configure make make install This will install Suricata into /usr/local/bin/, use the default configuration in /usr/local/etc/ suricata/ and will output to /usr/local/var/log/suricata 2.1.1 Common configure options --disable-gccmarch-native Do not optimize the binary for the hardware it is built on. Add this flag if the binary is meant to be portable or if Suricata is to be used in a VM. --prefix=/usr/ Installs the Suricata binary into /usr/bin/. Default /usr/local/ --sysconfdir=/etc Installs the Suricata configuration files into /etc/suricata/. Default /usr/local/etc/ 3 Suricata User Guide, Release 4.1.0-dev --localstatedir=/var Setups Suricata for logging into /var/log/suricata/. Default /usr/local/var/log/suricata --enable-lua Enables Lua support for detection and output. --enable-geopip Enables GeoIP support for detection. --disable-rust Disables Rust support. Rust support is enabled by default if rustc/cargo are available. 2.1.2 Dependencies For Suricata’s compilation you’ll need the following libraries and their development headers installed: libpcap, libpcre, libmagic, zlib, libyaml The following tools are required: make gcc (or clang) pkg-config For full features, also add: libjansson, libnss, libgeoip, liblua5.1, libhiredis, libevent Rust support: rustc, cargo Not every distro provides Rust packages yet. Rust can also be installed directly from the Rust project itself: https://www.rust-lang.org/en-US/install.html Ubuntu/Debian Minimal: apt-get install libpcre3 libpcre3-dbg libpcre3-dev build-essential libpcap-dev \ libyaml-0-2 libyaml-dev pkg-config zlib1g zlib1g-dev \ make libmagic-dev Recommended: apt-get install libpcre3 libpcre3-dbg libpcre3-dev build-essential libpcap-dev \ libnet1-dev libyaml-0-2 libyaml-dev pkg-config zlib1g zlib1g-dev \ libcap-ng-dev libcap-ng0 make libmagic-dev libjansson-dev \ libnss3-dev libgeoip-dev liblua5.1-dev libhiredis-dev libevent-dev \ python-yaml rustc cargo Extra for iptables/nftables IPS integration: apt-get install libnetfilter-queue-dev libnetfilter-queue1 \ libnetfilter-log-dev libnetfilter-log1 \ libnfnetlink-dev libnfnetlink0 For Rust