Integrations
      Back to home
      1. Knowledge Base
      2. Cydarm Administration
      3. Integrations

      Azure Sentinel integration

      In this article we will explain how to set up an integration with Azure Sentinel, to create Cydarm cases from alerts.

      Overview

      Azure Sentinel includes SIEM and alerting capability, orchestration and automation, and incident management. Cydarm have a polling integration for Azure Sentinel. The integration, once configured, will poll the Alert API in Sentinel and create Cydarm cases from those alerts.

      A Sentinel Service needs to be initialised to run on a Cydarm platform. Then one or many polling integrations can be configured to poll either Azure Sentinel or Azure Defender and create cases within Cydarm.

      For hosted customers, please log a support ticket and provide the required Cydarm Configuration and Azure app registration details outlined below.

      For Enterprise customer, please see the Enterprise Configuration section below for configuration instructions.

      Cydarm Configuration information required

      The following information is required: 

      • Polling rate (in seconds) which indicates how frequently Cydarm will check for new alerts in Sentinal. Our default polling interval is 30 seconds.
      • If you have multiple organisations inside your Cydarm instance, we need the Organisation name for the Cydarm cases that will be created against the Sentinel alerts.

      Azure app registration and permissions

      The following Azure information is required to allow the Cydarm integration to connect to Azure:

      • Azure directory
      • Client secret
      • Client ID

      If you are a hosted customer, please log a support ticket with the above information and we will configure your instance.

      If you are an Enterprise customer, please see the Enterprise Configuration section below

      Case Creation

      After successful configuration, alerts from the Sentinel integration should be assigned to the configured Organisation with a default Severity level.

      When a new alert is detected by the Sentinel-Cydarm integration, the following fields from Azure Sentinel are mapped into a new Cydarm case:

      • Severity
      • Description
      • Metadata fields:
        • Sentinel Alert ID
        • Azure Subscription ID
        • Azure Tenant ID

      Enterprise Configuration

      These instructions assume that the Cydarm instance is configured with system vault.

      The steps for configuration are:

      1. Make a script for your encrypted system properties
      2. Create the service principal that will run the Cydarm-Sentinel integration
      3. Configure properties in Cydarm
        1. Create metadata fields in Cydarm to assign to cases created from Sentinel alerts
        2. Create the system properties in Cydarm to map sentinel alerts
      4. Update the Cydarm configuration to register the Sentinel integration
      5. Restart the Cydarm instance

      Make a script to create encrypted system properties

      The following code except needs to be saved in a filed called: create_sysprop.sh

      #!/bin/bash
      HOST=$1
      USERNAME=$2
      PASSWORD=$3

      encUserName=`echo -n $USERNAME | base64`
      encPassword=`echo -n $PASSWORD | base64`

      # Authenticate to Cydarm with the username/password to obtain a JWT bearer token:
      bearerToken=`curl --silent -v -k  $HOST/cydarm-api/auth/password -d '{"username":"'$encUserName'", "password":"'$encPassword'"}' 2>&1 | grep -i -E '^< Access-Token: ' | cut -d ' ' -f 3- | tr -d -c 'A-Za-z0-9\-\._'`

      # Use the bearer token to create a system property:
      curl -v -k -H "x-cydarm-authz: $bearerToken" $HOST/cydarm-api/sys-prop -d "{\"name\":\"${4}\",\"value\":\"${5}\",\"acl\":\"Sentinel Service service config\",\"encrypt\":${6}}"

      # Extract the session UUID from the JWT
      sessionUuid=`echo $bearerToken | cut -d '.' -f 2 | sed 's/$/===/g' | base64 -d | cut -d '"' -f 12`

      # End the session
      curl --silent -v -k -H "X-Cydarm-Authz: $bearerToken" $PROTO://${HOST}${PORT}/cydarm-api/auth/session/$sessionUuid -X DELETE

      And it must be made executable:

      chmod 700 create_sysprop.sh

      Then you can create encrypted system properties for this integration.

      Create service principal

      To setup the service principal, first create the agent username and password, then add it to the config and insert the credentials and the new ACLs into the database.

      Create a service principal:

      /data/cydarm/bin/cydarm-admin.sh create-user sentinel-agent-user "CUSTOMER ORGANISATION" Sentinel Agent

      Take the returned password, and add the password to the System Vault (you will need this password again a little later in this session):

      /data/cydarm/bin/cydarm-admin.sh add-system-secret $SV_UNSEAL_KEY $SV_LOGIN_TOKEN sentinel-agent-password $SENTINEL_AGENT_PASSWORD

      Now add the personal group to the new service principal:

      INSERT INTO cy_user_group (user_id, group_id, created, last_sync) 
      VALUES ((select id from cy_user where username = 'sentinel-agent-user'), 
      (Select id from cy_group where name = 'personal-sentinel-agent-user'), now(), now());

      Then insert the system properties to configure the organisation for which the Cydarm cases will be created, and the service principal for the Sentinel integration. This step requires the organisation name within Cydarm that will received the Sentinel alert cases.

      INSERT INTO cy_system_property (name, value, acl_id) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.ORG_NAME',
        'ORGANISATION NAME',
        (select id from cy_access_control_list where description = 'Sentinel Service config')
      );

      INSERT INTO cy_system_property (name, value, acl_id) VALUES (
        'SENTINEL_SERVICE.CYDARM.USERNAME',
        'sentinel-agent-user',
        (select id from cy_access_control_list where description = 'Sentinel Service config')
      );

      INSERT INTO cy_group_group (group_id, member_group_id, last_sync) VALUES (
        (SELECT id FROM cy_group WHERE name = 'Sentinel Service'),
        (SELECT id FROM cy_group WHERE name = ''personal-sentinel-agent-user'),
        NOW()
      );

      Add the encrypted system property for the service principal password. To do this, you need a username and password for the API and the address of your Cydarm API (e.g. https://cydarm.test.io).

      ./create_sysprop.sh '<ADDRESS OF API>' <username> <password> 'SENTINEL_SERVICE.CYDARM.PASSWORD' '<RETURNED_PASSWORD>' true

      This uses the returned password from above when you created the service principal.

      Configure Azure sentinel app properties in Cydarm

      Set the values for Azure app, client secret, and client ID as encrypted system properties.


      ./create_sysprop.sh '<ADDRESS OF API>' <username> <password> 'SENTINEL_SERVICE.SENTINEL.0.CLIENT_SECRET' '<CLIENT_SECRET>' true

      ./create_sysprop.sh '<ADDRESS OF API>' <username> <password> 'SENTINEL_SERVICE.SENTINEL.0.CLIENT_ID' '<CLIENT_ID>' true

      The next step inserts the system properties to refer to the Azure sentinel app. The parameters required are the Azure directory and the polling interval (in seconds). (They don't need to be encrypted.)

      INSERT INTO cy_system_property (name, value, acl_id) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.AZURE_DIRECTORY',
        '**Azure Directory**',
        (select id from cy_access_control_list where description = 'Sentinel Service config')
      );
      INSERT INTO cy_system_property (name, value, acl_id) VALUES (
        'SENTINEL_SERVICE.INTERVAL',
        '**polling interval in seconds**',
        (select id from cy_access_control_list where description = 'Sentinel Service config')
      );
      INSERT INTO cy_system_property (name, value, acl_id) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.LAST_UPDATE',
        '',
        (select id from cy_access_control_list where description = 'Sentinel Service editable config')
      );
      INSERT INTO cy_system_property (name, value, acl_id) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.LAST_UPDATE_OFFSET',
        '2s',
        (select id from cy_access_control_list where description = 'Sentinel Service config')
      );
      INSERT INTO  cy_system_property (name, value, acl_id, created) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.RESOURCE_TYPE',
        'scope',
        (select id from cy_access_control_list where description = 'Sentinel Service config'),
        now()
      );
      INSERT INTO  cy_system_property (name, value, acl_id, created) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.RESOURCE_VALUE',
        'https://graph.microsoft.com/.default',
        (select id from cy_access_control_list where description = 'Sentinel Service config'),
        now()
      );
      INSERT INTO  cy_system_property (name, value, acl_id, created) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.FILTER_FIELD',
        'createdDateTime',
        (select id from cy_access_control_list where description = 'Sentinel Service config'),
        now()
      );
      INSERT INTO  cy_system_property (name, value, acl_id, created) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.LOGIN_URL',
        'https://login.microsoftonline.com/{azure_directory}/oauth2/v2.0/token',
        (select id from cy_access_control_list where description = 'Sentinel Service config'),
        now()
      );

      INSERT INTO  cy_system_property (name, value, acl_id, created) VALUES (
        'SENTINEL_SERVICE.SENTINEL.0.ALERT_URL',
        'https://graph.microsoft.com/v1.0/security/alerts',
        (select id from cy_access_control_list where description = 'Sentinel Service config'),
        now()
      );

      Create metadata fields

      These metadata fields map values from the Sentinel alerts and apply them to each Cydarm case.

      INSERT INTO cy_metadata_name (metadata_name, precedence, acl, match) VALUES (
        'Sentinel Alert ID',
        (select max(precedence) from cy_metadata_name) + 1,
        (SELECT id FROM cy_access_control_list WHERE description='base user read'),
        '.*'
      );
      INSERT INTO cy_metadata_name (metadata_name, precedence, acl, match) VALUES (
        'Azure Subscription ID',
        (select max(precedence) from cy_metadata_name) + 1,
        (SELECT id FROM cy_access_control_list WHERE description='base user read'),
        '.*'
      );
      INSERT INTO cy_metadata_name (metadata_name, precedence, acl, match) VALUES (
        'Azure Tenant ID',
        (select max(precedence) from cy_metadata_name) + 1,
        (SELECT id FROM cy_access_control_list WHERE description='base user read'),
        '.*'
      );
      INSERT INTO cy_metadata_name (metadata_name, precedence, acl, match) VALUES (
        'Alert Hash',
        (select max(precedence) from cy_metadata_name) + 1,
        (SELECT id FROM cy_access_control_list WHERE description='base user read'),
        '.*'
      );

      Create mapping between Sentinel and Cydarm values

      Then we configure the mapping property between Sentinel and Cydarm. 

      INSERT INTO cy_system_property (name, value, acl_id, created) VALUES (
      'SENTINEL_SERVICE.SENTINEL.0.FIELD_MAPPING',
      regexp_replace('{
         "fields":[
            {
               "dest":"severityname",
               "src":[
                  {
                     "field":"severity",
                     "mapping":{
                        "emergency":"Emergency",
                        "high":"High",
                        "low":"Low",
                        "medium":"Medium",
                        "severe":"Severe"
                     }
                  }
               ]
            },
            {
               "dest":"description",
               "src":[
                  {
                     "field":"description"
                  }
               ]
            }
         ],
         "metadata":[
          {
                      "dest": "Sentinel Alert ID",
                      "src": [
                          {
                              "field": "id"
                          }
                      ]
         },
         {
                      "dest": "Severity",
                      "src": [
                          {
                              "field": "Severity"
                          }
                      ]
         },
         {
                      "dest": "Azure Subscription ID",
                      "src": [
                          {
                              "field":  "azureSubscriptionId"
                          }
                      ]
         },
         {
                      "dest": "Azure Tenant ID",
                      "src": [
                          {
                              "field": "azureTenantId"
                          }
                      ]
         }],
         "tags":null,
         "default_acl_name":""
      }', E'[\\n\\r\\t]+', '', 'g' ),
      (select id from cy_access_control_list where description = 'Sentinel Service config'),
      now()
      );

      Update the configuration and restart

      To register the new integration on your Cydarm instance, update the file: /data/cydarm/config/local/docker-compose.yaml

      Search for and update the following section:

      sentinel-agent:
          image: cydarm/sentinel-agent
          deploy:
            replicas: 0
          networks:
            cydarm-net-1: {}
          configs:
            - source: sentinel-agent-loader-config
              target: /config/sentinel-agent-loader-config.yaml

      Change replicas value to 1.

      sentinel-agent:
          image: cydarm/sentinel-agent
          deploy:
            replicas: 1
          networks:
            cydarm-net-1: {}
          configs:
            - source: sentinel-agent-loader-config
              target: /config/sentinel-agent-loader-config.yaml

      Save the updated config and merge in the new information.

      Then restart the Cydarm instance.

      $ /data/cydarm/bin/cydarm-admin.sh merge-config

      $ /data/cydarm/bin/cydarm-admin.sh stop

      $ /data/cydarm/bin/cydarm-admin.sh start
      Your Cydarm instance should now be polling Sentinel for alerts.

      References

      Azure instructions for app registration: https://learn.microsoft.com/en-us/graph/security-authorization#register-an-application-with-the-microsoft-identity-platform-endpoint


      For more detailed technical information please refer to our Cydarm API documentation.