Integration with R-Vision Security Orchestration, Automation and Response

R-Vision Security Orchestration, Automation and Response (hereinafter referred to as R-Vision SOAR) is a software platform used for automation of monitoring, processing, and responding to information security incidents. It aggregates cyberthreat data from various sources into a single database for further analysis and investigation to facilitate incident response capabilities.

R-Vision SOAR can be integrated with KUMA. When this integration is enabled, the creation of a KUMA alert triggers the creation of an incident in R-Vision SOAR. A KUMA alert and its R-Vision SOAR incident are interdependent. When the status of an incident in R-Vision SOAR is updated, the status of the corresponding KUMA alert is also changed.

Integration of R-Vision SOAR and KUMA is configured in both applications. In KUMA integration settings are available only for general administrators.

Mapping KUMA alert fields to R-Vision SOAR incident fields when transferring data via API

Configuring integration in KUMA

This section describes integration of KUMA with R-Vision SOAR from the KUMA side.

Integration in KUMA is configured in the web interface under Settings → IRP / SOAR.

To configure integration with R-Vision SOAR:

1. In the KUMA web interface, open Resources → Secrets.

   The list of available secrets will be displayed.

2. Click the Add secret button to create a new secret. This resource is used to store token for R-Vision SOAR API requests.

   The secret window is displayed.

3. Enter information about the secret:
   1. In the Name field, enter a name for the added secret. The name must contain 1 to 128 Unicode characters.
   2. In the Tenant drop-down list, select the tenant that will own the created resource.
   3. In the Type drop-down list, select token.
   4. In the Token field, enter your R-Vision SOAR API token.

      You can obtain the token in the R-Vision SOAR web interface under Settings → General → API.

   5. If necessary, in the Description field, add up to 4,000 Unicode characters describing the secret.
4. Click Save.

   The R-Vision SOAR API token is now saved and can be used in other KUMA resources.

5. In the KUMA web interface, go to Settings → IRP / SOAR.

   The window containing R-Vision SOAR integration settings opens.

6. Make the necessary changes to the following parameters:
   • Disabled—select this check box if you want to disable R-Vision SOAR integration with KUMA.
   • In the Secret drop-down list, select the previously created secret.

     You can create a new secret by clicking the button with the plus sign. The created secret will be saved in the Resources → Secrets section.

   • URL (required)—URL of the R-Vision SOAR server host.
   • Field name where KUMA alert IDs must be placed (required)—name of the R-Vision SOAR field where the ID of the KUMA alert must be written.
   • Field name where KUMA alert URLs must be placed (required)—name of the R-Vision SOAR field where the link for accessing the KUMA alert should be written.
   • Category (required)—category of R-Vision SOAR incident that is created after KUMA alert is received.
   • KUMA event fields that must be sent to IRP / SOAR (required)—drop-down list for selecting the KUMA event fields that should be sent to R-Vision SOAR.
   • Severity group of settings (required)—used to map KUMA severity values to R-Vision SOAR severity values.
7. Click Save.

In KUMA integration with R-Vision SOAR is now configured. If integration is also configured in R-Vision SOAR, when alerts appear in KUMA, information about those alerts will be sent to R-Vision SOAR to create an incident. The Details on alert section in the KUMA web interface displays a link to R-Vision SOAR.

If you are working with multiple tenants and want to integrate with R-Vision SOAR, the names of tenants must match the abbreviated names of companies in R-Vision SOAR.

Configuring integration in R-Vision SOAR

This section describes KUMA integration with R-Vision SOAR from the R-Vision SOAR side.

Integration in R-Vision SOAR is configured in the Settings section of the R-Vision SOAR web interface. For details on configuring R-Vision SOAR, please refer to the documentation on this application.

Configuring integration with KUMA consists of the following steps:

• Configuring R-Vision SOAR user role
  1. Assign the Incident manager system role to the R-Vision SOAR user utilized for integration. The role is assigned when a user is selected in the R-Vision SOAR web interface in the Settings → General → System users section. The role is added in the System Roles block of settings.

     R-Vision SOAR version 4.0 user with the Incident Manager role

     

     R-Vision SOAR version 5.0 user with the Incident Manager role

     

  2. Make sure that the API token of the R-Vision SOAR user utilized for integration is indicated in the secret in the KUMA web interface. The token is displayed in the R-Vision SOAR web interface under Settings → General → API.

     API token in R-Vision SOAR version 4.0

     

     API token in R-Vision SOAR version 5.0

     

