From: Jason Ish Date: Fri, 1 Dec 2017 20:31:18 +0000 (-0600) Subject: doc: add quickstart X-Git-Tag: 1.0.0a1~22 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=09a97b335212ffd65f58de435c25160f82dbc602;p=thirdparty%2Fsuricata-update.git doc: add quickstart --- diff --git a/doc/index.rst b/doc/index.rst index 802c529..656b37b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,7 +1,11 @@ ############################################# -suricata-update - A Suricata rule update tool +suricata-update - A Suricata Rule Update Tool ############################################# +.. toctree:: + + quickstart + Synopsis ======== @@ -277,6 +281,9 @@ Example converting all drop rules with noalert back to alert:: Sub Commands ============ +add-sources + Add a new source by URL + add-source - Add a new source by URL ------------------------------------ diff --git a/doc/quickstart.rst b/doc/quickstart.rst new file mode 100644 index 0000000..0295aab --- /dev/null +++ b/doc/quickstart.rst @@ -0,0 +1,173 @@ +Suricata-Update Quick Start +########################### + +Install Suricata Update +======================= + +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 for use by your user. + +.. note:: At some point ``suricata-update`` should be bundled with + Suricata avoid the need for a separate installation. + +To install ``suricata-update`` globally:: + + pip install --pre --upgrade https://github.com/OISF/suricata-update/archive/master.zip + +or to install it to your own directory:: + + pip install --user --pre --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 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 correction permissions for + the ``suricata`` group then add users to the ``suricata`` + group. + + More documentation will be provided about this, including a + tool to verify and maybe setup the permissions. + +Update Your Rules +================= + +Without doing any configuration the default operation of +``suricata-update`` is 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 4.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. + +Configure Suricata to Load Suricata-Update Managed Rules +======================================================== + +Suricata-Update takes a different convention to rule files than +Suricata traditionally has. The most noticeable difference is that the +rules are stored by default in +``/var/lib/suricata/rules/suricata.rules``. + +One way to load the rules is to the the ``-S`` Suricata command line +option. The other is to update your ``suricata.yaml`` to look +something like:: + + default-rule-path: /var/lib/suricata/rules + rule-files: + - suricata.rules + +.. note:: In the future we expect Suricata to use this new convention + by default. + +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 lets at the **ptresearch/attackdetection** ruleset:: + + suricata-update enable-source ptresearch/attackdetection + +And update your rules again:: + + suricata-update + +.. note:: Note that enabling a source changes the default behaviour of + using Emerging Threats Open when no other source has been + configured. So after enabling our first source, Emerging + Threats Open will no longer be downloaded. + +Now we want to add Emerging Threats back, but this time we will choose +the Pro rul eset. Using ``list-sources`` we can see it exists with the +name **et/pro**:: + + suricata-update enable-source et/pro + +Make sure to have your Emerging Threats Pro access code ready as you +will be prompted for it. + +Now run ``suricata-update`` againg to download Emerging Threats Pro +along with the Attack Detection rules. + +List Enabled Sources +==================== + +:: + + suricata-update list-enabled-sources + +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. +