eBPF is used for three things in Suricata:
- eBPF filter: any BPF like filter can be developed. An example of filter accepting only packet for some VLANs is provided. A bypass implementation is also provided.
-- eBPF load balancing: provide programmable load balancing. A simple ippair load balancing is provided.
-- XDP programs: suricata can load XDP programs. A bypass program is provided.
+- eBPF load balancing: provide programmable load balancing. Simple ippair load balancing is provided.
+- XDP programs: Suricata can load XDP programs. A bypass program is provided.
Bypass can be implemented in eBPF and XDP. The advantage of XDP is that the packets are dropped at the earliest stage
possible. So performance is better. But bypassed packets don't reach the network so you can't use this on regular
Requirements
------------
-You will need a kernel that supports XDP and, for real performance improvement, a network
+You will need a kernel that supports XDP and, for the most performance improvement, a network
card that support XDP in the driver.
Suricata XDP code has been tested with 4.13.10 but 4.15 or later is necessary to use all
Disable irqbalance
~~~~~~~~~~~~~~~~~~
-Irqbalance may cause issues in most setups described here, so it is recommended
+``irqbalance`` may cause issues in most setups described here, so it is recommended
to deactivate it ::
systemctl stop irqbalance
Clang and dependencies
~~~~~~~~~~~~~~~~~~~~~~
-Make sure you have clang (>=3.9) installed on the system ::
+Make sure you have ``clang`` (>=3.9) installed on the system ::
sudo apt install clang
sudo ldconfig
In some cases your system will not find the libbpf library that is installed under
-`/usr/lib64` so you may need to modify your ldconfig configuration.
+``/usr/lib64`` so you may need to modify your ldconfig configuration.
Compile and install Suricata
----------------------------
To get Suricata source, you can use the usual ::
- git clone https://github.com/OISF/suricata.git
+ git clone https://github.com/OISF/suricata.git
cd suricata && git clone https://github.com/OISF/libhtp.git -b 0.5.x
./autogen.sh
-Then you need to add the ebpf flags to configure and specify the Clang
+Then you need to add the eBPF flags to configure and specify the Clang
compiler for building all C sources, including the eBPF programs ::
CC=clang ./configure --prefix=/usr/ --sysconfdir=/etc/ --localstatedir=/var/ \
--enable-ebpf --enable-ebpf-build
make clean && make
- sudo make install-full
+ sudo make install-full
sudo ldconfig
sudo mkdir /usr/libexec/suricata/ebpf/
Setup eBPF filter
-----------------
-The file `ebpf/vlan_filter.c` contains a list of vlan id in a switch
+The file `ebpf/vlan_filter.c` contains a list of VLAN id in a switch
that you need to edit to get something adapted to your network. Another
filter dropping packets from or to a set of IPv4 address is also available in
`ebpf/filter.c`. See :ref:`ebpf-pinned-maps` for more information.
Suricata can load as eBPF filter any eBPF code exposing a ``filter`` section.
-Once modifications and build via `make` are done, you can copy the resulting
+Once modifications and build via ``make`` are complete, you can copy the resulting
eBPF filter as needed ::
cp ebpf/vlan_filter.bpf /usr/libexec/suricata/ebpf/
use-mmap: yes
ring-size: 200000
-You can then run suricata normally ::
+You can then run Suricata normally ::
/usr/bin/suricata --pidfile /var/run/suricata.pid --af-packet=eth3 -vvv
-----------------
You can also use eBPF bypass. To do that load the `bypass_filter.bpf` file and
-update af-packet configuration in ``suricata.yaml`` to set bypass to yes ::
+update af-packet configuration in ``suricata.yaml`` to set bypass to `yes` ::
- interface: eth3
threads: 16
use-mmap: yes
ring-size: 200000
-Constraints on eBPF code to have a bypass compliant code are stronger than for regular filter. The
+Constraints on eBPF code to have a bypass compliant code are stronger than for regular filters. The
filter must expose `flow_table_v4` and `flow_table_v6` per CPU array maps with similar definitions
as the one available in `bypass_filter.c`. These two maps will be accessed and
-maintained by Suricata to handle the lists of flow to bypass.
+maintained by Suricata to handle the lists of flows to bypass.
-If you are not using vlan tracking (``vlan.use-for-tracking`` set to false in suricata.yaml) then you also have to set
-the VLAN_TRACKING define to 0 in ``bypass_filter.c``.
+If you are not using VLAN tracking (``vlan.use-for-tracking`` set to `false` in suricata.yaml) then you also have to set
+the ``VLAN_TRACKING`` define to `0` in ``bypass_filter.c``.
Setup eBPF load balancing
-------------------------
Setup XDP bypass
----------------
-XDP bypass will allow Suricata to tell the kernel that packets for some
-flows have to be dropped via the XDP mechanism. This is a really early
-drop that occurs before the datagram is reaching the Linux kernel
+XDP bypass allows Suricata to tell the kernel that packets for some
+flows have to be dropped via the XDP mechanism. This is an early
+drop that occurs before the datagram reaches the Linux kernel
network stack.
Linux 4.15 or newer are recommended to use that feature. You can use it
-on older kernel if you set ``BUILD_CPUMAP`` to 0 in ``ebpf/xdp_filter.c``.
+on older kernel if you set ``BUILD_CPUMAP`` to `0` in ``ebpf/xdp_filter.c``.
-Copy the resulting xdp filter as needed::
+Copy the resulting XDP filter as needed::
cp ebpf/xdp_filter.bpf /usr/libexec/suricata/ebpf/
the encrypted TLS 1.2 packets in the eBPF code. Be aware that this will mean that Suricata will
be blind on packets on port 443 with the correct pattern.
-If you are not using vlan tracking (``vlan.use-for-tracking`` set to false in suricata.yaml) then you also have to set
+If you are not using VLAN tracking (``vlan.use-for-tracking`` set to false in suricata.yaml) then you also have to set
the VLAN_TRACKING define to 0 in ``xdp_filter.c``.
Intel NIC setup
Balance as much as you can
~~~~~~~~~~~~~~~~~~~~~~~~~~
-Try to use the network's card balancing as much as possible ::
+Try to use the network card's flow balancing as much as possible ::
for proto in tcp4 udp4 ah4 esp4 sctp4 tcp6 udp6 ah6 esp6 sctp6; do
/sbin/ethtool -N eth3 rx-flow-hash $proto sd
Pinned maps stay attached to the system if the creating process disappears and
they can also be accessed by external tools. In Suricata bypass case, this can be
-used to keep active bypassed flow tables, so Suricata is not hit by previously bypassed flows when
+used to keep bypassed flow tables active, so Suricata is not hit by previously bypassed flows when
restarting. In the socket filter case, this can be used to maintain a map from tools outside
of Suricata.
Then build the bpf file with `make` and install it in the expected place.
-On Suricata configuration side, this is rather simple as you need to activate
+The Suricata configuration is rather simple as you need to activate
hardware mode and the `use-percpu-hash` option in the `af-packet` configuration
of the interface ::
Configure with DAG support:
-
::
-
./configure --enable-dag --prefix=/usr --sysconfdir=/etc --localstatedir=/var
make
sudo make install
::
-
Suricata Configuration:
AF_PACKET support: no
PF_RING support: no
DAG enabled: yes
Napatech enabled: no
-Start with:
+Start with:
::
-
suricata -c suricata.yaml --dag 0:0
-Started up!
+Started up!
::
From: https://blog.inliniac.net/2012/07/10/suricata-on-myricom-capture-cards/
-In this guide I'll describe using the Myricom libpcap support. I'm going to assume you installed the card properly, installed the Sniffer driver and made sure that all works. Make sure that in your dmesg you see that the card is in sniffer mode:
+In this guide I'll describe using the Myricom libpcap support. I'm going to assume you installed the card properly, installed the Sniffer driver and made sure that all works. Make sure ``dmesg`` shows that the card is in sniffer mode:
::
[ 2102.860241] myri_snf INFO: eth4: Link0 is UP
[ 2101.341965] myri_snf INFO: eth5: Link0 is UP
-I have installed the Myricom runtime and libraries in /opt/snf
+I have installed the Myricom runtime and libraries in ``/opt/snf``
Compile Suricata against Myricom's libpcap:
-
::
buffer-size: 512kb
checksum-checks: no
-The 8 threads setting makes Suricata create 8 reader threads for eth5. The Myricom driver makes sure each of those is attached to its own ringbuffer.
+The 8 threads setting causes Suricata to create 8 reader threads for eth5. The Myricom driver makes sure each of those is attached to its own ringbuffer.
Then start Suricata as follows:
SNF_NUM_RINGS=8 SNF_FLAGS=0x1 suricata -c suricata.yaml -i eth5 --runmode=workers
-If you want 16 ringbuffers, update the "threads" variable in your yaml to 16 and start Suricata:
+If you want 16 ringbuffers, update the "threads" variable in the Suricata configuration file to `16` and start Suricata:
::
SNF_NUM_RINGS=16 SNF_FLAGS=0x1 suricata -c suricata.yaml -i eth5 --runmode=workers
-Note that the pcap.buffer-size yaml setting shown above is currently ignored when using Myricom cards. The value is passed through to the pcap_set_buffer_size libpcap API within the Suricata source code. From Myricom support:
+Note that the ``pcap.buffer-size`` configuration setting shown above is currently ignored when using Myricom cards. The value is passed through to the ``pcap_set_buffer_size`` libpcap API within the Suricata source code. From Myricom support:
::
-
"The libpcap interface to Sniffer10G ignores the pcap_set_buffer_size() value. The call to snf_open() uses zero as the dataring_size which informs the Sniffer library to use a default value or the value from the SNF_DATARING_SIZE environment variable."
The following pull request opened by Myricom in the libpcap project indicates that a future SNF software release could provide support for setting the SNF_DATARING_SIZE via the pcap.buffer-size yaml setting:
* http://www.40gbe.net/index_files/be59da7f2ab5bf0a299ab99ef441bb2e-28.html
-* http://o-www.emulex.com/blogs/implementers/2012/07/23/black-hat-usa-2012-emulex-faststack-sniffer10g-product-demo-emulex-booth/
+* https://www.broadcom.com/support/knowledgebase/1211161394432/how-to-use-emulex-oneconnect-oce12000-d-adapters-with-faststack-
$ apt-get install linux-headers-$(uname .r) gcc make
$ ./package_install_3gd.sh
-To complete installation for all distros ntservice::
+To complete installation for all distros ``ntservice``::
$ /opt/napatech3/bin/ntstart.sh -m
ports: [all]
hashmode: hash5tuplesorted
-Now modify ntservice.ini. You also need make sure that you have allocated enough
-host buffers in ntservice.ini for the streams. It's a good idea to also set the
-TimeSyncReferencePriority. To do this make the following changes to ntservice.ini:
+Now modify ``ntservice.ini``. You also need make sure that you have allocated enough
+host buffers in ``ntservice.ini`` for the streams. It's a good idea to also set the
+``TimeSyncReferencePriority``. To do this make the following changes to ntservice.ini:
HostBuffersRx = [4,16,-1] # [number of host buffers, Size(MB), NUMA node]
TimeSyncReferencePriority = OSTime # Timestamp clock synchronized to the OS
-Stop and restart ntservice after making changes to ntservice::
+Stop and restart ``ntservice`` after making changes to ntservice::
$ /opt/napatech3/bin/ntstop.sh
$ /opt/napatech3/bin/ntstart.sh
------------------------------------------------------
This option will create a single worker-thread and stream for each CPU defined in the
-worker-cpu-set. To use this option make the following changes to suricata.yaml:
+``worker-cpu-set``. To use this option make the following changes to suricata.yaml:
1. Turn on cpu-affinity
2. Specify the worker-cpu-set
TimeSyncReferencePriority = OSTime # Timestamp clock synchronized to the OS
HostBuffersRx = [16,16,0],[16,16,1] # [number of host buffers, Size(MB), NUMA node]
-Stop and restart ntservice after making changes to ntservice::
+Stop and restart ``ntservice`` after making changes to ntservice::
$ /opt/napatech3/bin/ntstop.sh -m
$ /opt/napatech3/bin/ntstart.sh -m
Delete=All # Delete any existing filters
Assign[streamid=(0..3)]= all # Assign all physical ports to stream ID 0
-Next execute those command using the ntpl tool::
+Next execute those command using the ``ntpl`` tool::
$ /opt/napatech3/bin/ntpl -f <my_ntpl_file>
Bypassing Flows
---------------
-On flow-aware Napatech products traffic from individual flows can be automatically
+On flow-aware Napatech products, traffic from individual flows can be automatically
dropped or, in the case of inline configurations, forwarded by the hardware after
an inspection of the initial packet(s) of the flow by Suricata. This will save
CPU cycles since Suricata does not process packets for a flow that has already been
of the packets. If this is enabled without another application sharing the stream it will result in sub-optimal packet
buffering.*
-Make sure that there are enough host-buffers declared in ntservice.ini to
+Make sure that there are enough host-buffers declared in ``ntservice.ini`` to
accommodate the number of cores/streams being used.
Support
When NETMAP is installed, add ``--enable-netmap`` to the configure line.
If the includes are not added to a standard location, the location can
-be specified on the Suricata configure commandline.
+be specified when configuring Suricata.
Example::
suricata --netmap=<interface>
suricata --netmap=igb0
-In the above example Suricata will start reading from igb0. The number of
-threads created depends on the number of RSS queues available on the NIC.
+In the above example Suricata will start reading from the `igb0` network interface.
+The number of threads created depends on the number of RSS queues available on the NIC.
::
suricata --netmap
-In the above example Suricata will take the ``netmap`` block from the yaml
-and open each of the interfaces listed.
+In the above example Suricata will take the ``netmap`` block from the Suricata
+configuration and open each of the interfaces listed.
::
- interface: igb1
threads: 4
-For the above configuration, both igb0 and igb1 would be opened. With 2
-threads for igb0 and 4 capture threads for igb1.
+For the above configuration, both ``igb0`` and ``igb1`` would be opened. With 2
+threads for ``igb0`` and 4 capture threads for ``igb1``.
.. warning:: This multi threaded setup only works correctly if the NIC
has symmetric RSS hashing. If this is not the case, consider
Unit Tests
~~~~~~~~~~
-Builtin unittests are only available if Suricata has been built with
---enable-unittests.
+The builtin unittests are only available when Suricata has been configured and built with
+``--enable-unittests``.
-Running unittests does not take a configuration file. Use -l to supply
-an output directory.
+Running unittests does not require a configuration file. Use -l to supply
+an output directory.::
+
+ sudo suricata -u
.. include:: partials/options-unittests.rst
Dropping Privileges After Startup
=================================
-Currently, libcap-ng is needed for dropping privileges on Suricata
+Currently, ``libcap-ng`` is needed for dropping privileges on Suricata
after startup. For libcap, see status of feature request number #276
-- Libcap support for dropping privileges.
suricata -D -i eth0 --user=suri --group=suri
You will also want to make sure your user/group permissions are set so
-suricata can still write to its log files which are usually located in
+Suricata can still write to its log files which are usually located in
/var/log/suricata.
::
Example
^^^^^^^
-Lets say we want to limit incoming connections to our SSH server. The rule
+Let's say we want to limit incoming connections to our SSH server. The rule
``888`` below simply alerts on SYN packets to the SSH port of our SSH server.
If an IP-address triggers this more than 10 or more with a minute, the
drop ``rate_filter`` is set with a timeout of 5 minutes.
Threading
---------
-Suricata is multi-threaded. Suricata uses multiple CPU' s/CPU cores so
+Suricata is multi-threaded. Suricata uses multiple CPUs/CPU cores so
it can process a lot of network packets simultaneously. (In a
single-core engine, the packets will be processed one at a time.)
write-meta: yes # write a .meta file if set to yes
include-pid: yes # include the pid in filenames if set to yes.
-the following changes will need to be made to convert to a V2 style configuration:
+The following changes will need to be made to convert to a v2 style configuration:
-* A ``version`` field must be set to 2.
+* The ``version`` field must be set to 2.
* The ``log-dir`` field should be renamed to ``dir``. It is recommended to use a new directory instead of an existing v1 directory.
* Remove the ``waldo`` option. It is no longer used.
-* Remove the ``write-meta`` option. Optionally set ``write-fileinfo`` to enable writing of a metadata file along side the extracted file. Not that this option is disabled by default as a ``fileinfo`` event can be written to the Eve log file.
+* Remove the ``write-meta`` option.
+* Optionally set ``write-fileinfo`` to enable writing of a metadata file along side the extracted file. Not that this option is disabled by default as a ``fileinfo`` event can be written to the Eve log file.
* Remove the ``include-pid`` option. There is no equivalent to this option in file-store v2.
Example converted configuration::
This means that settings in the stream engine, reassembly engine and the application layer parsers all affect the workings of the file extraction.
-What files are actually extracted and stored to disk is controlled by the rule language.
+The rule language controls which files are extracted and stored on disk.
Supported protocols are:
*file-store.stream-depth* controls how far into a stream reassembly is done. Beyond this value no reassembly will be done. This means that after this value the HTTP session will no longer be tracked. By default a setting of 1 Megabyte is used. 0 sets it to unlimited. If set to no, it is disabled and stream.reassembly.depth is considered. Non-zero values must be greater than ``stream.stream-depth`` to be used.
-*libhtp.default-config.request-body-limit* / *libhtp.server-config.<config>.request-body-limit* controls how much of the HTTP request body is tracked for inspection by the http_client_body keyword, but also used to limit file inspection. A value of 0 means unlimited.
+*libhtp.default-config.request-body-limit* / *libhtp.server-config.<config>.request-body-limit* controls how much of the HTTP request body is tracked for inspection by the `http_client_body` keyword, but also used to limit file inspection. A value of 0 means unlimited.
*libhtp.default-config.response-body-limit* / *libhtp.server-config.<config>.response-body-limit* is like the request body limit, only it applies to the HTTP response body.
File-Store and Eve Fileinfo
---------------------------
-There are two output modules for logging information about files
-extracted. The first is ``eve.files`` which is an ``eve`` sub-logger
+There are two output modules for logging information about extracted files.
+The first is ``eve.files`` which is an ``eve`` sub-logger
that logs ``fileinfo`` records. These ``fileinfo`` records provide
metadata about the file, but not the actual file contents.
Without rules in place no extraction will happen. The simplest rule would be:
-
::
-
alert http any any -> any any (msg:"FILE store all"; filestore; sid:1; rev:1;)
This will simply store all files to disk.
-Want to store all files with a pdf extension?
+Want to store all files with a pdf extension?
::
-
alert http any any -> any any (msg:"FILE PDF file claimed"; fileext:"pdf"; filestore; sid:2; rev:1;)
-Or rather all actual pdf files?
+Or rather all actual pdf files?
::
-
alert http any any -> any any (msg:"FILE pdf detected"; filemagic:"PDF document"; filestore; sid:3; rev:1;)
-Or rather only store files from black list checksum md5 ?
+Or rather only store files from black list checksum md5 ?
::
-
alert http any any -> any any (msg:"Black list checksum match and extract MD5"; filemd5:fileextraction-chksum.list; filestore; sid:4; rev:1;)
-Or only store files from black list checksum sha1 ?
+Or only store files from black list checksum sha1 ?
::
-
alert http any any -> any any (msg:"Black list checksum match and extract SHA1"; filesha1:fileextraction-chksum.list; filestore; sid:5; rev:1;)
-Or finally store files from black list checksum sha256 ?
+Or finally store files from black list checksum sha256 ?
::
-
-
alert http any any -> any any (msg:"Black list checksum match and extract SHA256"; filesha256:fileextraction-chksum.list; filestore; sid:6; rev:1;)
-Bundled with the Suricata download is a file with more example rules. In the archive, go to the rules/ directory and check the files.rules file.
+Bundled with the Suricata download, is a file with more example rules. In the archive, go to the `rules` directory and check the ``files.rules`` file.
MD5
Configuration
~~~~~~~~~~~~~
-In the suricata yaml:
+In the Suricata config file:
::
-
- file-store:
enabled: yes # set to yes to enable
- log-dir: files # directory to store the files
- force-magic: yes # force logging magic on all stored files
+ dir: filestore # directory to store the files
force-hash: [md5] # force logging of md5 checksums
- #waldo: file.waldo # waldo file to store the file_id across runs
+
For JSON output:
Other settings affecting :doc:`file-extraction`
-
::
-
stream:
memcap: 64mb
checksum-validation: yes # reject wrong csums
::
-
libhtp:
default-config:
personality: IDS
::
-
alert http any any -> any any (msg:"FILE store all"; filestore; sid:1; rev:1;)
This rule above will save all the file data for files that are opened/downloaded through HTTP
-Start Suricata (-S option loads ONLY the specified rule file, with disregard if any other rules that are enabled in suricata.yaml):
-
+Start Suricata (``-S`` option *ONLY loads* the specified rule file and disregards any other rules that are enabled in suricata.yaml):
::
-
suricata -c /etc/suricata/suricata.yaml -S file.rules -i eth0
Meta data:
-
::
-
TIME: 05/01/2012-11:09:52.425751
SRC IP: 2.23.144.170
DST IP: 192.168.1.91
::
-
{ "id": 1, "timestamp": "05\/01\/2012-11:10:27.693583", "ipver": 4, "srcip": "2.23.144.170", "dstip": "192.168.1.91", "protocol": 6, "sp": 80, "dp": 51598, "http_uri": "\/en\/US\/prod\/collateral\/routers\/ps5855\/prod_brochure0900aecd8019dc1f.pdf", "http_host": "www.cisco.com", "http_referer": "http:\/\/www.google.com\/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&ved=0CDAQFjAA&url=http%3A%2F%2Fwww.cisco.com%2Fen%2FUS%2Fprod%2Fcollateral%2Frouters%2Fps5855%2Fprod_brochure0900aecd8019dc1f.pdf&ei=OqyfT9eoJubi4QTyiamhAw&usg=AFQjCNGdjDBpBDfQv2r3VogSH41V6T5x9Q", "filename": "\/en\/US\/prod\/collateral\/routers\/ps5855\/prod_brochure0900aecd8019dc1f.pdf", "magic": "PDF document, version 1.6", "state": "CLOSED", "md5": "59eba188e52467adc11bf2442ee5bf57", "stored": true, "size": 9485123 }
{ "id": 12, "timestamp": "05\/01\/2012-11:12:57.421420", "ipver": 4, "srcip": "2.23.144.170", "dstip": "192.168.1.91", "protocol": 6, "sp": 80, "dp": 51598, "http_uri": "\/en\/US\/prod\/collateral\/routers\/ps5855\/prod_brochure0900aecd8019dc1f.pdf", "http_host": "www.cisco.com", "http_referer": "http:\/\/www.google.com\/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&ved=0CDAQFjAA&url=http%3A%2F%2Fwww.cisco.com%2Fen%2FUS%2Fprod%2Fcollateral%2Frouters%2Fps5855%2Fprod_brochure0900aecd8019dc1f.pdf&ei=OqyfT9eoJubi4QTyiamhAw&usg=AFQjCNGdjDBpBDfQv2r3VogSH41V6T5x9Q", "filename": "\/en\/US\/prod\/collateral\/routers\/ps5855\/prod_brochure0900aecd8019dc1f.pdf", "magic": "PDF document, version 1.6", "state": "CLOSED", "md5": "59eba188e52467adc11bf2442ee5bf57", "stored": true, "size": 9485123 }
If you would like to log MD5s for everything and anything that passes through the traffic that you are inspecting with Suricata, but not log the files themselves, all you have to do is disable file-store and enable only the JSON output with forced MD5s - in suricata.yaml like so:
-
::
-
- file-store:
+ version: 2
enabled: no # set to yes to enable
log-dir: files # directory to store the files
- force-magic: yes # force logging magic on all stored files
- force-hash: [md5] # force logging of md5 checksums
- #waldo: file.waldo # waldo file to store the file_id across runs
-
- - file-log:
- enabled: yes
- filename: files-json.log
- append: no
- #filetype: regular # 'regular', 'unix_stream' or 'unix_dgram'
- force-magic: yes # force logging magic on all logged files
+ force-filestore: no
force-hash: [md5] # force logging of md5 checksums
Public SHA1 MD5 data sets
=========================
-National Software Reference Library - http://www.nsrl.nist.gov/Downloads.htm
+National Software Reference Library - http://www.nsrl.nist.gov/Downloads.html
Init Scripts
============
-For Ubuntu with Upstart, the following can be used in /etc/init/suricata.conf:
+For Ubuntu with Upstart, the following can be used in ``/etc/init/suricata.conf``:
::
# suricata
- description "Intruder Detection System Daemon"
+ description "Intrusion Detection System Daemon"
start on runlevel [2345]
stop on runlevel [!2345]
expect fork
Before Suricata can be used it has to be installed. Suricata can be installed
on various distributions using binary packages: :ref:`install-binary-packages`.
-For people familiar with compiling their own software, the Source method is
+For people familiar with compiling their own software, the `Source method` is
recommended.
Advanced users can check the advanced guides, see :ref:`install-advanced`.
Basic steps::
- tar xzvf suricata-5.0.0.tar.gz
- cd suricata-5.0.0
+ tar xzvf suricata-6.0.0.tar.gz
+ cd suricata-6.0.0
./configure
make
make install
Dependencies
^^^^^^^^^^^^
-For Suricata's compilation you'll need the following libraries and their development headers installed:
+For Suricata's compilation you'll need the following libraries and their development headers installed::
- libpcap, libpcre, libmagic, zlib, libyaml
+ libjansson, libpcap, libpcre, libmagic, zlib, libyaml
-The following tools are required:
+The following tools are required::
make gcc (or clang) pkg-config
-For full features, also add:
+For full features, also add::
- libjansson, libnss, libgeoip, liblua5.1, libhiredis, libevent
+ libnss, libgeoip, liblua5.1, libhiredis, libevent
-Rust support:
+Rust support::
rustc, cargo
Not every distro provides Rust packages yet. Rust can also be installed
- directly from the Rust project itself:
+ directly from the Rust project itself::
+
https://www.rust-lang.org/en-US/install.html
Ubuntu/Debian
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
+ make libmagic-dev libjansson libjansson-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 \
+ libcap-ng-dev libcap-ng0 make libmagic-dev \
libnss3-dev libgeoip-dev liblua5.1-dev libhiredis-dev libevent-dev \
python-yaml rustc cargo
For Rust support::
apt-get install rustc cargo
+ cargo install --force --debug --version 0.14.1 cbindgen
.. _install-binary-packages:
To use backports, the backports repository for the current stable
distribution needs to be added to the system-wide sources list.
-For Debian 10 (buster), for instance, run the following as root::
+For Debian 10 (buster), for instance, run the following as ``root``::
echo "deb http://http.debian.net/debian buster-backports main" > \
/etc/apt/sources.list.d/backports.list
Various installation guides for installing from GIT and for other operating systems are maintained at:
https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Suricata_Installation
-
SCPacketTimeString
~~~~~~~~~~~~~~~~~~
-Add SCPacketTimeString to get the packets time string in the format:
+Use ``SCPacketTimeString`` to get the packet's time string in the format:
11/24/2009-18:57:25.179869
::
SCFlowAppLayerProto
~~~~~~~~~~~~~~~~~~~
-Get alprotos as string from the flow. If a alproto is not (yet) known, it
+Get alproto as a string from the flow. If a alproto is not (yet) known, it
returns "unknown".
Example:
Making sense out of Alerts
==========================
-When alert happens it's important to figure out what it means. Is it
+When an alert happens it's important to figure out what it means. Is it
serious? Relevant? A false positive?
To find out more about the rule that fired, it's always a good idea to
look at the actual rule.
The first thing to look at in a rule is the description that follows
-the "msg" keyword. Lets consider an example:
-
-::
+the ``msg`` keyword. Let's consider an example: ::
msg:"ET SCAN sipscan probe";
-The "ET" indicates the rule came from the Emerging Threats
+The "ET" indicates the rule came from the Emerging Threats (Proofpoint)
project. "SCAN" indicates the purpose of the rule is to match on some
-form of scanning. Following that a more or less detailed description
+form of scanning. Following that, a more or less detailed description
is given.
Most rules contain some pointers to more information in the form of
the "reference" keyword.
-Consider the following example rule:
-
-::
-
+Consider the following example rule: ::
alert tcp $HOME_NET any -> $EXTERNAL_NET $HTTP_PORTS \
(msg:"ET CURRENT_EVENTS Adobe 0day Shovelware"; \
reference:url,www.emergingthreats.net/cgi-bin/cvsweb.cgi/sigs/CURRENT_EVENTS/CURRENT_Adobe; \
sid:2010496; rev:2;)
-In this rule the reference keyword indicates 3 url's to visit for more
-information:
-
-::
+In this rule, the reference keyword indicates 3 urls to visit for more
+information: ::
isc.sans.org/diary.html?storyid=7747
doc.emergingthreats.net/2010496
www.emergingthreats.net/cgi-bin/cvsweb.cgi/sigs/CURRENT_EVENTS/CURRENT_Adobe
-Some rules contain a reference like: "reference:cve,2009-3958;" should
+Some rules contain a reference like: ``"reference:cve,2009-3958;"`` should
allow you to find info about the specific CVE using your favorite
search engine.
It's not always straight forward and sometimes not all of that
information is available publicly. Usually asking about it on the
-signature support channel helps a lot then.
+signature support channel can be helpful.
In :doc:`../rule-management/suricata-update` more information on the rule
sources and their documentation and support methods can be found.
For example, if a rule fired that indicates your web application is
attacked, looking at the metadata might reveal that the web
-application replied with 404 not found. This will usually mean the
-attack failed. Usually, not always.
+application replied with ``404 not found``. This will usually mean the
+attack failed but not always.
Not every protocol leads to metadata generation, so when running an
IDS engine like Suricata, it's often recommended to combine it with
.. option:: -u
- Run the unit tests and exit. Requires that Suricata be compiled
+ Run the unit tests and exit. Requires that Suricata be configured
with *--enable-unittests*.
.. option:: -U, --unittest-filter=REGEX
.. option:: --list-unittests
- List all unit tests.
+ Lists available unit tests.
.. option:: --fatal-unittests
Public Data Sets
================
-Collections of pcaps for testing, profiling.
+Collections of pcaps for testing and profiling.
DARPA sets: http://www.ll.mit.edu/mission/communications/cyber/CSTcorpora/ideval/data/
Wireshark: https://wiki.wireshark.org/SampleCaptures
-Security Onion collection: https://github.com/security-onion-solutions/security-onion/wiki/Pcaps
+Security Onion collection: https://securityonion.net/docs/Pcaps
Stratosphere IPS. Malware Capture Facility Project: https://stratosphereips.org/category/dataset.html
================
This guide will give you a quick start to run Suricata and will focus only on
-the basics. For more details read through the different more specific chapters.
+the basics. For more details, read through the more specific chapters.
Installation
------------
sudo apt update
sudo apt install suricata jq
-The dedicated PPA repository is added and after updating the index Suricata can
-be installed. It's recommended to install the tool ``jq`` as well to work with
-the EVE Json output which is used later in this guide.
+The dedicated PPA repository is added, and after updating the index, Suricata can
+be installed. We recommend installing the ``jq`` tool at this time as it will help
+with displaying information from Suricata's EVE JSON output (described later in this guide).
For the installation on other systems or to use specific compile options see
:ref:`installation`.
-When the installation is done you can check what version of Suricata you have
+After installing Suricata, you can check what version of Suricata you have
running and with what options as well as the service state::
sudo suricata --build-info
Basic setup
-----------
-You should check on which interface Suricata should be running and also the
-IP(s) of the interface::
+First, determine the interface(s) and IP address(es) on which Suricata should be inspecting network
+packets::
- ip a
+ $ ip addr
2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
link/ether 00:11:22:33:44:55 brd ff:ff:ff:ff:ff:ff
sudo vim /etc/suricata/suricata.yaml
-There will be a lot of possible configuration options, we focus on the setup of
+There are many possible configuration options, we focus on the setup of
the ``HOME_NET`` variable and the network interface configuration. The
-``HOME_NET`` variable should include, in most scenarios, the IP you have
-configured on the interface you use to monitor and all the local networks in
+``HOME_NET`` variable should include, in most scenarios, the IP address of
+the monitored interface and all the local networks in
use. The default already includes the RFC 1918 networks. In this example
``10.0.0.23`` is already included within ``10.0.0.0/8``. If no other networks
-are used the other predefined can be removed.
+are used the other predefined values can be removed.
-In this example the interface name is ``enp1s0`` so at the ``af-packet``
-section the interface name needs to match. An example interface config might
+In this example the interface name is ``enp1s0`` so the interface name in the
+``af-packet`` section needs to match. An example interface config might
look like this:
Capture settings::
tpacket-v3: yes
This configuration uses the most recent recommended settings for the IDS
-runmode for basic setups. There are a lot of possible configuration options
+runmode for basic setups. There are many of possible configuration options
which are described in dedicated chapters and are especially relevant for high
performance setups.
Signatures
----------
-As Suricata uses Signatures to trigger alerts it's necessary to install those
+Suricata uses Signatures to trigger alerts so it's necessary to install those
and keep them updated. Signatures are also called rules, thus the name
-rule-files. With the tool ``suricata-update`` rules can be fetched, updated and
-managed to be provided for suricata.
+`rule-files`. With the tool ``suricata-update`` rules can be fetched, updated and
+managed to be provided for Suricata.
In this guide we just run the default mode which fetches the ET Open ruleset::
sudo tail /var/log/suricata/suricata.log
-The last line should look like this::
+The last line will be similar to this::
<Notice> - all 4 packet processing threads, 4 management threads initialized, engine started.
-The amount of threads depends on the system and the configuration.
+The actual thread count will depend on the system and the configuration.
-To see statistics the ``stats.log`` can be checked::
+To see statistics, check the ``stats.log`` file::
sudo tail -f /var/log/suricata/stats.log
-Every 20 seconds by default it will show updated informations about the current
+By default, it is updated every 8 seconds to show updated values with the current
state, like how many packets have been processed and what type of traffic was
decoded.
Alerting
--------
-To test the IDS functionality of Suricata it's best to test with a signature. The signature with ID ``2100498`` from the ET Open ruleset is written specific for such test cases.
+To test the IDS functionality of Suricata it's best to test with a signature. The signature with
+ID ``2100498`` from the ET Open ruleset is written specific for such test cases.
2100498::
The syntax and logic behind those signatures is covered in other chapters. This
will alert on any IP traffic that has the content within its payload. This rule
-can be triggered quite easy. Before we trigger it, we will tail on the
-``fast.log`` so we see the result.
+can be triggered quite easy. Before we trigger it, start ``tail`` to see updates to
+``fast.log``.
-Ruletrigger::
+Rule trigger::
sudo tail -f /var/log/suricata/fast.log
curl http://testmyids.com/
EVE Json
--------
-The more advanced output is the EVE Json output which is explained in detail in
+The more advanced output is the EVE JSON output which is explained in detail in
:ref:`Eve JSON Output <eve-json-output>`. To see what this looks like it's
recommended to use ``jq`` to parse the JSON output.
-Alert::
+Alerts::
sudo tail -f /var/log/suricata/eve.json | jq 'select(.event_type=="alert")'
-This will also show much more details and meta-data that are related to the
-triggered alert.
+This will display more detail about each alert, including meta-data.
Stats::
sudo tail -f /var/log/suricata/eve.json | jq 'select(.event_type=="stats")|.stats.capture.kernel_packets'
+ sudo tail -f /var/log/suricata/eve.json | jq 'select(.event_type=="stats")'
-This will only show the amount of packets processed.
+The first example displays the number of packets captured by the kernel; the second
+examples shows all of the statistics.
If you would like to create a rule yourself and use it with Suricata,
this guide might be helpful.
-Start creating a file for your rule. Type for example the following in
-your console:
+Start creating a file for your rule. Use one of the following examples in
+your console/terminal window:
::
sudo nano local.rules
+ sudo vim local.rules
Write your rule, see :doc:`../rules/intro` and save it.
-Open yaml
+Update the Suricata configuration file so your rule is included. Use
+one of the following examples:
::
sudo nano /etc/suricata/suricata.yaml
+ sudo vim /etc/suricata/suricata.yaml
-and make sure your local.rules file is added to the list of rules.
+and make sure your local.rules file is added to the list of rules: ::
+
+ default-rule-path: /usr/local/etc/suricata/rules
+
+ rule-files:
+ - suricata.rules
+ - /path/to/local.rules
Now, run Suricata and see if your rule is being loaded.
suricata -c /etc/suricata/suricata.yaml -i wlan0
-If your rule failed to load, check if you have made a mistake anywhere
-in the rule. Mind the details; look for mistakes in special
-characters, spaces, capital characters etc.
+If the rule failed to load, Suricata will display as much information as
+it has when it deemed the rule un-loadable. Pay special attention to the
+details: look for mistakes in special characters, spaces, capital characters,
+etc.
-Next, check if your log-files are enabled in suricata.yaml.
+Next, check if your log-files are enabled in the Suricata configuration file
+``suricata.yaml``.
-If you had to correct your rule and/or modify yaml, you have to
-restart Suricata.
+If you had to correct your rule and/or modify Suricata's YAML configuration
+file, you'll have to restart Suricata.
If you see your rule is successfully loaded, you can double check your
rule by doing something that should trigger it.
-Enter:
+By default, Suricata will log alerts to two places
-::
+- ``eve.json``
+- ``fast.log``
- tail -f /var/log/suricata/fast.log
+These files will be located in the log output directory which is set by
+one of two methods:
-If you would make a rule like this:
+1. Suricata configuration file: see ``default-log-dir`` for the name of the directory
+2. Suricata command line: Using ``-l /path/to/log-dir`` creates log files in the named
+ directory.
-::
+The following example assumes that the log directory is named ``/var/log/suricata`` ::
+
+ tail -f /var/log/suricata/fast.log
+
+If you would make a rule like this: ::
alert http any any -> any any (msg:"Do not read gossip during work";
content:"Scarlett"; nocase; classtype:policy-violation; sid:1; rev:1;)
-Your alert should look like this:
-
-::
+Your alert should look like this: ::
09/15/2011-16:50:27.725288 [**] [1:1:1] Do not read gossip during work [**]
[Classification: Potential Corporate Privacy Violation] [Priority: 1] {TCP} 192.168.0.32:55604 -> 68.67.185.210:80
Rule Reloads
============
-Suricata can be told to reloads it's rules without restarting.
+Suricata can reload the rules without restarting. This way, there
+is minimal service disruption.
This works by sending Suricata a signal or by using the unix socket. When Suricata is told to reload the rules these are the basic steps it takes:
-* Load new config
+* Load new config to update rule variables and values.
* Load new rules
* Construct new detection engine
* Swap old and new detection engines
kill -USR2 $(pidof suricata)
-Unix socket has two method for rules reload.
+There are two methods available when using the Unix socket.
Blocking reload ::
====================================
While it is possible to download and install rules manually, it is
-recommended to use a management tool for this. Suricata-Update is the
+recommended to use a management tool for this. ``suricata-update`` is the
official way to update and manage rules for Suricata.
-Suricata-update is bundled with Suricata and is normally installed
+``suricata-update`` is bundled with Suricata and is normally installed
with it. For instructions on installing manually, see http://suricata-update.readthedocs.io/en/latest/quickstart.html#install-suricata-update
.. note:: ``suricata-update`` is bundled with Suricata version 4.1 and
Controlling which rules are used
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-By default suricata-update will merge all rules into a single file
+By default ``suricata-update`` will merge all rules into a single file
"/var/lib/suricata/rules/suricata.rules".
To enable rules that are disabled by default, use `/etc/suricata/enable.conf`
bypass
---------
+------
Bypass a flow on matching http traffic.
Using the ``dataset`` and ``datarep`` keyword it is possible to match on
large amounts of data against any sticky buffer.
-For example, to match against a dns black list called ``dns-bl``::
+For example, to match against a DNs black list called ``dns-bl``::
dns.query; dataset:isset,dns-bl;
* reject - send RST/ICMP unreach error to the sender of the matching packet.
* rejectsrc - same as just `reject`
* rejectdst - send RST/ICMP error packet to receiver of the matching packet.
-* rejectboth - send RST/ICMP error packets to both sides of the coversation.
+* rejectboth - send RST/ICMP error packets to both sides of the conversation.
.. note:: In IPS mode, using any of the `reject` actions also enables `drop`.
Setting up IPS with Netfilter
-----------------------------
-In this guide will be explained how to work with Suricata in layer3 inline
-mode and how to set iptables for that purpose.
+In this guide, we'll discuss how to work with Suricata in layer3 `inline
+mode` using ``iptables``.
-First start with compiling Suricata with NFQ support. For instructions
+First, start by compiling Suricata with NFQ support. For instructions
see `Ubuntu Installation
<https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Ubuntu_Installation>`_.
-For more information about NFQ and iptables, see
+For more information about NFQ and ``iptables``, see
:ref:`suricata-yaml-nfq`.
-To check if you have NFQ enabled in your Suricata, enter the following command:
-
-
-::
+To check if you have NFQ enabled in your Suricata build, enter the following command: ::
suricata --build-info
-and examine if you have NFQ between the features.
-
-To run suricata with the NFQ mode, you have to make use of the -q option. This
-option tells Suricata which of the queue numbers it should use.
+and make sure that NFS is listed in the output.
+To run Suricata with the NFQ mode, you have to make use of the ``-q`` option. This
+option tells Suricata which queue numbers it should use.
::
Iptables configuration
~~~~~~~~~~~~~~~~~~~~~~
-First of all it is important to know which traffic you would like to send
-to Suricata. Traffic that passes your computer or traffic that is generated
-by your computer.
+First of all, it is important to know which traffic you would like to send
+to Suricata. There are two choices:
+
+1. Traffic that passes your computer
+2. Traffic that is generated by your computer.
.. image:: setting-up-ipsinline-for-linux/IPtables.png
If Suricata is running on a gateway and is meant to protect the computers
behind that gateway you are dealing with the first scenario: *forward_ing* .
+
If Suricata has to protect the computer it is running on, you are dealing
with the second scenario: *host* (see drawing 2).
+
These two ways of using Suricata can also be combined.
The easiest rule in case of the gateway-scenario to send traffic to Suricata is:
In this case, all forwarded traffic goes to Suricata.
-In case of the host situation, these are the two most simple iptables rules;
+In case of the host situation, these are the two most simple ``iptables`` rules;
::
It is possible to set a queue number. If you do not, the queue number will
be 0 by default.
-Imagine you want Suricata to check for example just TCP-traffic, or all
+Imagine you want Suricata to check for example just TCP traffic, or all
incoming traffic on port 80, or all traffic on destination-port 80, you
can do so like this:
.. image:: setting-up-ipsinline-for-linux/IPtables3.png
-To see if you have set your iptables rules correct make sure Suricata is
+To see if you have set your ``iptables`` rules correct make sure Suricata is
running and enter:
::
.. image:: setting-up-ipsinline-for-linux/iptables_vnL.png
-This description of the use of iptables is the way to use it with IPv4. To
-use it with IPv6 all previous mentioned commands have to start with 'ip6tables'.
+This description of the use of ``iptables`` is the way to use it with IPv4. To
+use it with IPv6 all previous mentioned commands have to start with ``ip6tables``.
It is also possible to let Suricata check both kinds of traffic.
-There is also a way to use iptables with multiple networks (and interface cards). Example:
+There is also a way to use ``iptables`` with multiple networks (and interface cards). Example:
.. image:: setting-up-ipsinline-for-linux/iptables4.png
sudo iptables -I FORWARD -i eth0 -o eth1 -j NFQUEUE
sudo iptables -I FORWARD -i eth1 -o eth0 -j NFQUEUE
-The options -i (input) -o (output) can be combined with all previous mentioned
+The options ``-i`` (input) ``-o`` (output) can be combined with all previous mentioned
options.
If you would stop Suricata and use internet, the traffic will not come through.
-To make internet work correctly, you have to erase all iptables rules.
+To make internet work correctly, first delete all ``iptables`` rules.
-To erase all iptables rules, enter:
+To erase all ``iptables`` rules, enter:
::
NFtables configuration is straight forward and allows mixing firewall rules
with IPS. The concept is to create a dedicated chain for the IPS that will
be evaluated after the firewalling rule. If your main table is named `filter`
-it can be created like so ::
+it can be created like so::
nft> add chain filter IPS { type filter hook forward priority 10;}
NFQUEUE advanced options
~~~~~~~~~~~~~~~~~~~~~~~~
-NFQUEUE mechanism supports some interesting options. The nftables configuration
-will be shown there but the features are also available in iptables.
+NFQUEUE mechanism supports some interesting options. The ``nftables`` configuration
+will be shown there but the features are also available in ``iptables``.
-The full syntax of the queuing mechanism looks as follow ::
+The full syntax of the queuing mechanism is as follows::
nft add rule filter IPS queue num 3-5 options fanout,bypass
- `fanout`: When used together with load balancing, this will use the CPU ID
instead of connection hash as an index to map packets to the queues. The idea
- is that you can improve performance if there’s a queue per CPU. This requires
+ is that you can improve performance if there’s one queue per CPU. This requires
total with a number of queues superior to 1 to be specified.
- `bypass`: By default, if no userspace program is listening on an Netfilter
queue, then all packets that are to be queued are dropped. When this option
AF_PACKET capture method is supporting a IPS/Tap mode. In this mode, you just
need the interfaces to be up. Suricata will take care of copying the packets
-from one interface to the other. No iptables or nftables configuration is
+from one interface to the other. No ``iptables`` or ``nftables`` configuration is
necessary.
You need to dedicate two network interfaces for this mode. The configuration
interface.
For example, the following configuration will create a Suricata acting as IPS
-between interface eth0 and eth1: ::
+between interface ``eth0`` and ``eth1``: ::
af-packet:
- interface: eth0
buffer-size: 64535
use-mmap: yes
-Basically, we’ve got an af-packet configuration with two interfaces. Interface
-eth0 will copy all received packets to eth1 because of the copy-* configuration
-variable ::
+This is a basic af-packet configuration using two interfaces. Interface
+``eth0`` will copy all received packets to ``eth1`` because of the `copy-*`
+configuration variable ::
copy-mode: ips
copy-iface: eth1
-The configuration on eth1 is symmetric ::
+The configuration on ``eth1`` is symmetric ::
copy-mode: ips
copy-iface: eth0
-There is some important points to consider when setting up this mode:
+There are some important points to consider when setting up this mode:
- The implementation of this mode is dependent of the zero copy mode of
- AF_PACKET. Thus you need to set `use-mmap` to yes on both interface.
+ AF_PACKET. Thus you need to set `use-mmap` to `yes` on both interface.
- MTU on both interfaces have to be equal: the copy from one interface to
- the other is direct and packet bigger then the MTU will be dropped by kernel.
-- Set different values of cluster-id on both interfaces to avoid conflict.
+ the other is direct and packets bigger then the MTU will be dropped by kernel.
+- Set different values of `cluster-id` on both interfaces to avoid conflict.
- Any network card offloading creating bigger then physical layer datagram
- (like GRO, LRO, TSO) will result in packets drop as transmit path can not
+ (like GRO, LRO, TSO) will result in dropped packets as transmit path can not
handle them.
-- Set `stream.inline` to `auto` or `yes` so Suricata really switches to
+- Set `stream.inline` to `auto` or `yes` so Suricata switches to
blocking mode.
The `copy-mode` variable can take the following values:
the port information will not be present.
A solution is to use eBPF load balancing to get an IP pair load balancing
-that will be fragmentation resistant. The AF_PACKET IPS Configuration
-using multiple threads and eBPF load balancing looks like the following: ::
+without fragmentation. The AF_PACKET IPS Configuration using multiple threads
+and eBPF load balancing looks like the following: ::
af-packet:
- interface: eth0
buffer-size: 64535
use-mmap: yes
-The eBPF file `/usr/libexec/suricata/ebpf/lb.bpf` may not be present on disk.
+The eBPF file ``/usr/libexec/suricata/ebpf/lb.bpf`` may not be present on disk.
See :ref:`ebpf-xdp` for more information.
`Windows Installation\r
<https://redmine.openinfosecfoundation.org/attachments/download/1175/SuricataWinInstallationGuide_v1.4.3.pdf>`_.\r
This documentation has not yet been updated with WinDivert information, so make\r
-sure to add the following flags to `configure`:\r
+sure to add the following flags before configuring Suricata with ``configure``:\r
\r
::\r
\r
https://www.reqrypt.org/windivert-doc.html#filter_language\r
\r
If Suricata is running on a gateway and is meant to protect the network behind\r
-that gateway, you need to run WinDivert at the NETWORK_FORWARD layer. This can\r
+that gateway, you need to run WinDivert at the `NETWORK_FORWARD` layer. This can\r
be achieved using the following command:\r
\r
::\r
A few additional examples:\r
\r
Only TCP traffic:\r
+\r
::\r
\r
suricata -c suricata.yaml --windivert tcp\r
\r
+\r
Only TCP traffic on port 80:\r
+\r
::\r
\r
suricata -c suricata.yaml --windivert "tcp.DstPort == 80"\r
\r
+\r
TCP and ICMP traffic:\r
+\r
::\r
\r
- suricata -c suricata.yaml --windivert "tcp or icmp"
\ No newline at end of file
+ suricata -c suricata.yaml --windivert "tcp or icmp"\r
------------
Suricata can listen to a unix socket and accept commands from the user. The
-exchange protocol is JSON-based and the format of the message has been done
-to be generic.
+exchange protocol is JSON-based and the format of the message is generic.
-An example script called suricatasc is provided in the source and installed
+An example script called ``suricatasc`` is provided in the source and installed
automatically when installing/updating Suricata.
-The unix socket is enabled by default if libjansson is available.
+The unix socket is always enabled by default.
-You need to have libjansson installed:
+You'll need to have JSON support in Python:
-* libjansson4 - C library for encoding, decoding and manipulating JSON data
-* libjansson-dev - C library for encoding, decoding and manipulating JSON data (dev)
* python-simplejson - simple, fast, extensible JSON encoder/decoder for Python
Debian/Ubuntu::
- apt-get install libjansson4 libjansson-dev python-simplejson
-
-If libjansson is present on the system , unix socket will be compiled
-in automatically.
+ apt-get install python-simplejson
The creation of the socket is managed by setting enabled to 'yes' or 'auto'
-under unix-command in Suricata YAML configuration file:
-
-::
+under unix-command in Suricata YAML configuration file: ::
unix-command:
enabled: yes
filename. The filename is always relative to the local state base
directory.
-Clients are implemented for some language and can be used as code
+Clients are implemented for some programming languages and can be used as code
example to write custom scripts:
-* Python: https://github.com/inliniac/suricata/blob/master/scripts/suricatasc/suricatasc.in (provided with suricata and used in this document)
+* Python: https://github.com/inliniac/suricata/blob/master/scripts/suricatasc/suricatasc.in (provided with Suricata and used in this document)
* Perl: https://github.com/aflab/suricatac (a simple Perl client with interactive mode)
* C: https://github.com/regit/SuricataC (a Unix socket mode client in C without interactive mode)
Commands in standard running mode
---------------------------------
-You may need to install suricatasc if you have not done so, running the following command from python/suricatasc
+You may need to install ``suricatasc`` if you have not done so, running the following command from python/suricatasc
::
The set of existing commands is the following:
* command-list: list available commands
-* shutdown: this shutdown Suricata
+* shutdown: shutdown Suricata
* iface-list: list interfaces where Suricata is sniffing packets
-* iface-stat: list statistic for an interface
+* iface-stat: list statistics for an interface
* help: alias of command-list
* version: display Suricata's version
* uptime: display Suricata's uptime
* ruleset-reload-time: return time of last reload
* ruleset-stats: display the number of rules loaded and failed
* ruleset-failed-rules: display the list of failed rules
-* memcap-set: update memcap value of an item specified
-* memcap-show: show memcap value of an item specified
+* memcap-set: update memcap value of the specified item
+* memcap-show: show memcap value of the specified item
* memcap-list: list all memcap values available
* reload-rules: alias of ruleset-reload-rules
* register-tenant-handler: register a tenant handler with the specified mapping
* remove-hostbit: remove hostbit on a host IP with specified bit name
* list-hostbit: list hostbit for a particular host IP
-You can access to these commands with the provided example script which
-is named ``suricatasc``. A typical session with ``suricatasc`` will looks like:
-
+You can access these commands with the provided example ``suricatasc`` script.
+A typical session with ``suricatasc`` looks like:
+
::
# suricatasc
Commands on the cmd prompt
--------------------------
-You can use suricatasc directly on the command prompt:
-
+You can use ``suricatasc`` directly on the command prompt:
+
::
-
root@debian64:~# suricatasc -c version
- {'message': '2.1beta2 RELEASE', 'return': 'OK'}
+ {'message': '5.0.3 RELEASE', 'return': 'OK'}
root@debian64:~#
root@debian64:~# suricatasc -c uptime
{'message': 35264, 'return': 'OK'}
**NOTE:**
-You need to quote commands involving more than one argument:
-
+You need to quote commands with more than one argument:
+
::
-
root@debian64:~# suricatasc -c "iface-stat eth0"
{'message': {'pkts': 5110429, 'drop': 0, 'invalid-checksums': 0}, 'return': 'OK'}
root@debian64:~#
-Pcap processing mode
+PCAP processing mode
--------------------
-This mode is one of main motivation behind this code. The idea is to
-be able to ask to Suricata to treat different pcap files without
-having to restart Suricata between the files. This provides you a huge
-gain in time as you don't need to wait for the signature engine to
-initialize.
+This mode is one of main motivations behind this code. The idea is to
+be able to provide different pcap files to Suricata without
+having to restart Suricata for each file. This saves time since
+you don't need to wait for the signature engine to initialize.
-To use this mode, start suricata with your preferred YAML file and
-provide the option ``--unix-socket`` as argument:
-
-::
+To use this mode, start Suricata with your preferred configuration YAML file and
+provide the option ``--unix-socket`` as argument::
suricata -c /etc/suricata-full-sigs.yaml --unix-socket
-It is also possible to specify the socket filename as argument:
-
-::
+It is also possible to specify the socket filename as an argument::
suricata --unix-socket=custom.socket
In this last case, you will need to provide the complete path to the
socket to ``suricatasc``. To do so, you need to pass the filename as
-first argument of ``suricatasc``:
-
-::
-
+first argument of ``suricatasc``: ::
+
suricatasc custom.socket
-Once Suricata is started, you can use the provided script
-``suricatasc`` to connect to the command socket and ask for pcap
-treatment:
-
-::
+Once Suricata is started, you can use ``suricatasc`` to connect to the
+command socket and provide different pcap files: ::
root@tiger:~# suricatasc
>>> pcap-file /home/benches/file1.pcap /tmp/file1
>>> pcap-file-continuous /home/pcaps /tmp/dirout
Success: Successfully added file to list
-You can add multiple files without waiting the result: they will be
+You can add multiple files without waiting for each to be processed; they will be
sequentially processed and the generated log/alert files will be put
-into the directory specified as second arguments of the pcap-file
-command. You need to provide absolute path to the files and directory
+into the directory specified as second argument of the pcap-file
+command. You need to provide an absolute path to the files and directory
as Suricata doesn't know from where the script has been run. If you pass
a directory instead of a file, all files in the directory will be processed. If
using ``pcap-file-continuous`` and passing in a directory, the directory will
be monitored for new files being added until you use ``pcap-interrupt`` or
delete/move the directory.
-To know how many files are waiting to get processed, you can do:
-
-::
+To display how many files are waiting to get processed, you can do: ::
>>> pcap-file-number
Success: 3
-To get the list of queued files, do:
-
-::
+To display the list of queued files, do: ::
>>> pcap-file-list
Success: {'count': 2, 'files': ['/home/benches/file1.pcap', '/home/benches/file2.pcap']}
-To get current processed file:
-
-::
+To display current processed file: ::
>>> pcap-current
Success:
The protocol is documented in the following page
https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Unix_Socket#Protocol
-The following session show what is send (SND) and received (RCV) by
-the server. Initial negotiation is the following:
-
-::
+The following session show what is sent (SND) and received (RCV) by
+the server. Initial negotiation is the following: ::
# suricatasc
SND: {"version": "0.1"}
RCV: {"return": "OK"}
-Once this is done, command can be issued:
-
-::
+Once this is done, commands can be issued: ::
>>> iface-list
SND: {"command": "iface-list"}
RCV: {"message": {"pkts": 41508, "drop": 0, "invalid-checksums": 0}, "return": "OK"}
Success: {'pkts': 41508, 'drop': 0, 'invalid-checksums': 0}
-In pcap-file mode, this gives:
-
-::
+In pcap-file mode, this gives: ::
>>> pcap-file /home/eric/git/oisf/benches/sandnet.pcap /tmp/bench
SND: {"command": "pcap-file", "arguments": {"output-dir": "/tmp/bench", "filename": "/home/eric/git/oisf/benches/sandnet.pcap"}}
New versions of Suricata will occasionally include updated config files:
``classification.config`` and ``reference.config``. Since the Suricata
-installation will not overwrite these if they exist, they should be manually
+installation will not overwrite these if they exist, they must be manually
updated. If there are no local modifications they can simply be overwritten
by the ones Suricata supplies.
Upgrading 5.0 to 6.0
--------------------
- SIP now enabled by default
-- EDP now enabled by default
+- RDP now enabled by default
+- ERSPAN Type I enabled by default.
+
+Major changes
+~~~~~~~~~~~~~
+- New protocols enabled by default: mqtt, rfb
+- SSH Client fingerprinting for SSH clients
+- Conditional logging
+- Initial HTTP/2 support
+- DCERPC logging
+- Improved EVE logging performance
Removals
~~~~~~~~
-- File-store v1 has been removed. If using file extraction, the file-store configuration will need to be updated to version 2. See :ref:`filestore-update-v1-to-v2`.
+- File-store v1 has been removed. If using file extraction, the file-store configuration
+ will need to be updated to version 2. See :ref:`filestore-update-v1-to-v2`.
Upgrading 4.1 to 5.0
--------------------
~~~~~~~~
- ``dns-log``, the text dns log. Use EVE.dns instead.
- ``file-log``, the non-EVE JSON file log. Use EVE.files instead.
+- ``drop-log``, the non-EVE JSON drop log.
See https://suricata-ids.org/about/deprecation-policy/
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.
+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 <https://oisf.net>`__). Suricata is developed by the OISF.
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.
-
License
-------
The Suricata source code is licensed under version 2 of the
-:doc:`licenses/gnu-gpl-v2.0`. This documentation is licensed under the
+:doc:`licenses/gnu-gpl-v2.0`.
+
+This documentation is licensed under the
:doc:`licenses/cc-nc-4.0`.
parser = argparse.ArgumentParser(prog='suricatasc', description='Client for Suricata unix socket')
parser.add_argument('-v', '--verbose', action='store_const', const=True, help='verbose output (including JSON dump)')
parser.add_argument('-c', '--command', default=None, help='execute on single command and return JSON')
-parser.add_argument('socket', metavar='socket', nargs='?', help='socket file to connnect to', default=None)
+parser.add_argument('socket', metavar='socket', nargs='?', help='socket file to connect to', default=None)
args = parser.parse_args()
if args.socket != None:
projects / people / ms / suricata.git / commitdiff