• Configuring R-Vision SOAR incident fields and KUMA alert fields
  1. Add the ALERT_ID and ALERT_URL incident fields.
  2. Configure the category of R-Vision SOAR incidents created based on KUMA alerts. You can do this in the R-Vision SOAR web interface, in the Settings → Incident management → Incident categories section. Add a new incident category or edit an existing incident category by indicating the previously created Alert ID and Alert URL incident fields under Category fields. The Alert ID field can be hidden.

     Incident categories with data from KUMA alerts in R-Vision SOAR version 4.0

     

     Incident categories with data from KUMA alerts in R-Vision SOAR version 5.0

     

  3. Block editing of previously created Alert ID and Alert URL incident fields. In the R-Vision SOAR web interface, under Settings → Incident management → Presentation, select the category of R-Vision SOAR incidents that will be created based on KUMA alerts and put a lock icon next to the Alert ID and Alert URL incident fields.

     The Alert URL field is not editable in R-Vision SOAR version 4.0

     

     The Alert URL field is not editable in R-Vision SOAR version 5.0

     

• Creating R-Vision SOAR collector and connector
  1. Create an R-Vision SOAR collector to interact with KUMA.
  2. Create and configure an R-Vision SOAR connector to send API requests to close KUMA alerts.
• Creating a rule to close a KUMA alert

  Create a rule for sending KUMA alert closing request when R-Vision SOAR incident is closed.

Integration with KUMA is now configured in R-Vision SOAR. If integration is also configured in KUMA, when alerts appear in KUMA, information about those alerts is sent to R-Vision SOAR to create an incident. The Details on alert section in the KUMA web interface displays a link to R-Vision SOAR.

Adding the ALERT_ID and ALERT_URL incident fields

To add the ALERT_ID incident field in the R-Vision SOAR:

1. In the R-Vision SOAR web interface, under Settings → Incident management → Incident fields, select the No group group of fields.
2. Click the plus icon in the right part of the screen.

   The right part of the screen will display the settings area for the incident field you are creating.

3. In the Title field, enter the name of the field (for example: Alert ID).
4. In the Type drop-down list, select Text field.
5. In the Parsing Tag field, enter ALERT_ID.

ALERT_ID field added to R-Vision SOAR incident.

ALERT_ID field in R-Vision SOAR version 4.0

ALERT_ID field in R-Vision SOAR version 5.0

To add the ALERT_URL incident field in R-Vision SOAR:

1. In the R-Vision SOAR web interface, under Settings → Incident management → Incident fields, select the No group group of fields.
2. Click the plus icon in the right part of the screen.

   The right part of the screen will display the settings area for the incident field you are creating.

3. In the Title field, enter the name of the field (for example: Alert URL).
4. In the Type drop-down list, select Text field.
5. In the Parsing Tag field, enter ALERT_URL.
6. Select the Display links and Display URL as links check boxes.

ALERT_URL field added to R-Vision SOAR incident.

ALERT_URL field in R-Vision SOAR version 4.0

ALERT_URL field in R-Vision SOAR version 5.0

If necessary, you can likewise configure the display of other data from a KUMA alert in an R-Vision SOAR incident.

Creating a collector in R-Vision SOAR

To create a collector in R-Vision SOAR:

1. In the R-Vision SOAR web interface, under Settings → Common → Collectors, click the plus icon.
2. Specify the collector name in the Name field (for example, Main collector).
3. In the Collector address field, enter the IP address or hostname where the R-Vision SOAR is installed (for example, 127.0.0.1).
4. In the Port field type 3001.
5. Click Add.
6. On the Organizations tab, select the organization for which you want to add integration with KUMA and select the Default collector and Response collector check boxes.

The R-Vision SOAR collector is created.

Creating connector in R-Vision SOAR

To create connector in R-Vision SOAR:

1. In the R-Vision SOAR web interface, under Settings → Incident management → Connectors, click the plus icon.
2. In the Type drop-down list, select REST.
3. In the Name field, specify the connector name, such as KUMA.
4. In the URL field type API request to close an alert in the format <KUMA Core server FQDN>:<Port used for API requests (7223 by default)>/api/v1/alerts/close.

   Example: https://kuma-example.com:7223/api/v1/alerts/close

5. In the Authorization type drop-down list, select Token.
6. In the Auth header field type Authorization.
7. In the Auth value field enter the token of KUMA user with general administrator role in the following format:

   Bearer <KUMA General administrator token>

8. In the Collector drop-down list select previously created collector.
9. Click Save.

The connector has been created.

Connector in R-Vision SOAR version 4.0

Connector in R-Vision SOAR version 5.0

When connector is created you must configure sending API queries for closing alerts in KUMA.

To configure API queries in R-Vision SOAR:

1. In the R-Vision SOAR web interface, under Settings → Incident management → Connectors, open for editing the newly created connector.
2. In the request type drop-down list, select POST.
3. In the Params field type API request to close an alert in the format <KUMA Core server FQDN>:<Port used for API requests (7223 by default)>/api/v1/alerts/close.

   Example: https://kuma-example.com:7223/api/v1/alerts/close

