|
| 1 | +.. |
| 2 | + SPDX-FileCopyrightText: 2023 Bundesamt für Sicherheit in der Informationstechnik (BSI) |
| 3 | + SPDX-License-Identifier: AGPL-3.0-or-later |
| 4 | +
|
| 5 | +########################## |
| 6 | +Running IntelMQ as Library |
| 7 | +########################## |
| 8 | + |
| 9 | +.. contents:: |
| 10 | + |
| 11 | +************ |
| 12 | +Introduction |
| 13 | +************ |
| 14 | + |
| 15 | +The feature is specified in `IEP007 <https://github.com/certtools/ieps/tree/iep-007/007/>`_. |
| 16 | + |
| 17 | +********** |
| 18 | +Quickstart |
| 19 | +********** |
| 20 | + |
| 21 | +First, import the Python module and a helper. More about the ``BotLibSettings`` later. |
| 22 | + |
| 23 | +.. code-block:: python |
| 24 | +
|
| 25 | + from intelmq.lib.bot import BotLibSettings |
| 26 | + from intelmq.bots.experts.domain_suffix.expert import DomainSuffixExpertBot |
| 27 | +
|
| 28 | +Then we need to initialize the bot's instance. |
| 29 | +We pass two parameters: |
| 30 | +* ``bot_id``: The id of the bot |
| 31 | +* ``settings``: A Python dictionary of runtime configuration parameters, see :ref:`runtime-configuration`. |
| 32 | + The bot first loads the runtime configuration file if it exists. |
| 33 | + Then we update them with the ``BotLibSettings`` which are some accumulated settings disabling the logging to files and configure the pipeline so that we can send and receive messages directly to/from the bot. |
| 34 | + Last by not least, the actual bot parameters, taking the highest priority. |
| 35 | + |
| 36 | +.. code-block:: python |
| 37 | +
|
| 38 | + domain_suffix = DomainSuffixExpertBot('domain-suffix', # bot id |
| 39 | + settings=BotLibSettings | { |
| 40 | + 'field': 'fqdn', |
| 41 | + 'suffix_file': '/usr/share/publicsuffix/public_suffix_list.dat'} |
| 42 | +
|
| 43 | +As the bot is not fully initialized, we can process messages now. |
| 44 | +Inserting a message as dictionary: |
| 45 | +
|
| 46 | +.. code-block:: python |
| 47 | +
|
| 48 | + queues = domain_suffix.process_message({'source.fqdn': 'www.example.com'}) |
| 49 | +
|
| 50 | +The return value is a dictionary of queues, e.g. the output queue and the error queue. |
| 51 | +More details below. |
| 52 | +
|
| 53 | +The methods accepts multiple messages as positional argument: |
| 54 | +
|
| 55 | +.. code-block:: python |
| 56 | +
|
| 57 | + domain_suffix.process_message({'source.fqdn': 'www.example.com'}, {'source.fqdn': 'www.example.net'}) |
| 58 | + domain_suffix.process_message(*[{'source.fqdn': 'www.example.com'}, {'source.fqdn': 'www.example.net'}]) |
| 59 | +
|
| 60 | +
|
| 61 | +Select the output queue (as defined in `destination_queues`), first message, access the field 'source.domain_suffix': |
| 62 | +
|
| 63 | +.. code-block:: python |
| 64 | +
|
| 65 | + >>> output['output'][0]['source.domain_suffix'] |
| 66 | + 'com' |
| 67 | +
|
| 68 | +************* |
| 69 | +Configuration |
| 70 | +************* |
| 71 | +
|
| 72 | +Configuration files are not required to run IntelMQ as library. |
| 73 | +Contrary to IntelMQ normal behavior, if the files ``runtime.yaml`` and ``harmonization.conf`` do not exist, IntelMQ won't raise any errors. |
| 74 | +For the harmonization configuration, internal defaults are loaded. |
0 commit comments