summaryrefslogtreecommitdiffstats
path: root/doc/quickstart.rst
blob: bf57de55b44d5eb86dd5d1b6d1ad9f48c5057d41 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
Quick Start
###########

Install Suricata Update
=======================

Suricata-Update is bundled with all supported versions of Suricata and
should be installed when Suricata is installed. Please check if
``suricata-update`` is already installed before proceeding with these
installation directions, for example, the following command will tell
you the version::

    suricata-update -V

You should only need to install Suricata-Update manually if it is
required independently of a Suricata install.

Suricata-Update is a tool written in Python and best installed with
the ``pip`` tool for installing Python packages.

Pip can install ``suricata-update`` globally making it available to
all users or it can install ``suricata-update`` into your home
directory.

To install ``suricata-update`` globally::

    pip install --upgrade suricata-update

or to install it to your own directory::

    pip install --user --upgrade suricata-update

Pip can also be used to install the latest development version of
Suricata-Update::

    pip install --user --upgrade \
        https://github.com/oisf/suricata-update/archive/master.zip

.. note:: When installing to your home directory the
          ``suricata-update`` program will be installed to
          $HOME/.local/bin, so make sure this directory is in your
          path::

	    export PATH=$HOME/.local/bin:$PATH

Directories and Permissions
===========================

In order for ``suricata-update`` to function, the following
permissions are required:

* Directory /etc/suricata: read/write access
* Directory /var/lib/suricata/rules: read/write access
* Directory /var/lib/suricata/update: read/write access

One option is to simply run ``suricata-update`` as root or with
``sudo``.

.. note:: It is recommended to create a ``suricata`` group and setup
          the above directories with the correct permissions for
          the ``suricata`` group then add users to the ``suricata``
          group.

Steps to setup the above directories with the correct permissions:

First, create a group ``suricata``::

    sudo groupadd suricata

Next, change the group of the directories and its files recursively::

    sudo chgrp -R suricata /etc/suricata
    sudo chgrp -R suricata /var/lib/suricata/rules
    sudo chgrp -R suricata /var/lib/suricata/update

.. note:: The paths ``/etc/suricata`` and ``/var/lib`` above are used
          in the default configuration and are dependent on paths set
          during compilation. By default, these paths are set to
          ``/usr/local``.
          Please check your configuration for appropriate paths.

Setup the directories with the correct permissions for the ``suricata``
group::

    sudo chmod -R g+r /etc/suricata/
    sudo chmod -R g+rw /var/lib/suricata/rules
    sudo chmod -R g+rw /var/lib/suricata/update

Now, add user to the group::

    sudo usermod -a -G suricata username

Verify whether group has been changed::

    ls -al /etc/suricata
    ls -al /var/lib/suricata/rules
    ls -al /var/lib/suricata/update

Reboot your system. Run ``suricata-update`` without a sudo to check
if suricata-update functions.

Update Your Rules
=================

Without doing any configuration the default operation of
``suricata-update`` is to use the Emerging Threats Open ruleset.

Example::

  suricata-update

This command will:

* Look for the ``suricata`` program on your path to determine its
  version.

* Look for /etc/suricata/enable.conf, /etc/suricata/disable.conf,
  /etc/suricata/drop.conf, and /etc/suricata/modify.conf to look for
  filters to apply to the downloaded rules. These files are optional
  and do not need to exist.

* Download the Emerging Threats Open ruleset for your version of
  Suricata, defaulting to 6.0.0 if not found.

* Apply enable, disable, drop and modify filters as loaded above.

* Write out the rules to ``/var/lib/suricata/rules/suricata.rules``.

* Run Suricata in test mode on
  ``/var/lib/suricata/rules/suricata.rules``.

.. note:: Suricata-Update is also capable of triggering a rule reload,
          but doing so requires some extra configuration that will be
          covered later. See the documentation of
          :command:`--reload-command=<command>` for more details.

Configure Suricata to Load Suricata-Update Managed Rules
========================================================

.. note:: If ``suricata-update`` was installed for you by Suricata,
          then your Suricata configuration should already be setup to
          work with Suricata-Update.

If upgrading from an older version of Suricata, or running a
development version that may not be bundled with Suricata-Update, you
will have to check that your ``suricata.yaml`` is configured for
Suricata-Update. The main difference is the ``default-rule-path``
which is ``/var/lib/suricata/rules`` when using Suricata-Update.

You will want to update your ``suricata.yaml`` to have the following::

  default-rule-path: /var/lib/suricata/rules
  rule-files:
    - suricata.rules

If you have local rules you would like Suricata to load, these can be
listed here as well by using the full path name.

Discover Other Available Rule Sources
=====================================

First update the rule source index with the ``update-sources`` command,
for example::

  suricata-update update-sources

Then list the sources from the index. Example::

  suricata-update list-sources

Now enable the **ptresearch/attackdetection** ruleset::

  suricata-update enable-source ptresearch/attackdetection

And update your rules again::

  suricata-update

List Enabled Sources
====================

::

   suricata-update list-sources --enabled

Disable a Source
================

::

   suricata-update disable-source et/pro

Disabling a source keeps the source configuration but disables. This
is useful when a source requires parameters such as a code that you
don't want to lose, which would happen if you removed a source.

Enabling a disabled source re-enables without prompting for user
inputs.

Remove a Source
===============

::

   suricata-update remove-source et/pro

This removes the local configuration for this source. Re-enabling
**et/pro** will requiring re-entering your access code.