From 06f41f608c16344f83fe183636f1ef23d2979cb1 Mon Sep 17 00:00:00 2001 From: Jeff Lucovsky Date: Sun, 23 Aug 2020 19:42:21 -0400 Subject: [PATCH] doc: Improve grammar, spelling and clarifications This commit improves the overall documentation's grammar, spelling, and adds clarifications where needed. --- doc/userguide/capture-hardware/ebpf-xdp.rst | 52 ++++---- doc/userguide/capture-hardware/endace-dag.rst | 8 +- doc/userguide/capture-hardware/myricom.rst | 14 +-- doc/userguide/capture-hardware/napatech.rst | 20 +-- doc/userguide/capture-hardware/netmap.rst | 14 +-- doc/userguide/command-line-options.rst | 10 +- .../configuration/dropping-privileges.rst | 4 +- .../configuration/global-thresholds.rst | 2 +- doc/userguide/configuration/suricata-yaml.rst | 2 +- .../file-extraction/config-update.rst | 7 +- .../file-extraction/file-extraction.rst | 28 ++--- doc/userguide/file-extraction/md5.rst | 33 +---- .../public-sha1-md5-data-sets.rst | 2 +- doc/userguide/initscripts.rst | 4 +- doc/userguide/install.rst | 29 ++--- doc/userguide/lua/lua-functions.rst | 4 +- doc/userguide/make-sense-alerts.rst | 29 ++--- doc/userguide/partials/options-unittests.rst | 4 +- doc/userguide/public-data-sets.rst | 4 +- doc/userguide/quickstart.rst | 64 +++++----- .../rule-management/adding-your-own-rules.rst | 53 +++++--- doc/userguide/rule-management/rule-reload.rst | 7 +- .../rule-management/suricata-update.rst | 6 +- doc/userguide/rules/bypass-keyword.rst | 2 +- doc/userguide/rules/datasets.rst | 2 +- doc/userguide/rules/intro.rst | 2 +- .../setting-up-ipsinline-for-linux.rst | 88 ++++++------- .../setting-up-ipsinline-for-windows.rst | 11 +- doc/userguide/unix-socket.rst | 118 +++++++----------- doc/userguide/upgrade.rst | 18 ++- doc/userguide/what-is-suricata.rst | 7 +- python/bin/suricatasc | 2 +- 32 files changed, 309 insertions(+), 341 deletions(-) diff --git a/doc/userguide/capture-hardware/ebpf-xdp.rst b/doc/userguide/capture-hardware/ebpf-xdp.rst index baf12b2fc..116038716 100644 --- a/doc/userguide/capture-hardware/ebpf-xdp.rst +++ b/doc/userguide/capture-hardware/ebpf-xdp.rst @@ -15,8 +15,8 @@ between kernel and userspace. 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 @@ -42,7 +42,7 @@ More info about XDP: 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 @@ -62,7 +62,7 @@ This guide has been confirmed on Debian/Ubuntu "LTS" Linux. 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 @@ -76,7 +76,7 @@ You need to run a kernel 4.13 or newer. 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 @@ -101,26 +101,26 @@ Now, you can build and install the library :: 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/ @@ -167,14 +167,14 @@ For instance one could use :: 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/ @@ -192,7 +192,7 @@ Then setup the `ebpf-filter-file` variable in af-packet section in ``suricata.ya 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 @@ -200,7 +200,7 @@ Setup eBPF bypass ----------------- 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 @@ -213,13 +213,13 @@ update af-packet configuration in ``suricata.yaml`` to set bypass to yes :: 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 ------------------------- @@ -253,15 +253,15 @@ and point the ``ebpf-lb-file`` variable to the ``lb.bpf`` file :: 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/ @@ -299,7 +299,7 @@ In the XDP filter file, you can set ``ENCRYPTED_TLS_BYPASS`` to 1 if you want to 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 @@ -343,7 +343,7 @@ Run the following command to disable offloading :: 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 @@ -430,7 +430,7 @@ Pinned maps usage 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. @@ -525,7 +525,7 @@ To achieve this, edit the beginning of `ebpf/xdp_filter.c` and do :: 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 :: diff --git a/doc/userguide/capture-hardware/endace-dag.rst b/doc/userguide/capture-hardware/endace-dag.rst index 72eb78f8f..854fd4b85 100644 --- a/doc/userguide/capture-hardware/endace-dag.rst +++ b/doc/userguide/capture-hardware/endace-dag.rst @@ -7,10 +7,8 @@ Steps: Configure with DAG support: - :: - ./configure --enable-dag --prefix=/usr --sysconfdir=/etc --localstatedir=/var make sudo make install @@ -19,7 +17,6 @@ Results in: :: - Suricata Configuration: AF_PACKET support: no PF_RING support: no @@ -28,16 +25,15 @@ Results in: DAG enabled: yes Napatech enabled: no -Start with: +Start with: :: - suricata -c suricata.yaml --dag 0:0 -Started up! +Started up! :: diff --git a/doc/userguide/capture-hardware/myricom.rst b/doc/userguide/capture-hardware/myricom.rst index cf8c6f47d..1898ff247 100644 --- a/doc/userguide/capture-hardware/myricom.rst +++ b/doc/userguide/capture-hardware/myricom.rst @@ -3,7 +3,7 @@ Myricom 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: :: @@ -11,11 +11,10 @@ In this guide I'll describe using the Myricom libpcap support. I'm going to assu [ 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: - :: @@ -35,7 +34,7 @@ Next, configure the amount of ringbuffers. I'm going to work with 8 here, as my 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: @@ -44,18 +43,17 @@ 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: @@ -95,4 +93,4 @@ Additional Info * 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- diff --git a/doc/userguide/capture-hardware/napatech.rst b/doc/userguide/capture-hardware/napatech.rst index 1c01ca300..27d99112f 100644 --- a/doc/userguide/capture-hardware/napatech.rst +++ b/doc/userguide/capture-hardware/napatech.rst @@ -58,7 +58,7 @@ Debian Based Distros:: $ 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 @@ -124,14 +124,14 @@ Below are the options to set:: 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 @@ -144,7 +144,7 @@ Example Configuration - Auto-config with cpu-affinity: ------------------------------------------------------ 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 @@ -183,7 +183,7 @@ To do this make the following changes to ntservice.ini:: 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 @@ -233,7 +233,7 @@ commands to complete the setup. Create a file will the following commands:: 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 @@ -247,7 +247,7 @@ creating the appropriate NTPL file and attaching Suricata to the streams. 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 @@ -519,7 +519,7 @@ This insures that, should Suricata get behind in its packet processing, the othe 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 diff --git a/doc/userguide/capture-hardware/netmap.rst b/doc/userguide/capture-hardware/netmap.rst index 9ee25f58d..8b227581c 100644 --- a/doc/userguide/capture-hardware/netmap.rst +++ b/doc/userguide/capture-hardware/netmap.rst @@ -26,7 +26,7 @@ Follow the instructions on installation included in the NETMAP repository. 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:: @@ -52,15 +52,15 @@ Suricata can be started in 2 ways to use netmap: suricata --netmap= 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. :: @@ -70,8 +70,8 @@ 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 diff --git a/doc/userguide/command-line-options.rst b/doc/userguide/command-line-options.rst index 77f6a381a..9baeb7eff 100644 --- a/doc/userguide/command-line-options.rst +++ b/doc/userguide/command-line-options.rst @@ -10,10 +10,12 @@ Suricata's command line options: 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 diff --git a/doc/userguide/configuration/dropping-privileges.rst b/doc/userguide/configuration/dropping-privileges.rst index 937a3951a..444f3d42e 100644 --- a/doc/userguide/configuration/dropping-privileges.rst +++ b/doc/userguide/configuration/dropping-privileges.rst @@ -1,7 +1,7 @@ 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. @@ -38,7 +38,7 @@ e.g. (this assumes a 'suri' user and group): 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. :: diff --git a/doc/userguide/configuration/global-thresholds.rst b/doc/userguide/configuration/global-thresholds.rst index ff070d13a..d268dd7c3 100644 --- a/doc/userguide/configuration/global-thresholds.rst +++ b/doc/userguide/configuration/global-thresholds.rst @@ -87,7 +87,7 @@ Time in seconds during which the ``rate_filter`` will remain active. 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. diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst index e76e3ea26..152d7977c 100644 --- a/doc/userguide/configuration/suricata-yaml.rst +++ b/doc/userguide/configuration/suricata-yaml.rst @@ -691,7 +691,7 @@ On `x86_64` hs (Hyperscan) should be used for best performance. 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.) diff --git a/doc/userguide/file-extraction/config-update.rst b/doc/userguide/file-extraction/config-update.rst index 5c3c18078..5035ac824 100644 --- a/doc/userguide/file-extraction/config-update.rst +++ b/doc/userguide/file-extraction/config-update.rst @@ -17,12 +17,13 @@ Given a file-store configuration like:: 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:: diff --git a/doc/userguide/file-extraction/file-extraction.rst b/doc/userguide/file-extraction/file-extraction.rst index 1e7d14231..17195b5d3 100644 --- a/doc/userguide/file-extraction/file-extraction.rst +++ b/doc/userguide/file-extraction/file-extraction.rst @@ -12,7 +12,7 @@ In case of HTTP, the parser takes care of dechunking and unzipping the request a 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: @@ -29,7 +29,7 @@ Settings *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..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..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..response-body-limit* is like the request body limit, only it applies to the HTTP response body. @@ -40,8 +40,8 @@ Output 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. @@ -114,55 +114,47 @@ Rules 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 diff --git a/doc/userguide/file-extraction/md5.rst b/doc/userguide/file-extraction/md5.rst index bab883260..939463b46 100644 --- a/doc/userguide/file-extraction/md5.rst +++ b/doc/userguide/file-extraction/md5.rst @@ -6,17 +6,15 @@ Storing MD5s checksums 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: @@ -37,10 +35,8 @@ For JSON output: Other settings affecting :doc:`file-extraction` - :: - stream: memcap: 64mb checksum-validation: yes # reject wrong csums @@ -56,7 +52,6 @@ Make sure we have *depth: 0* so all files can be tracked fully. :: - libhtp: default-config: personality: IDS @@ -75,26 +70,21 @@ For the purpose of testing we use this rule only in a file.rules (a test/example :: - 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 @@ -115,7 +105,6 @@ and in files-json.log (or eve.json) : :: - { "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 } @@ -125,21 +114,11 @@ Log all MD5s without any rules 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 diff --git a/doc/userguide/file-extraction/public-sha1-md5-data-sets.rst b/doc/userguide/file-extraction/public-sha1-md5-data-sets.rst index f5e7d09b3..2e850ce95 100644 --- a/doc/userguide/file-extraction/public-sha1-md5-data-sets.rst +++ b/doc/userguide/file-extraction/public-sha1-md5-data-sets.rst @@ -1,4 +1,4 @@ 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 diff --git a/doc/userguide/initscripts.rst b/doc/userguide/initscripts.rst index a479df239..7549c01bf 100644 --- a/doc/userguide/initscripts.rst +++ b/doc/userguide/initscripts.rst @@ -1,14 +1,14 @@ 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 diff --git a/doc/userguide/install.rst b/doc/userguide/install.rst index 18b0f4068..5ec24b031 100644 --- a/doc/userguide/install.rst +++ b/doc/userguide/install.rst @@ -6,7 +6,7 @@ Installation 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`. @@ -18,8 +18,8 @@ Installing from the source distribution files gives the most control over the Su 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 @@ -61,24 +61,25 @@ Common configure options 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 @@ -88,13 +89,13 @@ 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 + 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 @@ -107,6 +108,7 @@ Extra for iptables/nftables IPS integration:: For Rust support:: apt-get install rustc cargo + cargo install --force --debug --version 0.14.1 cbindgen .. _install-binary-packages: @@ -137,7 +139,7 @@ if it can be built there. 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 @@ -169,4 +171,3 @@ Advanced Installation Various installation guides for installing from GIT and for other operating systems are maintained at: https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Suricata_Installation - diff --git a/doc/userguide/lua/lua-functions.rst b/doc/userguide/lua/lua-functions.rst index 5bd715137..60a29ebab 100644 --- a/doc/userguide/lua/lua-functions.rst +++ b/doc/userguide/lua/lua-functions.rst @@ -31,7 +31,7 @@ Get packets timestamp as 2 numbers: seconds & microseconds elapsed since 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 :: @@ -92,7 +92,7 @@ SCFlowTuple 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: diff --git a/doc/userguide/make-sense-alerts.rst b/doc/userguide/make-sense-alerts.rst index e648fbe78..819ec5e5d 100644 --- a/doc/userguide/make-sense-alerts.rst +++ b/doc/userguide/make-sense-alerts.rst @@ -1,31 +1,26 @@ 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"; \ @@ -39,22 +34,20 @@ Consider the following example rule: 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. @@ -65,8 +58,8 @@ a lot of metadata will be added to the alert. 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 diff --git a/doc/userguide/partials/options-unittests.rst b/doc/userguide/partials/options-unittests.rst index 2fd1e2db5..971e8fd98 100644 --- a/doc/userguide/partials/options-unittests.rst +++ b/doc/userguide/partials/options-unittests.rst @@ -2,7 +2,7 @@ .. 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 @@ -13,7 +13,7 @@ .. option:: --list-unittests - List all unit tests. + Lists available unit tests. .. option:: --fatal-unittests diff --git a/doc/userguide/public-data-sets.rst b/doc/userguide/public-data-sets.rst index 2e6789dab..1f50d6fcb 100644 --- a/doc/userguide/public-data-sets.rst +++ b/doc/userguide/public-data-sets.rst @@ -1,7 +1,7 @@ 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/ @@ -13,6 +13,6 @@ Netresec: http://www.netresec.com/?page=PcapFiles 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 diff --git a/doc/userguide/quickstart.rst b/doc/userguide/quickstart.rst index 89ec646cf..6de10594c 100644 --- a/doc/userguide/quickstart.rst +++ b/doc/userguide/quickstart.rst @@ -2,7 +2,7 @@ Quickstart guide ================ 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 ------------ @@ -16,14 +16,14 @@ Installation steps:: 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 @@ -32,10 +32,10 @@ running and with what options as well as the service state:: 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: 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 @@ -45,16 +45,16 @@ Use that information to configure Suricata:: 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:: @@ -68,17 +68,17 @@ 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:: @@ -98,24 +98,25 @@ To make sure Suricata is running check the Suricata log:: sudo tail /var/log/suricata/suricata.log -The last line should look like this:: +The last line will be similar to this:: - 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:: @@ -123,10 +124,10 @@ To test the IDS functionality of Suricata it's best to test with a signature. Th 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/ @@ -140,19 +141,20 @@ This should include the timestamp and the IP of your system. 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 `. 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. diff --git a/doc/userguide/rule-management/adding-your-own-rules.rst b/doc/userguide/rule-management/adding-your-own-rules.rst index 83305cdb9..2a2264b92 100644 --- a/doc/userguide/rule-management/adding-your-own-rules.rst +++ b/doc/userguide/rule-management/adding-your-own-rules.rst @@ -4,22 +4,31 @@ Adding Your Own Rules 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. @@ -27,34 +36,42 @@ 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 diff --git a/doc/userguide/rule-management/rule-reload.rst b/doc/userguide/rule-management/rule-reload.rst index a73c5ceca..5c29232d6 100644 --- a/doc/userguide/rule-management/rule-reload.rst +++ b/doc/userguide/rule-management/rule-reload.rst @@ -1,11 +1,12 @@ 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 @@ -18,7 +19,7 @@ Signal:: kill -USR2 $(pidof suricata) -Unix socket has two method for rules reload. +There are two methods available when using the Unix socket. Blocking reload :: diff --git a/doc/userguide/rule-management/suricata-update.rst b/doc/userguide/rule-management/suricata-update.rst index 89a4b7ac6..0c86d0f5d 100644 --- a/doc/userguide/rule-management/suricata-update.rst +++ b/doc/userguide/rule-management/suricata-update.rst @@ -2,10 +2,10 @@ Rule Management with Suricata-Update ==================================== 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 @@ -82,7 +82,7 @@ To see which rulesets are currently active, use "list-enabled-sources". 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` diff --git a/doc/userguide/rules/bypass-keyword.rst b/doc/userguide/rules/bypass-keyword.rst index 11b60fb0e..787fe4236 100644 --- a/doc/userguide/rules/bypass-keyword.rst +++ b/doc/userguide/rules/bypass-keyword.rst @@ -9,7 +9,7 @@ The ``bypass`` keyword is considered a post-match keyword. bypass --------- +------ Bypass a flow on matching http traffic. diff --git a/doc/userguide/rules/datasets.rst b/doc/userguide/rules/datasets.rst index 1e01de934..7ea32d5f0 100644 --- a/doc/userguide/rules/datasets.rst +++ b/doc/userguide/rules/datasets.rst @@ -7,7 +7,7 @@ Datasets 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; diff --git a/doc/userguide/rules/intro.rst b/doc/userguide/rules/intro.rst index b600cc34e..bb071144b 100644 --- a/doc/userguide/rules/intro.rst +++ b/doc/userguide/rules/intro.rst @@ -52,7 +52,7 @@ Valid actions are: * 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`. diff --git a/doc/userguide/setting-up-ipsinline-for-linux.rst b/doc/userguide/setting-up-ipsinline-for-linux.rst index 90bb79e0b..10024f945 100644 --- a/doc/userguide/setting-up-ipsinline-for-linux.rst +++ b/doc/userguide/setting-up-ipsinline-for-linux.rst @@ -4,27 +4,23 @@ Setting up IPS/inline for Linux 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 `_. -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. :: @@ -34,9 +30,11 @@ option tells Suricata which of the 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 @@ -44,8 +42,10 @@ by your computer. 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: @@ -56,7 +56,7 @@ 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; :: @@ -66,7 +66,7 @@ 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: @@ -88,7 +88,7 @@ In this example, Suricata checks all input and output on port 80. .. 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: :: @@ -99,11 +99,11 @@ In the example you can see if packets are being logged. .. 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 @@ -112,13 +112,13 @@ There is also a way to use iptables with multiple networks (and interface cards) 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: :: @@ -131,7 +131,7 @@ Nftables configuration 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;} @@ -147,10 +147,10 @@ To only do it for packets exchanged between eth0 and eth1 :: 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 @@ -164,7 +164,7 @@ multiple queues on command line: :: - `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 @@ -182,7 +182,7 @@ AF_PACKET IPS mode 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 @@ -190,7 +190,7 @@ is made via configuration variable available in the description of an AF_PACKET 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 @@ -212,29 +212,29 @@ between interface eth0 and eth1: :: 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: @@ -249,8 +249,8 @@ reach the same thread as the full featured packet of the same flow because 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 @@ -274,5 +274,5 @@ using multiple threads and eBPF load balancing looks like the following: :: 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. diff --git a/doc/userguide/setting-up-ipsinline-for-windows.rst b/doc/userguide/setting-up-ipsinline-for-windows.rst index cb37078c3..0581e83a8 100644 --- a/doc/userguide/setting-up-ipsinline-for-windows.rst +++ b/doc/userguide/setting-up-ipsinline-for-windows.rst @@ -8,7 +8,7 @@ First start by compiling Suricata with WinDivert support. For instructions, see `Windows Installation `_. This documentation has not yet been updated with WinDivert information, so make -sure to add the following flags to `configure`: +sure to add the following flags before configuring Suricata with ``configure``: :: @@ -29,7 +29,7 @@ For information on the WinDivert filter language, see https://www.reqrypt.org/windivert-doc.html#filter_language If Suricata is running on a gateway and is meant to protect the network behind -that gateway, you need to run WinDivert at the NETWORK_FORWARD layer. This can +that gateway, you need to run WinDivert at the `NETWORK_FORWARD` layer. This can be achieved using the following command: :: @@ -49,16 +49,21 @@ command: A few additional examples: Only TCP traffic: + :: suricata -c suricata.yaml --windivert tcp + Only TCP traffic on port 80: + :: suricata -c suricata.yaml --windivert "tcp.DstPort == 80" + TCP and ICMP traffic: + :: - suricata -c suricata.yaml --windivert "tcp or icmp" \ No newline at end of file + suricata -c suricata.yaml --windivert "tcp or icmp" diff --git a/doc/userguide/unix-socket.rst b/doc/userguide/unix-socket.rst index 510455440..3c0722a2a 100644 --- a/doc/userguide/unix-socket.rst +++ b/doc/userguide/unix-socket.rst @@ -5,31 +5,23 @@ Introduction ------------ 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 @@ -39,10 +31,10 @@ The ``filename`` variable can be used to set an alternate socket 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) @@ -50,7 +42,7 @@ example to write custom scripts: 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 :: @@ -59,9 +51,9 @@ You may need to install suricatasc if you have not done so, running the followin 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 @@ -75,8 +67,8 @@ The set of existing commands is the following: * 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 @@ -88,9 +80,9 @@ The set of existing commands is the following: * 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 @@ -106,13 +98,12 @@ is named ``suricatasc``. A typical session with ``suricatasc`` will looks like: 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'} @@ -120,51 +111,40 @@ You can use suricatasc directly on the command prompt: **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 @@ -174,33 +154,27 @@ treatment: >>> 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: @@ -228,18 +202,14 @@ Build your own client 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"} @@ -250,9 +220,7 @@ Once this is done, command can be issued: 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"}} diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst index 7af08fceb..1dc92b794 100644 --- a/doc/userguide/upgrade.rst +++ b/doc/userguide/upgrade.rst @@ -23,7 +23,7 @@ Configuration Updates 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. @@ -33,11 +33,22 @@ remove features. 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 -------------------- @@ -60,5 +71,6 @@ Removals ~~~~~~~~ - ``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/ diff --git a/doc/userguide/what-is-suricata.rst b/doc/userguide/what-is-suricata.rst index 8cd49cdca..ae388bd05 100644 --- a/doc/userguide/what-is-suricata.rst +++ b/doc/userguide/what-is-suricata.rst @@ -1,17 +1,18 @@ 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 `__). 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`. diff --git a/python/bin/suricatasc b/python/bin/suricatasc index 32c561c5c..4dbe51344 100755 --- a/python/bin/suricatasc +++ b/python/bin/suricatasc @@ -47,7 +47,7 @@ except: 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: -- 2.39.2