DOC: n6: add more illustrations

add two n6 images directly to the repository, as they are not displayed
on readthedocs otherwise: The other websites hosting the images block
loading images if the referer does not match a whitelist. we can't add a
noreferer HTML attribute in rst as well. the option left is to add the
files, that only implies adding the licensing information and the
AGPL-3.0 license text as well.

add two illustrations on the the flow n6 to intelmq and vice versa, own
work.

some textual improvements in the document itself.

.reuse/dep5

@@ -29,3 +29,7 @@ License:   AGPL-3.0-or-later
 Files:     debian/debian/py3dist-overrides
 Copyright: 2021 Birger Schacht
 License:   AGPL-3.0-or-later
+
+Files:     docs/_static/n6/data-flow.png docs/_static/n6/n6-schemat2.png
+Copyright: CERT.pl <[email protected]>
+License:   AGPL-3.0-only

CHANGELOG.md

@@ -126,6 +126,7 @@ Update allowed classification fields to 2020-01-28 version (#1409, #1476).
 - License and copyright information was added to all the bots.
 - Added documentation on the EventDB (PR#1955 by Birger Schacht, PR#1985 by Sebastian Wagner).
 - Added TimescaleDB for time-series documentation (PR#1990 by Sebastian Waldbauer).
+- Improved n6 interoperability documentation by adding more graphs and illustrations (PR#1991 by Sebastian Wagner).
 
 ### Packaging
 - Docker images tagged with `certat/intelmq-full:develop` are built and published on every push to the develop branch (PR#1753 by Sebastian Waldbauer).

docs/_static/n6/data-flow.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2021 CERT.pl <[email protected]>
+SPDX-License-Identifier: AGPL-3.0-only

docs/_static/n6/intelmq-to-n6.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2021 Sebastian Wagner <[email protected]>
+SPDX-License-Identifier: CC0-1.0

docs/_static/n6/intelmq-to-n6.svg.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2021 Sebastian Wagner <[email protected]>
+SPDX-License-Identifier: CC0-1.0

docs/_static/n6/n6-schemat2.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2021 CERT.pl <[email protected]>
+SPDX-License-Identifier: AGPL-3.0-only

docs/_static/n6/n6-to-intelmq.png.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2021 Sebastian Wagner <[email protected]>
+SPDX-License-Identifier: CC0-1.0

docs/_static/n6/n6-to-intelmq.svg.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2021 Sebastian Wagner <[email protected]>
+SPDX-License-Identifier: CC0-1.0

docs/user/bots.rst

@@ -1490,6 +1490,8 @@ defined in the `SUPPORTED_MISP_CATEGORIES` and `MISP_TYPE_MAPPING` class
 constants.
 
 
+.. _n6 parser bot:
+
 .. _intelmq.bots.parsers.n6.parser_n6stomp:
 
 n6
@@ -3819,6 +3821,7 @@ Create the new database (you can ignore all errors since SQLite doesn't know all
 
 Then, set the `database` parameter to the `your-db.db` file path.
 
+.. _stomp output bot:
 
 .. _intelmq.bots.outputs.stomp.output:
 

docs/user/n6-integrations.rst

@@ -1,32 +1,40 @@
 ..
-   SPDX-FileCopyrightText: 2020 Sebastian Wagner
+   SPDX-FileCopyrightText: 2020-2021 Sebastian Wagner <[email protected]>
    SPDX-License-Identifier: AGPL-3.0-or-later
 
 IntelMQ - n6 Integration
 ========================
 
-n6 is an Open Source Tool with very similar aims as IntelMQ, processing and distributing IoC data, developed by CERT.pl.
-The covered use-cases differ and both tools have non-overlapping strengths.
+n6 is an Open Source Tool with very similar aims as IntelMQ: processing and distributing IoC data.
+The use-cases, architecture and features differ and both tools have non-overlapping strengths.
+n6 is maintained and developed by `CERT.pl <https://www.cert.pl/>`_.
 
 Information about n6 can be found here:
-- Website: https://n6.cert.pl/en/
-- Development: https://github.com/CERT-Polska/n6/
 
-.. figure:: https://n6.cert.pl/n6-schemat2.png
+- Website: `n6.cert.pl <https://n6.cert.pl/en/>`_
+- Source Code: `github.com/CERT-Polska/n6 <https://github.com/CERT-Polska/n6/>`_
+- n6 documentation: `n6.readthedocs.io <https://n6.readthedocs.io/>`_
+- n6sdk developer documentation: `n6sdk.readthedocs.io <https://n6sdk.readthedocs.io/>`_
+
+.. image:: /_static/n6/n6-schemat2.png
    :alt: n6 schema
 
+.. image:: /_static/n6/data-flow.png
+   :alt: n6 data flow
+
 Data format
 -------------------------------
 
-The internal data representation differs for the systems, so any data exchanged between the systems needs to be converted.
-As n6 can save multiple IP addresses per event, which IntelMQ is unable to do, one n6 event results in one or more IntelMQ events.
-Thus and because of some other reasons, the conversion is *not* bidirectional.
+The internal data representation differs between IntelMQ and n6, so any data exchange between the systems requires a format conversion.
+For example, in n6 one message can contain multiple IP addresses, but IntelMQ is intentionally restricted to one IP address per message.
+Therefore, one n6 event results in *one or more* IntelMQ events.
+Because of this, and some other naming differences and ambiguities, the format conversion is *not* bidirectional.
 
 Data exchange interface
 -------------------------------
 
 n6 offers a STOMP interface via the RabbitMQ broker, which can be used for both sending and receiving data.
-IntelMQ has both a STOMP collector bot as well as a STOMP output bot.
+IntelMQ offers both a STOMP collector bot for receiving data from n6, as well as a STOMP output bot for sending data to n6 instances.
 
 - :ref:`IntelMQ's Stomp collector bot <stomp collector bot>`
 - :ref:`IntelMQ's n6 parser bot <n6 parser bot>`
@@ -39,9 +47,31 @@ IntelMQ can parse n6 data using the n6 parser and n6 can parse IntelMQ data usin
 
 - :ref:`IntelMQ's n6 parser bot <n6 parser bot>`
 
+Complete example
+----------------
+
+Data flow n6 to IntelMQ
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: /_static/n6/n6-to-intelmq.png
+   :alt: dataflow from n6 to IntelMQ
+
+Data flow IntelMQ to n6
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: /_static/n6/intelmq-to-n6.png
+   :alt: dataflow from IntelMQ to n6
+
+CERT.pl Data feed
+^^^^^^^^^^^^^^^^^
+
+CERT.pl offers data feed available to their partners through the STOMP interface.
+Our feeds documentation contains details how it can be enabled in IntelMQ: `CERT.pl n6 STOMP stream <feeds.html#n6-stomp-stream>`_
+
+
 Webinput CSV
 -------------------------------
 
 The IntelMQ Webinput CSV software can also be used together with n6.
-The documentation can be found in the software's repository:
+The documentation on this component can be found in the software's repository:
 https://github.com/certat/intelmq-webinput-csv/blob/master/docs/webinput-n6.md