1Ignoring Traffic
2================
3
4In some cases there are reasons to ignore certain traffic. Certain hosts
5may be trusted, or perhaps a backup stream should be ignored.
6
7capture filters (BPF)
8---------------------
9
10Through BPFs the capture methods pcap, af-packet, netmap  and pf_ring can be
11told what to send to Suricata, and what not. For example a simple
12filter 'tcp' will only capture tcp packets.
13
14If some hosts and or nets need to be ignored, use something like "not
15(host IP1 or IP2 or IP3 or net NET/24)".
16
17Example::
18
19    not host 1.2.3.4
20
21Capture filters are specified on the commandline after all other options::
22
23    suricata -i eth0 -v not host 1.2.3.4
24    suricata -i eno1 -c suricata.yaml tcp or udp
25
26Capture filters can be set per interface in the pcap, af-packet, netmap
27and pf_ring sections. It can also be put in a file::
28
29    echo "not host 1.2.3.4" > capture-filter.bpf
30    suricata -i ens5f0 -F capture-filter.bpf
31
32Using a capture filter limits what traffic Suricata processes. So the
33traffic not seen by Suricata will not be inspected, logged or otherwise
34recorded.
35
36BPF and IPS
37^^^^^^^^^^^
38
39In case of IPS modes using af-packet and netmap, BPFs affect how traffic
40is forwarded. If a capture NIC does not capture a packet because of a BPF,
41it will also not be forwarded to the peering NIC.
42
43So in the example of `not host 1.2.3.4`, traffic to and from the IP `1.2.3.4`
44is effectively dropped.
45
46pass rules
47----------
48
49Pass rules are Suricata rules that if matching, pass the packet and in
50case of TCP the rest of the flow. They look like normal rules, except
51that instead of `alert` or `drop` they use `pass` as the action.
52
53Example::
54
55  pass ip 1.2.3.4 any <> any any (msg:"pass all traffic from/to 1.2.3.4"; sid:1;)
56
57A big difference with capture filters is that logs such as Eve or http.log
58are still generated for this traffic.
59
60suppress
61--------
62
63Suppress rules can be used to make sure no alerts are generated for a
64host. This is not efficient however, as the suppression is only
65considered post-matching. In other words, Suricata first inspects a
66rule, and only then will it consider per-host suppressions.
67
68Example::
69
70  suppress gen_id 0, sig_id 0, track by_src, ip 1.2.3.4
71
72
73encrypted traffic
74-----------------
75
76The TLS app layer parser has the ability to stop processing encrypted traffic
77after the initial handshake. By setting the `app-layer.protocols.tls.encryption-handling`
78option to `bypass` the rest of this flow is ignored. If flow bypass is enabled,
79the bypass is done in the kernel or in hardware.
80
81bypassing traffic
82-----------------
83
84Aside from using the ``bypass`` keyword in rules, there are three other ways
85to bypass traffic.
86
87- Within suricata (local bypass). Suricata reads a packet, decodes it, checks
88  it in the flow table. If the corresponding flow is local bypassed then it
89  simply skips all streaming, detection and output and the packet goes directly
90  out in IDS mode and to verdict in IPS mode.
91
92- Within the kernel (capture bypass). When Suricata decides to bypass it calls
93  a function provided by the capture method to declare the bypass in the
94  capture. For NFQ this is a simple mark that will be used by the
95  iptables/nftablesruleset. For AF_PACKET this will be a call to add an element
96  in an eBPF hash table stored in kernel.
97
98- Within the NIC driver. This method relies upon XDP, XDP can process the
99  traffic prior to reaching the kernel.
100
101Additional bypass documentation:
102
103https://suricon.net/wp-content/uploads/2017/12/SuriCon17-Manev_Purzynski.pdf
104https://www.stamus-networks.com/2016/09/28/suricata-bypass-feature/
105