Technical Note: CSTN 00030 - Using the Correlations Graph

[Andy_G]

Description

CyOPs™ provides you with the ability to view the nodes related to a particular record visually. In the Editable Form Group and Summary widgets, you can choose the Correlations Graph option for fields that have their field type set as Text Area. 

Following is an image of a sample Correlation Graph that you can view in the Detail view of an Alert record:

Solution

To build a Correlation Graph, you must provide the input data in a particular JSON format, an example of which follows:

[
 {
    "id": "/api/3/alerts/e627b3c3-b3db-41ca-8291-d3eb1e40760b",
    "data": {
      "$type": "star",
      "$color": "#e31b1d"
    },
    "name": "ALERT-408: IMAP -WIN-EXCH.cyo...",
    "adjacencies": [
      {
        "data": {},
        "nodeTo": "/api/3/incidents/22e6291d-3908-4bf9-a151-08bfaef8dcfb",
        "nodeFrom": "/api/3/alerts/e627b3c3-b3db-41ca-8291-d3eb1e40760b"
      }
    ]
},
{
    "id": "/api/3/incidents/22e6291d-3908-4bf9-a151-08bfaef8dcfb",
    "data": {
      "$type": "square",
      "$color": "#DE7A13"
    },
    "name": "INCIDENT-414: Security Lock C...",
    "adjacencies": [
      {
        "data": {},
        "nodeTo": "/api/3/alerts/e627b3c3-b3db-41ca-8291-d3eb1e40760b",
        "nodeFrom": "/api/3/incidents/22e6291d-3908-4bf9-a151-08bfaef8dcfb"
      }
    ]
 }
]

The Code-Snippet connector, which is a CyOPs™ Built-in connector, is one of the ways to build this JSON format.

For the Correlations Graph to be rendered, this JSON input must be passed to fields that have their field type set as Text Area. To include the Correlations Graph option in a field, you must do the following:

1. Navigate to the module where you want the Correlations Graph to be displayed, for example, Alerts and click a record in this module to open the Detail view of this module. 

2. Click Edit Template to open the Template Editor and modify the interface. 

3. Click Edit in the Editable Form Group and modify the field, which has its field type set as Text Area, for example, Correlations Graph.  
   Click the v icon in the Correlations Graph field to display more options and from the Text Editor drop-down list select Correlations Graph.
   

4. Click Save and Apply Changes.  
   Now when you open the alert record in the detail view, you will see the visual correlations displayed (based on your input JSON) as shown in the following image:
   

In the CyOPs™ 4.12.2 community edition, the Correlations Graph has been configured for the Correlations Graph field in the Alerts, Incidents, and Indicator modules.

Following are the steps that you require to perform to view correlations visually, in the CyOPs™ 4.12.2 community edition:

1. Configure the Code-Snippet connector:
   1. Click Automation > Connectors in the left navigation bar.
   2. On the Connectors page, in the Search box, type code to search for the Code Snippet connector.
   3. Click on the Code Snippet connector row, to display the Code Snippet configuration pane and configure the following parameters:
      1. In the Configuration Name field, add a unique Name for the configuration.
      2. Check the Mark As Default Configuration option to make the selected configuration, the default configuration of this connector, on the particular CyOPs™ instance. By default, this connector will point to this configuration, when it is being used in playbooks, etc.
      3. Check that the Allow All Imports checkbox is checked (it is checked by default), to enable importing of all python modules, and you require to include the import statement for any modules you want to use.
         
   4. Click Save to save the configuration.
2. Viewing the Correlations Graph:
   1. Click Incident Response > Alerts in the left navigation bar.
   2. Click on an alert and in the detail view of the alert, click Execute > Generate Node Graph.
      

Note: The Correlations Graph is static, i.e., if you add a relation it will not automatically get reflected. For example, if you related an indicator with an alert, the Correlations Graph will not automatically reflect this update. You will have to regenerate the Correlations Graph, by, for example, re-executing the Generate Node Graph playbook to get the updated content and reflect the changes on the graph

To change how the Correlations Graph is configured or to add any relations, then do the following:

1. Click Automation > Playbooks in the left navigation bar.
2. On the Playbooks page, in the Collections tab, click 10 - Utilities.
3. In the 10 - Utilities pane, click the Generate Node Graph playbook
4. In the Playbook Designer, click the Set Variable step, named Configurations.
   To be able to use the Correlations Graph, you must provide the input data in a particular format, which is included in the relation_config field, in the Variables section. You can add relations or change the configuration by editing this field:
   
5. Click Save to save your update configurations.
   Important: The Code Snippet step, named Adjacency Graphs, contains the default python code based on which the correlation graph is created. DO NOT CHANGE THIS STEP.