Skip to content

Commit

Permalink
Add Maltiverse integration documentation and reference
Browse files Browse the repository at this point in the history
  • Loading branch information
@fdalmaup
fdalmaup committed Jul 20, 2023
1 parent fe4cab2 commit 8d456fe
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 24 deletions.
Binary file added source/images/manual/integration/maltiverse.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
43 changes: 39 additions & 4 deletions source/user-manual/manager/manual-integration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
Integration with external APIs
==============================

The *Integrator* daemon allows Wazuh to connect to external APIs and alerting tools such as Slack, PagerDuty, VirusTotal, and Shuffle.
The *Integrator* daemon allows Wazuh to connect to external APIs and alerting tools such as Slack, PagerDuty, VirusTotal, Shuffle and Maltiverse.

Configuration
-------------
Expand All @@ -19,9 +19,9 @@ The integrations are configured on the Wazuh manager ``ossec.conf`` file. You ca
<integration>
<name> </name>
<hook_url> </hook_url> <!-- Required for Slack and Shuffle -->
<api_key> </api_key> <!-- Required for PagerDuty and VirusTotal -->
<alert_format>json</alert_format> <!-- Required for Slack, VirusTotal and Shuffle -->
<hook_url> </hook_url> <!-- Required for Slack, Shuffle and Maltiverse -->
<api_key> </api_key> <!-- Required for PagerDuty, VirusTotal and Maltiverse -->
<alert_format>json</alert_format> <!-- Required for Slack, VirusTotal, Shuffle and Maltiverse -->
<!-- Optional filters -->
<rule_id> </rule_id>
Expand Down Expand Up @@ -179,6 +179,41 @@ Once the configuration is complete, alerts start showing in the email inbox.
:align: center
:width: 80%

Maltiverse
----------

`Maltiverse <https://whatis.maltiverse.com/>`__ is an open and collaborative platform for indexing and searching Indicators of Compromise (IoCs) which works as a broker for Threat intelligence sources that are aggregated from more than a hundred different Public, Private and Community sources. This integration enriches any alert generated by Wazuh via the Maltiverse API, inserting new fields in case of match and following the threat taxonomy of the ECS standard (Elastic Common Squema).

To set up this integration, do the following.

#. Get your API key from the `Maltiverse <https://www.maltiverse.com>`__ page.

#. Edit ``/var/ossec/etc/ossec.conf`` in the Wazuh server and include a configuration block such as the following. Replace ``MALTIVERSE_AUTH_TOKEN`` with your Maltiverse Authentication Token. The rule level filter is optional. You can remove it or set another level value for the integration.

.. code-block:: xml
:emphasize-lines: 3
<integration>
<name>custom-maltiverse</name>
<hook_url>https://api.maltiverse.com</hook_url>
<level>3</level>
<api_key>MALTIVERSE_AUTH_TOKEN</api_key>
<alert_format>json</alert_format>
</integration>
#. Restart the Wazuh manager to apply the changes.

.. include:: /_templates/common/restart_manager.rst

Once the configuration is complete, if any alerts contain fields matching any IoC, these will be enriched and displayed in the Wazuh Dashboard.

.. thumbnail:: /images/manual/integration/maltiverse.png
:title: Maltiverse alert
:alt: Maltiverse alert
:align: center
:width: 80%


Custom integration
------------------

Expand Down
48 changes: 28 additions & 20 deletions source/user-manual/reference/ossec-conf/integration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ integration
<integration>
</integration>
This configures the manager to :ref:`connect Wazuh to external APIs <manual_integration>` and alerting tools such as Slack, PagerDuty, VirusTotal and Shuffle.
This configures the manager to :ref:`connect Wazuh to external APIs <manual_integration>` and alerting tools such as Slack, PagerDuty, VirusTotal, Shuffle and Maltiverse.

Options
-------
Expand All @@ -35,36 +35,36 @@ name

This indicates the service to integrate with.

+--------------------+------------------------------------------------------------------------------+
| **Default value** | n/a |
+--------------------+------------------------------------------------------------------------------+
| **Allowed values** | slack, pagerduty, virustotal, shuffle, any string that begins with 'custom-' |
+--------------------+------------------------------------------------------------------------------+
+--------------------+------------------------------------------------------------------------------------------+
| **Default value** | n/a |
+--------------------+------------------------------------------------------------------------------------------+
| **Allowed values** | slack, pagerduty, virustotal, shuffle, maltiverse, any string that begins with 'custom-' |
+--------------------+------------------------------------------------------------------------------------------+

.. note::
In the case of custom external integration, name must begin with ``custom-`` for example: ``custom-myintegration``. Read the `How to integrate external software using Integrator <https://wazuh.com/blog/how-to-integrate-external-software-using-integrator//>`_ document for more information.

hook_url
^^^^^^^^

This is the URL that is used for communication with the software being integrated. It's mandatory for the `Slack` and `Shuffle` integrations.
This is the URL that is used for communication with the software being integrated. It's mandatory for the `Slack`, `Shuffle` and `Maltiverse` integrations.

+--------------------+------------------------+
| **Default value** | n/a |
+--------------------+------------------------+
| **Allowed values** | Slack URL, Shuffle URL |
+--------------------+------------------------+
+--------------------+----------------------------------------+
| **Default value** | n/a |
+--------------------+----------------------------------------+
| **Allowed values** | Slack URL, Shuffle URL, Maltiverse URL |
+--------------------+----------------------------------------+

api_key
^^^^^^^

This is the key that you would have retrieved from the PagerDuty or VirusTotal API. This is **mandatory for PagerDuty and VirusTotal.**
This is the key that you would have retrieved from the PagerDuty, VirusTotal or Maltiverse API. This is **mandatory for PagerDuty, VirusTotal and Maltiverse.**

+--------------------+------------------------------+
| **Default value** | n/a |
+--------------------+------------------------------+
| **Allowed values** | PagerDuty/VirusTotal Api key |
+--------------------+------------------------------+
+--------------------+-----------------------------------------+
| **Default value** | n/a |
+--------------------+-----------------------------------------+
| **Allowed values** | PagerDuty/VirusTotal/Maltiverse Api key |
+--------------------+-----------------------------------------+

Optional filters
----------------
Expand Down Expand Up @@ -116,15 +116,15 @@ This filters alerts by where the event originated.
alert_format
^^^^^^^^^^^^

This writes the alert file in the JSON format. The Integrator makes use this file to fetch fields values.
This writes the alert file in the JSON format. The Integrator makes use of this file to fetch fields values.

+--------------------+-----------------------------------------------------------+
| **Default value** | n/a |
+--------------------+-----------------------------------------------------------+
| **Allowed values** | json |
+--------------------+-----------------------------------------------------------+

.. note:: This option must be set to ``json`` for Slack, VirusTotal and Shuffle integrations.
.. note:: This option must be set to ``json`` for Slack, VirusTotal, Shuffle and Maltiverse integrations.

max_log
^^^^^^^
Expand Down Expand Up @@ -175,6 +175,14 @@ Configuration example
<alert_format>json</alert_format>
</integration>
<!-- Integration with Maltiverse -->
<integration>
<name>maltiverse</name>
<hook_url>https://api.maltiverse.com</hook_url>
<api_key>maltiverse-auth-token</api_key>
<alert_format>json</alert_format>
</integration>
<!--Custom external Integration -->
<integration>
<name>custom-integration</name>
Expand Down

0 comments on commit 8d456fe

Please sign in to comment.