4. On the HEADERS tab, add the following keys and values:
   • Key Content-Type; value: application/json.
   • Key Authorization; value: Bearer <KUMA general administrator token>.

     The token of the KUMA general administrator can be obtained in the KUMA web interface under Settings → Users.

5. On the BODY → Raw tab, enter the contents of the API request body:

   {

       "id":"{{tag.ALERT_ID}}",

       "reason":"<Reason for closing the alert. Available values: "Incorrect Correlation Rule", "Incorrect Data", "Responded".> "

   }

6. Click Save.

The connector is configured.

Connector in R-Vision SOAR version 4.0

Connector in R-Vision SOAR version 5.0

Creating rule for closing KUMA alert when R-Vision SOAR incident is closed

To create a rule for sending an alert closing request to KUMA when an R-Vision SOAR incident is closed:

1. In the R-Vision SOAR web interface, under Settings → Incident management → Response playbooks, click the plus icon.
2. In the Name field, type the name of the rule, for example, Close alert.
3. In the Group drop-down list select All playbooks.
4. Under Autostart criteria, click Add and enter the conditions for triggering the rule in the opened window:
   1. In the Type drop-down list, select Field value.
   2. In the Field drop-down list, select Incident status.
   3. Select the Closed status.
   4. Click Add.

   Rule trigger conditions are added. The rule will trigger when an incident is closed.

5. Under Incident Response Actions, click Add → Run connector. In the opened window, select the connector that should be run when the rule is triggered:
   1. In the Connector drop-down list select previously created connector.
   2. Click Add.

   Connector added to the rule.

6. Click Add.

A rule is created for sending a KUMA alert closing request when an R-Vision SOAR incident is closed.

R-Vision IRP version 4.0 playbook rule

R-Vision SOAR version 5.0 playbook rule

Managing alerts using R-Vision SOAR

After integration of KUMA and R-Vision SOAR is configured, data on KUMA alerts starts coming into R-Vision SOAR. Changes of alert parameters in KUMA are reflected in R-Vision SOAR. Any changes in the statuses of alerts in KUMA or R-Vision SOAR (except closing an alert) are also reflected in the other system.

Alert management scenarios when KUMA and R-Vision SOAR are integrated:

• Send cyberthreat data from KUMA to R-Vision SOAR

  Data on detected alerts is automatically sent from KUMA to R-Vision SOAR. An incident is also created in R-Vision SOAR.

  The following information about the KUMA alert is sent to R-Vision SOAR:

  • ID.
  • Name.
  • Status.
  • Date of the first event related to the alert.
  • Date of the last detection related to the alert.
  • User account name or email address of the security officer assigned to process the alert.
  • Alert severity.
  • Category of the R-Vision SOAR incident corresponding to the KUMA alert.
  • Hierarchical list of events related to the alert.
  • List of alert-related assets (internal and external).
  • List of users related to the alert.
  • Alert change log.
  • Link to the alert in KUMA.
• Investigate cyberthreats in KUMA

  Initial processing of an alert is performed in KUMA. The security officer can update and change any parameters of an alert except its ID and name. Any changes are reflected in the R-Vision SOAR incident card.

  If a cyberthreat turns out to be a false positive and its alert is closed in KUMA, its corresponding incident in R-Vision SOAR is also automatically closed.

• Close incident in R-Vision SOAR

  After all necessary work is completed on an incident and the course of the investigation is recorded in R-Vision SOAR, the incident is closed. The corresponding KUMA alert is also automatically closed.

• Open a previously closed incident

  If active monitoring detects that an incident was not completely resolved or if additional information comes up, this incident is re-opened in R-Vision SOAR. However, the alert remains closed in KUMA.

  The security officer can use a link to navigate from an R-Vision SOAR incident to the corresponding alert in KUMA and make the necessary changes to any of its parameters except the ID, name, and status of the alert. Any changes are reflected in the R-Vision SOAR incident card.

  Further analysis is performed in R-Vision SOAR. When the investigation is complete and the incident is closed again in R-Vision SOAR, the status of the corresponding alert in KUMA remains closed.

• Request additional data from the source system as part of the response playbook or manually

  If additional information is required from KUMA when analyzing incidents in R-Vision SOAR, in R-Vision SOAR, you can create a search request to KUMA (for example, you can request telemetry data, reputation, host information). This request is sent via KUMA REST API and the response is recorded in the R-Vision SOAR incident card for further analysis and reporting.

  This same sequence of actions is performed during automatic processing if it is not possible to immediately save all information on an incident during an import.