diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 156 | ||||
| -rw-r--r-- | doc/_static/.gitignore | 0 | ||||
| -rw-r--r-- | doc/add-source.rst | 45 | ||||
| -rw-r--r-- | doc/check-versions.rst | 21 | ||||
| -rw-r--r-- | doc/common-options.rst | 51 | ||||
| -rw-r--r-- | doc/conf.py | 247 | ||||
| -rw-r--r-- | doc/disable-source.rst | 22 | ||||
| -rw-r--r-- | doc/enable-source.rst | 35 | ||||
| -rw-r--r-- | doc/index.rst | 16 | ||||
| -rw-r--r-- | doc/list-sources.rst | 28 | ||||
| -rw-r--r-- | doc/quickstart.rst | 209 | ||||
| -rw-r--r-- | doc/remove-source.rst | 21 | ||||
| -rw-r--r-- | doc/update-sources.rst | 40 | ||||
| -rw-r--r-- | doc/update.rst | 324 |
14 files changed, 1215 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..bfa0803 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,156 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXAPIDOC = sphinx-apidoc +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +all: html + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/suricataupdate.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/suricataupdate.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/suricataupdate" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/suricataupdate" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/_static/.gitignore b/doc/_static/.gitignore new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/_static/.gitignore diff --git a/doc/add-source.rst b/doc/add-source.rst new file mode 100644 index 0000000..c49692c --- /dev/null +++ b/doc/add-source.rst @@ -0,0 +1,45 @@ +################################ +add-source - Add a source by URL +################################ + +Synopsis +======== + +:: + + suricata-update add-source <name> <url> + +Description +=========== + +The ``add-source`` adds a source to the set of enabled sources by +URL. It is useful to add a source that is not provided in the index. + +Options +======= + +.. option:: --http-header "Header: Value" + + Add an additional HTTP header to requests for this rule source such + as a custom API key. Example:: + + add-source --http-header "X-API-Key: 1234" + + HTTP basic authentication can be achieved by setting the HTTP Basic + Authentication header with ``base64(user1:password1)``. Example:: + + add-source --http-header "Authorization: Basic dXNlcjE6cGFzc3dvcmQx" + + HTTP Bearer authentication can be used by setting the HTTP Bearer Authentication header + with a OAuth2 token containing printable ASCII characters. Example:: + + add-source --http-header "Auhorization: Bearer NjA2MTUOTAx?D+wOm4U/vpXQy0xhl!hSaR7#ENVpK59" + +.. option:: --no-checksum + + Skips downloading the checksum URL for the rule source. + +Common Options +============== + +.. include:: ./common-options.rst diff --git a/doc/check-versions.rst b/doc/check-versions.rst new file mode 100644 index 0000000..8be2e0a --- /dev/null +++ b/doc/check-versions.rst @@ -0,0 +1,21 @@ +########################################## +check-versions - Check version of Suricata +########################################## + +Synopsis +======== + +:: + + suricata-update check-versions + +Description +=========== + +The ``check-versions`` command checks if the installed Suricata version is up +to date. + +Options +======= + +.. include:: common-options.rst diff --git a/doc/common-options.rst b/doc/common-options.rst new file mode 100644 index 0000000..d56df99 --- /dev/null +++ b/doc/common-options.rst @@ -0,0 +1,51 @@ +.. option:: -h, --help + + Show help. + +.. option:: -D <directory>, --data-dir <directory> + + Set an alternate data directory. + + Default: */var/lib/suricata* + +.. option:: -c <filename>, --config <filename> + + Path to the suricata-update config file. + + Default: */etc/suricata/update.yaml* + +.. option:: -q, --quiet + + Run quietly. Only warning and error messages will be displayed. + +.. option:: -v, --verbose + + Provide more verbose output. + +.. option:: --suricata-conf <path> + + Path to the suricata config file. + + Default: */etc/suricata/suricata.yaml* + +.. option:: --suricata <path> + + The path to the Suricata program. If not provided + ``suricata-update`` will attempt to find Suricata on your path. + + The Suricata program is used to determine the version of Suricata + as well as providing information about the Suricata configuration. + +.. option:: --suricata-version <version> + + Set the Suricata version to a specific version instead of checking + the version of Suricata on the path. + +.. option:: --user-agent <string> + + Set a custom user agent string for HTTP requests. + +.. option:: -s, --show-advanced + + Show advanced options. +
\ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..b779bc9 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,247 @@ +# -*- coding: utf-8 -*- +# +# Suricata-Update documentation build configuration file, created by +# sphinx-quickstart on Wed Jul 17 23:14:56 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('..')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'sphinxcontrib.programoutput'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'suricata-update' +copyright = u'2017, OISF' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +import suricata.update.version + +version = suricata.update.version.version +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'suricataupdatedoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'suricata-update.tex', u'Suricata Update Documentation', + u'OISF', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'suricata-update', u'Suricata Update', [], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'suricata-update', u'Suricata Update Documentation', + u'OISF', 'suricata-update', 'Suricata Update Documentation.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +highlight_language = "none" diff --git a/doc/disable-source.rst b/doc/disable-source.rst new file mode 100644 index 0000000..b2c9ef0 --- /dev/null +++ b/doc/disable-source.rst @@ -0,0 +1,22 @@ +########################################## +disable-source - Disable an enabled source +########################################## + +Synopsis +======== + +:: + + suricata-update disable-source <name> + +Description +=========== + +The ``disable-source`` command disables a currently enabled +source. The configuration for the source is not removed, allowing it +to be re-enabled without having to re-enter any required parameters. + +Options +======= + +.. include:: ./common-options.rst diff --git a/doc/enable-source.rst b/doc/enable-source.rst new file mode 100644 index 0000000..476b87f --- /dev/null +++ b/doc/enable-source.rst @@ -0,0 +1,35 @@ +############################### +enable-source - Enable a source +############################### + +Synopsis +======== + +:: + + suricata-update enable-source <source-name> [param=val ...] + +Description +=========== + +Enable a source that is listed in the index. + +If the index requires user provided parameters the user will be +prompted for them. Alternatively they can be provided on command line +to avoid the prompt. + +For example:: + + suricata-update enable-source et/pro secret-code=xxxxxxxxxxxxxxxx + +This will prevent the prompt for the et/pro secret code using the +value provided on the command line instead. + +To update parameters for enabled sources, just re-run the ``enable-source`` +command above again with changed parameters. Changed parameters will be +updated in the stored configuration. + +Options +======= + +.. include:: ./common-options.rst diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..a9268c9 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,16 @@ +############################################# +suricata-update - A Suricata Rule Update Tool +############################################# + +.. toctree:: + :maxdepth: 2 + + quickstart + update + update-sources + list-sources + enable-source + disable-source + remove-source + add-source + check-versions diff --git a/doc/list-sources.rst b/doc/list-sources.rst new file mode 100644 index 0000000..f4b36eb --- /dev/null +++ b/doc/list-sources.rst @@ -0,0 +1,28 @@ +######################################## +list-sources - List available sources +######################################## + +Synopsis +======== + +:: + + suricata-update list-sources + +Description +=========== + +The ``list-sources`` command lists all the available sources. + +Options +======= + +.. include:: common-options.rst + +.. option:: --free + + List all freely available sources. + +.. option:: --enabled + + Lists all the enabled sources. diff --git a/doc/quickstart.rst b/doc/quickstart.rst new file mode 100644 index 0000000..bf57de5 --- /dev/null +++ b/doc/quickstart.rst @@ -0,0 +1,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. + diff --git a/doc/remove-source.rst b/doc/remove-source.rst new file mode 100644 index 0000000..f8e3135 --- /dev/null +++ b/doc/remove-source.rst @@ -0,0 +1,21 @@ +########################################## +remove-source - Remove a configured source +########################################## + +Synopsis +======== + +:: + + suricata-update remove-source <name> + +Description +=========== + +Remove a source configuration. This removes the source file from +``/var/lib/suricata/update/sources``, even if its disabled. + +Options +======= + +.. include:: ./common-options.rst diff --git a/doc/update-sources.rst b/doc/update-sources.rst new file mode 100644 index 0000000..ade1246 --- /dev/null +++ b/doc/update-sources.rst @@ -0,0 +1,40 @@ +######################################## +update-sources - Update the source index +######################################## + +Synopsis +======== + +:: + + suricata-update update-sources + +Description +=========== + +The ``update-sources`` command downloads the latest index of available +sources. + +Options +======= + +.. include:: common-options.rst + +Files and Directories +===================== + +``/var/lib/suricata/rules/.cache/index.yaml`` + Where the downloaded source index is cached. + +Environment Variables +===================== + +**SOURCE_INDEX_URL** + This environment variable allows the specification of an alternate + URL to download the index from. + +URLs +==== + +``https://www.openinfosecfoundation.org/rules/index.yaml`` + The default URL used to download the index from. diff --git a/doc/update.rst b/doc/update.rst new file mode 100644 index 0000000..c3db62e --- /dev/null +++ b/doc/update.rst @@ -0,0 +1,324 @@ +######################## +suricata-update - Update +######################## + +Synopsis +======== + +``suricata-update`` [OPTIONS] + +Description +=========== + +``suricata-update`` aims to be a simple to use rule download and +management tool for Suricata. + +Options +======= + +.. include:: ./common-options.rst + +.. option:: -o, --output + + The directory to output the rules to. + + Default: */var/lib/suricata/rules* + +.. option:: --force + + Force remote rule files to be downloaded if they otherwise wouldn't + be due to just recently downloaded, or the remote checksum matching + the cached copy. + +.. option:: --no-merge + + Do not merge the rules into a single rule file. + + *Warning: No attempt is made to resolve conflicts if 2 input rule files have the same name.* + +.. option:: --yaml-fragment=<filename.yaml> + + Output a fragment of YAML containing the *rule-files* section will + all downloaded rule files listed for inclusion in your + *suricata.yaml*. + +.. option:: --url=<url> + + A URL to download rules from. This option can be used multiple + times. + +.. option:: --local=<filename or directory> + + A path to a filename or directory of local rule files to include. + + If the path is a directory all files ending in *.rules* will be + loaded. + + Wildcards are accepted but to avoid shell expansion the argument + must be quoted, for example:: + + --local '/etc/suricata/custom-*.rules' + + This option can be specified multiple times. + +.. option:: --sid-msg-map=<filename> + + Output a v1 style sid-msg.map file. + +.. option:: --sid-msg-map-2=<filename> + + Output a v2 style sid-msg.map file. + +.. option:: --disable-conf=<disable.conf> + + Specify the configuration file for disable filters. + + See :ref:`example-disable-conf` + +.. option:: --enable-conf=<enable.conf> + + Specify the configuration file for enable rules. + + See :ref:`example-enable-conf` + +.. option:: --modify-conf=<modify.conf> + + Specify the configuration file for rule modification filters. + + See :ref:`example-modify-conf` + +.. option:: --drop-conf=<drop.conf> + + Specify the configuration file for drop filters. + + See :ref:`example-drop-conf` + +.. option:: --ignore=<pattern> + + Filenames to ignore. This is a pattern that will be matched against + the basename of a rule files. + + This argument may be specified multiple times. + + Default: *\*deleted.rules* + + Example:: + + --ignore dnp3-events.rules --ignore deleted.rules --ignore "modbus*" + + .. note:: + + If specified the default value of *\*deleted.rules* will no longer + be used, so add it as an extra ignore if needed. + +.. option:: --no-ignore + + Disable the --ignore option. Most useful to disable the default + ignore pattern without adding others. + +.. option:: --etopen + + Download the ET/Open ruleset. + + This is the default action of no ``--url`` options are provided or + no sources are configured. + + Use this option to enable the ET/Open ruleset in addition to any + URLs provided on the command line or sources provided in the + configuration. + +.. option:: --dump-sample-configs + + Output sample configuration files for the ``--disable``, + ``--enable``, ``--modify`` and ``--threshold-in`` commands. + +.. option:: --threshold-in=<threshold.conf.in> + + Specify the threshold.conf input template. + +.. option:: --threshold-out=<threshold.conf> + + Specify the name of the processed threshold.conf to output. + +.. option:: -T <command>, --test-command <command> + + Specifies a custom test command to test the rules before reloading + Suricata. This overrides the default command and can also be + specified in the configuration file under ``test-command``. + +.. option:: --no-test + + Disables the test command and proceed as if it had passed. + +.. option:: --reload-command=<command> + + A command to run after the rules have been updated; will not run if + no change to the output files was made. For example:: + + --reload-command='sudo kill -USR2 $(pidof suricata)' + + will tell Suricata to reload its rules. + + Furthermore the reload can be triggered using the Unix socket of Suricata. + + Blocking reload (with Suricata waiting for the reload to finish):: + + --reload-command='sudo suricatasc -c reload-rules' + + Non blocking reload (without restarting Suricata):: + + --reload-command='sudo suricatasc -c ruleset-reload-nonblocking' + + See the Suricata documentation on `Rule Reloads + <https://suricata.readthedocs.io/en/latest/rule-management/rule-reload.html>`_ + for more information. + +.. option:: --no-reload + + Disable Suricata rule reload. + +.. option:: -V, --version + + Display the version of **suricata-update**. + +.. option:: --offline + + Run offline using most recent cached rules. + +Rule Matching +============= + +Matching rules for disabling, enabling, converting to drop or +modification can be done with the following: + +- signature ID +- regular expression +- rule group +- filename + +Signature ID Matching +--------------------- + +A signature ID can be matched by just its signature ID, for example:: + + 1034 + +The generator ID can also be used for compatibility with other tools:: + + 1:1034 + +Regular Expression Matching +--------------------------- + +Regular expression matching will match a regular expression over the +complete rule. Example:: + + re:heartbleed + re:MS(0[7-9]|10)-\d+ + +Group Matching +-------------- + +The group matcher matches against the group the rule was loaded +from. Basically this is the filename without the leading path or file +extension. Example:: + + group:emerging-icmp.rules + group:emerging-dos + +Wild card matching similar to wildcards used in a Unix shell can also +be used:: + + group:*deleted* + +Filename Matching +----------------- + +The filename matcher matches against the filename the rule was loaded +from taking into consideration the full path. Shell wildcard patterns +are allowed:: + + filename:rules/*deleted* + filename:*/emerging-dos.rules + +Metadata Matching +----------------- + +Rules can be enabled or disabled based on the metadata fields +contained in the rule, for example:: + + metadata: deployment perimeter + +Will match rules that have a metadata field of "deployment" with the +value of "perimeter" (case insensitive). This will match on a rule +with the provided metadata:: + + metadata:affected_product Any, attack_target Any, deployment Perimeter + +.. note:: Metadata matching can only be used to enable, disable or + convert rules to drop. It is not available for rule + modification. + +Modifying Rules +--------------- + +Rule modification can be done with regular expression search and +replace. The basic format for a rule modification specifier is:: + + <match> <from> <to> + +where <match> is one of the rule matchers from above, <from> is the +text to be replaced and <to> is the replacement text. + +Example converting all alert rules to drop:: + + re:. ^alert drop + +Example converting all drop rules with noalert back to alert:: + + re:. "^drop(.*)noalert(.*)" "alert\\1noalert\\2" + +Order of application of configuration files +=========================================== +1. disable.conf +2. enable.conf +3. drop.conf +4. modify.conf + +Example Configuration Files +=========================== + +.. _example_update_yaml: + +Example Configuration File (/etc/suricata/update.yaml) +------------------------------------------------------ + +.. literalinclude:: ../suricata/update/configs/update.yaml + +.. _example-enable-conf: + +Example Configuration to Enable Rules (--enable-conf) +----------------------------------------------------- + +.. literalinclude:: ../suricata/update/configs/enable.conf + +.. _example-disable-conf: + +Example Configuration to Disable Rules (--disable-conf) +-------------------------------------------------------- + +.. literalinclude:: ../suricata/update/configs/disable.conf + +.. _example-drop-conf: + +Example Configuration to convert Rules to Drop (--drop-conf) +------------------------------------------------------------ + +.. literalinclude:: ../suricata/update/configs/drop.conf + +.. _example-modify-conf: + +Example Configuration to modify Rules (--modify-conf) +----------------------------------------------------- + +.. literalinclude:: ../suricata/update/configs/modify.conf |