From: Andreas Herz Date: Sat, 31 Aug 2019 22:39:04 +0000 (+0200) Subject: doc: add quickstart guide X-Git-Tag: suricata-5.0.0-rc1~71 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d657fd9bf05b368d72da2fcea95e9348f80984f0;p=thirdparty%2Fsuricata.git doc: add quickstart guide --- diff --git a/doc/userguide/index.rst b/doc/userguide/index.rst index 7e426caaf9..820fe90980 100644 --- a/doc/userguide/index.rst +++ b/doc/userguide/index.rst @@ -6,6 +6,7 @@ Suricata User Guide :maxdepth: 2 what-is-suricata + quickstart install.rst command-line-options rules/index.rst diff --git a/doc/userguide/install.rst b/doc/userguide/install.rst index 6ed024ae21..fe6a2b4012 100644 --- a/doc/userguide/install.rst +++ b/doc/userguide/install.rst @@ -1,3 +1,5 @@ +.. _installation: + Installation ============ diff --git a/doc/userguide/quickstart.rst b/doc/userguide/quickstart.rst new file mode 100644 index 0000000000..89ec646cfb --- /dev/null +++ b/doc/userguide/quickstart.rst @@ -0,0 +1,158 @@ +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. + +Installation +------------ + +It's assumed that you run a recent Ubuntu release as the official PPA can be +used for the installation. + +Installation steps:: + + sudo add-apt-repository ppa:oisf/suricata-stable + 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. + +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 +running and with what options as well as the service state:: + + sudo suricata --build-info + sudo systemctl status suricata + +Basic setup +----------- + +You should check on which interface Suricata should be running and also the +IP(s) of the interface:: + + ip a + + 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 + inet 10.0.0.23/24 brd 10.23.0.255 scope global noprefixroute enp1s0 + +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 +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 +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. + +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 +look like this: + +Capture settings:: + + af-packet: + - interface: enp1s0 + cluster-id: 99 + cluster-type: cluster_flow + defrag: yes + use-mmap: yes + 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 +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 +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. + +In this guide we just run the default mode which fetches the ET Open ruleset:: + + sudo suricata-update + +Afterwards the rules are installed at ``/var/lib/suricata/rules`` which is also +the default at the config and uses the sole ``suricata.rules`` file. + +Running Suricata +---------------- + +With the rules installed, Suricata can run properly and thus we restart it:: + + sudo systemctl restart suricata + +To make sure Suricata is running check the Suricata log:: + + sudo tail /var/log/suricata/suricata.log + +The last line should look like this:: + + - all 4 packet processing threads, 4 management threads initialized, engine started. + +The amount of threads depends on the system and the configuration. + +To see statistics the ``stats.log`` can be checked:: + + sudo tail -f /var/log/suricata/stats.log + +Every 20 seconds by default it will show updated informations about 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. + +2100498:: + + 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;) + +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. + +Ruletrigger:: + + sudo tail -f /var/log/suricata/fast.log + curl http://testmyids.com/ + +The following output should now be seen in the log:: + + [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 + +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 +:ref:`Eve JSON Output `. To see what this looks like it's +recommended to use ``jq`` to parse the JSON output. + +Alert:: + + 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. + +Stats:: + + sudo tail -f /var/log/suricata/eve.json | jq 'select(.event_type=="stats")|.stats.capture.kernel_packets' + +This will only show the amount of packets processed.