Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Options section for integrations. #5962

Merged
merged 9 commits into from
Sep 4, 2023
Merged

Options section for integrations. #5962

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
5fa83f6
Add: Options section for integrations.
GabrielEValenzuela Mar 8, 2023
75cf40c
Fix: Some API Url
GabrielEValenzuela Mar 8, 2023
5e2fd51
Add: Shuffle API reference
GabrielEValenzuela Mar 13, 2023
00a62a0
Del: Reference Virustotal API
GabrielEValenzuela Mar 27, 2023
d3dd070
Add example of configuration in integration.rst.
GabrielEValenzuela Aug 29, 2023
c41fae8
Add missing example in custom integration.
GabrielEValenzuela Aug 29, 2023
557157e
Add review changes
javimed Aug 30, 2023
3490f11
Add json format requirement for PagerDuty
javimed Sep 1, 2023
67e3ea7
Merge branch '4.7.0' into 5927_custom_notification
javimed Sep 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion source/user-manual/manager/manual-integration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,14 @@ The integrations are configured on the Wazuh manager ``ossec.conf`` file. You ca
<name> </name>
<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 -->
<alert_format>json</alert_format> <!-- Required for Slack, PagerDuty, VirusTotal, Shuffle, and Maltiverse -->

<!-- Optional filters -->
<rule_id> </rule_id>
<level> </level>
<group> </group>
<event_location> </event_location>
<options> </options>
</integration>


Expand Down Expand Up @@ -71,6 +72,10 @@ To set up this integration, follow these steps.
<alert_format>json</alert_format>
</integration>

.. note::

You can set a JSON object with customization fields using the :ref:`options <integration_options_tag>` tag. Visit the `Slack API reference <https://api.slack.com/reference/messaging/attachments#legacy_fields>`__ for information about available customization fields.

#. Restart the Wazuh manager to apply the changes.

.. include:: /_templates/common/restart_manager.rst
Expand Down Expand Up @@ -101,8 +106,13 @@ To set up this integration, do the following.
<name>pagerduty</name>
<api_key>API_KEY</api_key> <!-- Replace with your PagerDuty API key -->
<level>10</level>
<alert_format>json</alert_format> <!-- New mandatory parameter since v4.7.0 -->
</integration>

.. note::

You can set a JSON object with customization fields using the :ref:`options <integration_options_tag>` tag. Visit the `PagerDuty API reference <https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgx-send-an-alert-event>`__ for information about available customization fields.

#. Restart the Wazuh manager to apply the changes.

.. include:: /_templates/common/restart_manager.rst
Expand Down Expand Up @@ -167,6 +177,10 @@ To set up this integration, do the following.
<alert_format>json</alert_format>
</integration>

.. note::

You can set a JSON object with customization fields using the :ref:`options <integration_options_tag>` tag. Visit the `Shuffle API reference <https://shuffler.io/docs/API>`__ for information about available customization fields.

#. Restart the Wazuh manager to apply the changes.

.. include:: /_templates/common/restart_manager.rst
Expand Down Expand Up @@ -233,4 +247,5 @@ Below, you can find an example of a configuration block in the ``ossec.conf`` fi
<group>multiple_drops,authentication_failures</group>
<api_key>APIKEY</api_key> <!-- Replace with your external service API key -->
<alert_format>json</alert_format>
<options>{"data": "Custom data"}</options> <!-- Replace with your custom JSON object -->
</integration>
38 changes: 23 additions & 15 deletions source/user-manual/reference/ossec-conf/integration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.. Copyright (C) 2015, Wazuh, Inc.

.. meta::
:description: Learn how to configure the manager to connect Wazuh to external APIs. Check out the options, optional filters, and configuration examples.
:description: Learn how to configure the manager to connect Wazuh to external APIs. Check out the options, optional filters, and configuration examples.

.. _reference_ossec_integration:

integration
Expand All @@ -17,18 +17,8 @@ integration

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
-------

- `name`_
- `hook_url`_
- `api_key`_
- `level`_
- `rule_id`_
- `group`_
- `event_location`_
- `alert_format`_
- `max_log`_
Integration options
-------------------

name
^^^^
Expand Down Expand Up @@ -139,6 +129,19 @@ The maximum length of an alert snippet that will be sent to the Integrator. Lon

.. note:: This option only applies if ``alert_format`` is not set to ``json``.

.. _integration_options_tag:

options
^^^^^^^

This overwrites the previous fields or adds customization fields according to the information provided in the JSON object.

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

Configuration example
---------------------

Expand All @@ -151,12 +154,15 @@ Configuration example
<level>10</level>
<group>multiple_drops,authentication_failures</group>
<alert_format>json</alert_format>
<options>{"pretext": "Custom Title"}</options> <!-- Replace with your custom JSON object -->
</integration>

<!-- Integration with PagerDuty -->
<integration>
<name>pagerduty</name>
<api_key>API_KEY</api_key> <!-- Replace with your PagerDuty API key -->
<options>{"pretext": "Custom title"}</options> <!-- Replace with your custom JSON object -->
<alert_format>json</alert_format> <!-- With the new script this is mandatory -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What new script? maybe some context is needed if commenting like this

Copy link
Member Author

@GabrielEValenzuela GabrielEValenzuela Sep 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @javimed !

I spoke with @MarcelKemp and the new script is being maintained.

Mainly, the change is based on the fact that pagerduty previously had a shell script and now it is in python.
For this reason, as most of the python scripts of integrations, the format of the alert that it expects is in JSON and for this reason it is necessary to change this parameter in the configuration.

Here I let you the associate PR and issue 😃

</integration>

<!-- Integration with VirusTotal -->
Expand All @@ -173,6 +179,7 @@ Configuration example
<hook_url>http://IP:3001/api/v1/hooks/HOOK_ID</hook_url> <!-- Replace with your Shuffle hook URL -->
<level>3</level>
<alert_format>json</alert_format>
<options>{"data": {"title": "Custom title"}}</options> <!-- Replace with your custom JSON object -->
</integration>

<!-- Integration with Maltiverse -->
Expand All @@ -191,4 +198,5 @@ Configuration example
<group>multiple_drops,authentication_failures</group>
<api_key>APIKEY</api_key> <!-- Replace with your external service API key -->
<alert_format>json</alert_format>
</integration>
<options>{"data": "Custom data"}</options> <!-- Replace with your custom JSON object -->
</integration>