doc: add/update/improve stuff related to STOMP bots and *n6*

The changes include also those regarding *feeds* (values of certain
properties of the CERT.PL's "N6 Stomp Stream" feed entry have been
updated/improved) and the *changelog*.

CHANGELOG.md

@@ -11,26 +11,67 @@ CHANGELOG
 ------------------
 
 ### Configuration
+- Add new optional configuration parameters for `intelmq.bots.collectors.stomp.collector`
+  and `intelmq.bots.outputs.stomp.output` (PR#2408 by Jan Kaliszewski):
+  - `auth_by_ssl_client_certificate` (Boolean, default: *true*; if *false* then
+    `ssl_client_certificate` and `ssl_client_certificate_key` will be ignored);
+  - `username` (STOMP authentication login, default: "guest"; to be used only
+    if `auth_by_ssl_client_certificate` is *false*);
+  - `password` (STOMP authentication passcode, default: "guest"; to be used only
+    if `auth_by_ssl_client_certificate` is *false*).
 
 ### Core
 - `intelmq.lib.message`: For invalid message keys, add a hint on the failure to the exception: not allowed by configuration or not matching regular expression (PR#2398 by Sebastian Wagner).
 - `intelmq.lib.exceptions.InvalidKey`: Add optional parameter `additional_text` (PR#2398 by Sebastian Wagner).
+- `intelmq.lib.mixins`: Add a new class, `StompMixin` (defined in a new submodule: `stomp`),
+  which provides certain common STOMP-bot-specific operations, factored out from
+  `intelmq.bots.collectors.stomp.collector` and `intelmq.bots.outputs.stomp.output`
+  (PR#2408 by Jan Kaliszewski).
 
 ### Development
 
 ### Data Format
 
 ### Bots
 #### Collectors
+- `intelmq.bots.collectors.stomp.collector` (PR#2408 by Jan Kaliszewski):
+  - Add support for authentication based on STOMP login and passcode,
+    introducing 3 new configuration parameters (see above: *Configuration*).
+  - Update the code to support new versions of `stomp.py`, including the latest (`8.1.0`);
+    fixes [#2342](https://github.com/certtools/intelmq/issues/2342).
+  - Fix the reconnection behavior: do not attempt to reconnect after `shutdown`. Also,
+    never attempt to reconnect if the version of `stomp.py` is older than `4.1.21` (it
+    did not work properly anyway).
+  - Add coercion of the `port` config parameter to `int`.
+  - Add implementation of the `check` hook (verifying, in particular, accessibility
+    of necessary file(s)).
+  - Remove undocumented and unused attributes of `StompCollectorBot` instances:
+    `ssl_ca_cert`, `ssl_cl_cert`, `ssl_cl_cert_key`.
+  - Minor fixes/improvements and some refactoring (see also above: *Core*...).
 
 #### Parsers
 
 #### Experts
 
 #### Outputs
+- `intelmq.bots.outputs.stomp.output` (PR#2408 by Jan Kaliszewski):
+  - Add support for authentication based on STOMP login and passcode,
+    introducing 3 new configuration parameters (see above: *Configuration*).
+  - Update the code to support new versions of `stomp.py`, including the latest (`8.1.0`).
+  - Add coercion of the `port` config parameter to `int`.
+  - Add implementation of the `check` hook (verifying, in particular, accessibility
+    of necessary file(s)).
+  - Add `stomp.py` version check (raise `MissingDependencyError` if not `>=4.1.8`).
+  - Fix a hang, occurring for `stomp.py` in versions older than `4.1.20`, caused by
+    a missing invocation of the connection's `start` method.
+  - Fix `AttributeError` caused by attempts to get unset attributes (`ssl_ca_cert`
+    et consortes).
+  - Minor fixes/improvements and some refactoring (see also above: *Core*...).
 
 ### Documentation
 - Add a readthedocs configuration file to fix the build fail (PR#2403 by Sebastian Wagner).
+- Update/fix/improve the stuff related to the STOMP bots and integration with the *n6*'s
+  Stream API (PR#2408 by Jan Kaliszewski).
 
 ### Packaging
 

docs/user/bots.rst

@@ -945,12 +945,15 @@ Install the `stomp.py` library from PyPI:
 **Configuration Parameters**
 
 * **Feed parameters** (see above)
-* `exchange`: exchange point
+* `exchange`: STOMP *destination* to subscribe to, e.g. "/exchange/my.org/*.*.*.*"
 * `port`: 61614
-* `server`: hostname e.g. "n6stream.cert.pl"
+* `server`: hostname, e.g. "n6stream.cert.pl"
 * `ssl_ca_certificate`: path to CA file
-* `ssl_client_certificate`: path to client cert file
-* `ssl_client_certificate_key`: path to client cert key file
+* `auth_by_ssl_client_certificate`: Boolean, default: true (note: set to false for new *n6* auth)
+* `ssl_client_certificate`: path to client cert file, used only if `auth_by_ssl_client_certificate` is true
+* `ssl_client_certificate_key`: path to client cert key file, used only if `auth_by_ssl_client_certificate` is true
+* `username`: STOMP *login* (e.g., *n6* user login), used only if `auth_by_ssl_client_certificate` is false
+* `password`: STOMP *passcode* (e.g., *n6* user API key), used only if `auth_by_ssl_client_certificate` is false
 
 
 .. _intelmq.bots.collectors.twitter.collector_twitter:
@@ -4305,7 +4308,7 @@ Also you will need a so called "exchange point".
 
 **Configuration Parameters**
 
-* `exchange`: The exchange to push at
+* `exchange`: STOMP *destination* to push at, e.g. "/exchange/_push"
 * `heartbeat`: default: 60000
 * `message_hierarchical_output`: Boolean, default: false
 * `message_jsondict_as_string`: Boolean, default: false
@@ -4314,8 +4317,11 @@ Also you will need a so called "exchange point".
 * `server`: Host or IP address of the STOMP server
 * `single_key`: Boolean or string (field name), default: false
 * `ssl_ca_certificate`: path to CA file
-* `ssl_client_certificate`: path to client cert file
-* `ssl_client_certificate_key`: path to client cert key file
+* `auth_by_ssl_client_certificate`: Boolean, default: true (note: set to false for new *n6* auth)
+* `ssl_client_certificate`: path to client cert file, used only if `auth_by_ssl_client_certificate` is true
+* `ssl_client_certificate_key`: path to client cert key file, used only if `auth_by_ssl_client_certificate` is true
+* `username`: STOMP *login* (e.g., *n6* user login), used only if `auth_by_ssl_client_certificate` is false
+* `password`: STOMP *passcode* (e.g., *n6* user API key), used only if `auth_by_ssl_client_certificate` is false
 
 
 .. _intelmq.bots.outputs.tcp.output:

docs/user/n6-integrations.rst

@@ -11,10 +11,9 @@ n6 is maintained and developed by `CERT.pl <https://www.cert.pl/>`_.
 
 Information about n6 can be found here:
 
-- Website: `n6.cert.pl <https://n6.cert.pl/en/>`_
+- Website: `cert.pl/en/n6 <https://cert.pl/en/n6/>`_
 - 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

intelmq/etc/feeds.yaml

@@ -1158,20 +1158,19 @@ providers:
           module: intelmq.bots.collectors.stomp.collector
           parameters:
             exchange: "{insert your exchange point as given by CERT.pl}"
-            ssl_client_certificate_key: "{insert path to client cert key file for
-              CERT.pl's n6}"
             ssl_ca_certificate: "{insert path to CA file for CERT.pl's n6}"
+            auth_by_ssl_client_certificate: false
+            username: "{insert n6 user's login}"
+            password: "{insert n6 user's API key}"
             port: '61614'
-            ssl_client_certificate: "{insert path to client cert file for CERTpl's
-              n6}"
             server: n6stream.cert.pl
             name: __FEED__
             provider: __PROVIDER__
         parser:
           module: intelmq.bots.parsers.n6.parser_n6stomp
           parameters:
-      revision: 2018-01-20
-      documentation: https://n6.cert.pl/en/
+      revision: 2023-09-23
+      documentation: https://n6.readthedocs.io/usage/streamapi/
       public: false
   AlienVault:
     OTX: