doc/userguide/quickstart.rst

   1 Quickstart guide
   2 ================
   3
   4 This guide will give you a quick start to run Suricata and will focus only on
   5 the basics. For more details, read through the more specific chapters.
   6
   7 Installation
   8 ------------
   9
  10 It's assumed that you run a recent Ubuntu release as the official PPA can be
  11 used for the installation.
  12
  13 Installation steps::
  14
  15     sudo add-apt-repository ppa:oisf/suricata-stable
  16     sudo apt update
  17     sudo apt install suricata jq
  18
  19 The dedicated PPA repository is added, and after updating the index, Suricata can
  20 be installed. We recommend installing the ``jq`` tool at this time as it will help
  21 with displaying information from Suricata's EVE JSON output (described later in this guide).
  22
  23 For the installation on other systems or to use specific compile options see
  24 :ref:`installation`.
  25
  26 After installing Suricata, you can check what version of Suricata you have
  27 running and with what options as well as the service state::
  28
  29     sudo suricata --build-info
  30     sudo systemctl status suricata
  31
  32 Basic setup
  33 -----------
  34
  35 First, determine the interface(s) and IP address(es) on which Suricata should be inspecting network
  36 packets::
  37
  38     $ ip addr
  39
  40     2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
  41     link/ether 00:11:22:33:44:55 brd ff:ff:ff:ff:ff:ff
  42     inet 10.0.0.23/24 brd 10.23.0.255 scope global noprefixroute enp1s0
  43
  44 Use that information to configure Suricata::
  45
  46     sudo vim /etc/suricata/suricata.yaml
  47
  48 There are many possible configuration options, we focus on the setup of
  49 the ``HOME_NET`` variable and the network interface configuration. The
  50 ``HOME_NET`` variable should include, in most scenarios, the IP address of
  51 the monitored interface and all the local networks in
  52 use. The default already includes the RFC 1918 networks. In this example
  53 ``10.0.0.23`` is already included within ``10.0.0.0/8``. If no other networks
  54 are used the other predefined values can be removed.
  55
  56 In this example the interface name is ``enp1s0`` so the interface name in the
  57 ``af-packet`` section needs to match. An example interface config might
  58 look like this:
  59
  60 Capture settings::
  61
  62     af-packet:
  63         - interface: enp1s0
  64           cluster-id: 99
  65           cluster-type: cluster_flow
  66           defrag: yes
  67           use-mmap: yes
  68           tpacket-v3: yes
  69
  70 This configuration uses the most recent recommended settings for the IDS
  71 runmode for basic setups. There are many of possible configuration options
  72 which are described in dedicated chapters and are especially relevant for high
  73 performance setups.
  74
  75 Signatures
  76 ----------
  77
  78 Suricata uses Signatures to trigger alerts so it's necessary to install those
  79 and keep them updated. Signatures are also called rules, thus the name
  80 `rule-files`. With the tool ``suricata-update`` rules can be fetched, updated and
  81 managed to be provided for Suricata.
  82
  83 In this guide we just run the default mode which fetches the ET Open ruleset::
  84
  85     sudo suricata-update
  86
  87 Afterwards the rules are installed at ``/var/lib/suricata/rules`` which is also
  88 the default at the config and uses the sole ``suricata.rules`` file.
  89
  90 Running Suricata
  91 ----------------
  92
  93 With the rules installed, Suricata can run properly and thus we restart it::
  94
  95     sudo systemctl restart suricata
  96
  97 To make sure Suricata is running check the Suricata log::
  98
  99     sudo tail /var/log/suricata/suricata.log
 100
 101 The last line will be similar to this::
 102
 103     <Notice> - all 4 packet processing threads, 4 management threads initialized, engine started.
 104
 105 The actual thread count will depend on the system and the configuration.
 106
 107 To see statistics, check the ``stats.log`` file::
 108
 109     sudo tail -f /var/log/suricata/stats.log
 110
 111 By default, it is updated every 8 seconds to show updated values with the current
 112 state, like how many packets have been processed and what type of traffic was
 113 decoded.
 114
 115 Alerting
 116 --------
 117
 118 To test the IDS functionality of Suricata it's best to test with a signature. The signature with
 119 ID ``2100498`` from the ET Open ruleset is written specific for such test cases.
 120
 121 2100498::
 122
 123     alert ip any any -> any any (msg:"GPL ATTACK_RESPONSE id check returned root"; content:"uid=0|28|root|29|"; classtype:bad-unknown; sid:2100498; rev:7; metadata:created_at 2010_09_23, updated_at 2010_09_23;)
 124
 125 The syntax and logic behind those signatures is covered in other chapters. This
 126 will alert on any IP traffic that has the content within its payload. This rule
 127 can be triggered quite easy. Before we trigger it, start ``tail`` to see updates to
 128 ``fast.log``.
 129
 130 Rule trigger::
 131
 132     sudo tail -f /var/log/suricata/fast.log
 133     curl http://testmyids.com/
 134
 135 The following output should now be seen in the log::
 136
 137     [1:2100498:7] GPL ATTACK_RESPONSE id check returned root [**] [Classification: Potentially Bad Traffic] [Priority: 2] {TCP} 217.160.0.187:80 -> 10.0.0.23:41618
 138
 139 This should include the timestamp and the IP of your system.
 140
 141 EVE Json
 142 --------
 143
 144 The more advanced output is the EVE JSON output which is explained in detail in
 145 :ref:`Eve JSON Output <eve-json-output>`. To see what this looks like it's
 146 recommended to use ``jq`` to parse the JSON output.
 147
 148 Alerts::
 149
 150     sudo tail -f /var/log/suricata/eve.json | jq 'select(.event_type=="alert")'
 151
 152 This will display more detail about each alert, including meta-data.
 153
 154 Stats::
 155
 156     sudo tail -f /var/log/suricata/eve.json | jq 'select(.event_type=="stats")|.stats.capture.kernel_packets'
 157     sudo tail -f /var/log/suricata/eve.json | jq 'select(.event_type=="stats")'
 158
 159 The first example displays the number of packets captured by the kernel; the second
 160 examples shows all of the statistics.