Configuring Notifications

Use the Events and Notifications services to send notifications, wheneverCloud Guard detects a problem for which you want to be notified.

Prerequisite: If you want to configure notifications to be sent through Slack, create a Webhook for the Slack channel to receive the notifications before proceeding with the steps in the "Configure Notifications..." that follows. See Slack documentation.
Note

If you are processing problems entirely within Cloud Guard, you do not need to configure notifications.

Cloud Guard provides a notification responder, Cloud Event, that can emit problem details to the Events service. The Cloud Event responder rule is part of the Responder recipe, which needs to be attached to a corresponding target or targets. The Cloud Event rule is enabled by default. The Cloud Event responder does not require other IAM policies and is configured to execute automatically.

Emitting from Cloud Event to the Events service allows for integration with the Notifications service, which can push notifications to:

  • Email
  • Slack
  • Oracle Cloud Infrastructure Functions

Notifications can be sent for any of these event types in Cloud Guard:

  • Problem detected – when Cloud Guard detects a potential security issue that appears on the Problems page. These are the details for the different actions that can occur under this event type:
    Event Type Action Leading to Event Status Field in Event Details Reason Field in Event Details
    Detected-Problem New Problem Created OPEN New Problem detected by CloudGuard
    Detected-Problem Problem Updated OPEN Existing Problem updated by CloudGuard
    Detected-Problem Problem Reopened by Cloud Guard OPEN Existing Problem re-opened by CloudGuard
    Detected-Problem

    Problem Reopened By User

    OPEN Existing Problem re-opened by User
  • Problem remediated - when a responder that is configured to automatically remediate a detected problem performs the remediation. These are the details for the different actions that can occur under this event type:
    Event Type Action Leading to Event Status Field in Event Details Reason Field in Event Details
    Remediated-Problem User Marked the problem as Resolved RESOLVED Problem marked as RESOLVED by <User OCID>
    Remediated-Problem Problem Dismissed RESOLVED Problem marked as DISMISSED by <User>
    Remediated-Problem Problem Auto Resolved RESOLVED Problem is auto resolved by CloudGuard
    Remediated-Problem User does manual problem remediation / Responder Rules configured for Automatic Remediation RESOLVED Problem remediated by CloudGuard
  • Problem threshold reached - when Cloud Guard discovers that certain threshold limits are reached, because of excessive audit signals from services such as VCN or Identity.
Note

You must set up Events and Notifications from your Cloud Guard Reporting Region, which aggregates problems from the monitored regions and send out the Cloud Event from the Reporting Region.

To receive notifications when a responder recipe is triggered, you must:

  1. For OCI Functions, create the function code to call and place the function application in the compartment from which it's to be called.
  2. In Cloud Guard, ensure that the Cloud Event rule is enabled for the responder recipe.
  3. For email or Slack notifications, in the Notification service, create a Topic and a Subscription to that topic.
  4. In the Events service, configure a rule that specifies the Action to take.

What's Next

To set up notifications through email or Slack, continue with Notifying through Email or Slack.

To use OCI Functions to relay notification information to another service, see Notifying through OCI Functions.

Notifying through Email or Slack

Use the Events and Notifications services to send notifications through email or Slack, whenever Cloud Guard detects a problem for which you want to be notified.

Note

To add notifications for more than one event type, perform all the following steps for the first notification, then repeat steps 3 and 4 for each additional notification.
  1. In Cloud Guard, ensure that the Cloud Event rule is enabled for the responder recipe for which you want to receive notifications.
    1. From the Cloud Guard options panel on the left, select Responder Recipes.
    2. Click the name of the recipe for which you want to configure notifications.
    3. On the detail page for the responder recipe, in the Responder Rules section, locate the row for the Cloud Events rule.
    4. If the entry in the Status column for the Cloud Events rule is Disabled:
      1. Open the Actions menu Image of Action menu and select Edit.
      2. In the Edit Responder Rule dialog box, drop down the Status list and select Enabled.
      3. Click Save.
  2. In Cloud Guard, ensure that the target for which you want to receive notifications has the responder recipe that you just checked added, with automatic execution enabled.
    1. From the Cloud Guard options panel on the left, select Targets.
    2. On the Targets page, in the Target Name column, click the name of the target about which you want to receive notifications.
    3. On the details page for that target, under Resources on the left, click Detector Recipes.
      • If the name of the responder recipe appears under Recipe Name, it is already added.
      • If there is nothing listed under Recipe Name, click Add Recipe and select the responder recipe to add.
      • If a different responder recipe appears under Recipe Name:
        1. Open the Actions menu Image of Action menu and select Remove, then confirm the removal.
        2. Click Add Recipe and select the responder recipe to add.
    4. Ensure that the Cloud Event responder rule is set to execute automatically:
      1. Under Recipe Name, click the link for the responder recipe.
      2. On the details page for the responder recipe, in the Responder Rules section, locate the row for Cloud Event responder rule.
      3. In that row, open the Actions menu Image of Action menu, and select Edit.
      4. In the Configure Responder Rule dialog box, Setting section, check the Rule Trigger setting.
      5. If Rule Trigger is set to Ask me before executing rule:
        1. Select Execute Automatically.
        2. Select the CONFIRM EXECUTE AUTOMATICALLY check box.
        3. Click Save.
  3. In the Notifications service, create a topic.
    1. From the Oracle Cloud menu, select Developer Services, then click Application Integration, then click Notifications.
    2. On the Topics page, click Create Topic.
    3. In the Create Topic dialog box:
      1. Enter a Name for the topic.
      2. (Optional) Enter a Description for the topic.
      3. (Optional) Specify tagging information.
      4. Click Create.

        The topic you created appears in the list on the Topics page.

  4. Create a subscription to the topic.
    1. On the Topics page, in the Name column, click the name of the topic you created.
    2. On the details page for the topic, under Resources, click Create Subscription.
    3. In the Create Subscription dialog box:
      1. Set Protocol for email or Slack notification:
        • Email:
          1. Set Protocol to Email.
          2. Enter the email address that should receive the notifications.
        • Slack:
          1. Set Protocol to Slack.
          2. For URL, enter the URL for your Slack Webhook.
      2. Specify tag information for one or more tag namespaces.

        Click Additional Tag to specify tag information for another tag namespace.

      3. Click Create.

        The details page for the subscription you just created appears:

        • The large "T" icon is orange, with "Pending" under it.
        • The Subscription Information tab displays "Pending confirmation" just below the tab title.
      4. When you receive the subscription confirmation email, click the Confirm Subscription link in the body of the message.

        An Oracle Cloud Infrastructure page appears in your browser, indicating that your subscription is confirmed.

        On the details page for the subscription you created:

        • The large "T" icon is green, with "Active" under it.
        • The Subscription Information tab no longer displays "Pending confirmation" at the top.
  5. In the Events service, configure a rule to specify conditions under which a notification is sent.
    1. Ensure that you are in the reporting region of the tenancy where the responder recipe is active.

      To see the reporting region, from the Cloud Guard options panel on the left select Settings.

      To see the region that you are in, drop down the regions list at the top of the page.

    2. From the Oracle Cloud menu, select Observability & Management , then click Events Service.
    3. Under List Scope, ensure that the Compartment selected is either the compartment where the resource exists, or a parent of that compartment.
    4. Click Create Rule.
    5. On the Create Rule page, enter a Display Name for the rule.
    6. (Optional) Enter a Description for the rule.
    7. In the Rule Conditions section:
      • Set Condition to Event Type.
      • Set Service Name to Cloud Guard.
      • Set Event Type to the type of event for which you want to be notified:
        • Detected - Problem
        • Remediated - Problem
        • Target - Information
    8. To add another rule condition, in the Rule Conditions section, click Another Condition.
      Note

      Multiple rules are ANDed to limit the scope for which a notification is sent. To trigger a notification, all conditions must be true.
      1. Set first item, for example, to Attribute.
      2. Set second item to the parameter on which you want to filter.

        For example, if first item is Attribute, you might set Attribute Name to riskLevel.

      3. Set third item to the value for the parameter on which you want to filter.

        For example, if you set first item to Attribute, and then set Attribute Name to riskLevel, you might set third item to Critical.

      4. (Optional) To add another rule condition to further limit the scope for which a notification is sent, click Another Condition, then repeat the preceding substeps.
    9. In the Actions section:
      1. Set Action Type to Notifications.
      2. Select the Notifications Compartment.
      3. For Topic, select the name of the Notifications topic you created.
    10. Click Create Rule at the bottom of the page.
      The details page for the rule you created appears.
  6. Watch for activity for the Cloud Event responder rule with status Succeeded, on either the Problems or Responder Activity page.
    This activity confirms that the Cloud Event responder rule is being triggered and it is creating events for that problem in the Events service.

Notifying through OCI Functions

Use the Events and Notifications services to send notifications through Oracle Cloud Infrastructure Functions, wheneverCloud Guard detects a problem for which you want to be notified.

  1. Familiarize yourself with Oracle Functions.
    If you are working with Oracle Functions for the first time:
  2. Examine the data contained in the event envelope for a Cloud Guard problem.

    The following sample shows key pieces of information in bold:

    (
        "eventType": "com.oraclecloud.cloudguard.problemdetected",
        "cloudEventsVersion": "0.1",
        "eventTypeVersion": "2.0",
        "source": "CloudGuardResponderEngine"'
        "eventTime": "2020-09-21T18:21:49Z",
        "contentType": "application/json",
        "data":
        {
            "compartmentId": "<compartment_OCID>",
            "compartmentName": "<compartment_name>",
            "resourceName": "Object Storage bucket is encrypted with Oracle-managed key",
            "resourceId": "ocid1.cloudguardproblem.oc1.iad.<unique_resource_id>",
            "additionalDetails":
            {
                "tenantId": "<oci_tenant_id>",
                "problemDescription": "Encryption of storage buckets provides an additional 
                    level of security on your data. Management of encryption keys is 
                    critical to protecting and accessing protected data. Some customers 
                    want to identity storage buckes encrypted Oracle-managed keys in order
                    to apply their own key lifecycle management to the bucket.",
                "riskLevel": "MINOR",
                "problemRecommendation": "Assign a vault key to this bucket",
                "status": "OPEN",
                "problemType": "CONFIG_CHANGE",
                "resoourceName": "<oci_resource_name>",
                "resourceId": "<resource_ocid>",
                "resourceType": "Bucket",
                "targetId": "ocid1.cloudguardtarget.oc1.iad.<unique_target_id>",
                "labels": "CIS 3.0, Vault",
                "firstDetected": "2020-09-21T18:21:46.001Z",
                "lastDetected": "2020-09-21T18:21:46.001Z",
                "region": "us-ashburn-1"
            ]
        },
        "eventId": "8dg7bc2b-63d8-44be-b19d-e3203e64a810",
        "extensioons":
        {,
            "compartmentId": "oc1dl.compartment.ocl.<unique_compartment_id>"
        }
    }
  3. Create the function application code.

    You can use Python, Java, and several other languages to develop your function. This example uses Python.

    1. The Event service invokes this function. You can obtain event data by using a code fragment like this:
      def handler(ctx, data: io.BytesIO = None):
      funDataStr = data.read().decode('utf-8')
      funData =  json.loads(funDataStr)

      The ctx parameter passes the function configuration, and the data parameter passes the data.

    2. Obtain the function configuration from the ctx parameter of the handler function:
      config = ctx.Config()
    3. To invoke OCI APIs from inside the function, use a resource principal:
      ociResPrncplSigner = oci.auth.signers.get_resource_principals_signer()
      ociObjStoreSvc = oci.object_storage.ObjectStorageClient(config={}, signer=ociResPrncplSigner)
    4. Use standard JSON techniques to extract the values of various fields from within the data element.
    5. Then use other standard manipulation techniques to perform transformations and analyses to support whatever logic you require to complete the function.
    6. (Optional) Invoke APIs for external services from inside the function to integrate with external systems, for example:
      • If the riskLevel is CRITICAL, call the public APIs for a service management system to open a ticket, with relevant details populated from other fields in the event envelope for the problem.
      • To send the entire data across for further analysis, call an external SIEM system's APIs.
      • Use OCI APIs to enrich the data before sending to an external SIEM.

    If you are using JSON, the resulting function code might look something like this:

    import io
    import sys
    import oci
    import json
    #import time
    from fdk import response
    # This Python function creates an object in a Object Store Bucket when
    # triggered by OCI Events Service with a Cloud Problem as input. The JSON
    # format data for 'additionalDetails' is simply written out as content of the
    # created object. This function takes two parameters:
    #
    # OCI_CMPT_ID - Compartment OCID of the OCI Bucket
    # OCI_OBJ_BUCKET_NAME - Name of the OCI Bucket where the object will be created
    #
    # Object names comprise of two parts - resource Id and event Id
    #
    def handler(ctx, data: io.BytesIO = None):
        try:
            respData = {}
            # Get Config
            ctxConfig = ctx.Config()
            # Get Data
            funDataStr = data.read().decode('utf-8')
            # Load JSON from String
            funData =  json.loads(funDataStr)
            respData['RECVD_DATA'] = funDataStr
            # Read the configuration parameters
            ociCmptID = ctxConfig['OCI_CMPT_ID']
            ociBucketName = ctxConfig['OCI_OBJ_BUCKET_NAME']
            # Create Object name string
            ociObjName = funData['data']['resourceId'] + '-' + funData['eventID']
            # Create signer and Object Store API client
            ociResPrncplSigner = oci.auth.signers.get_resource_principals_signer()
            ociObjStoreSvc = oci.object_storage.ObjectStorageClient(config={}, signer=ociResPrncplSigner)
            # Get 'additionalDetails' field from data
            cgProblem = funData['data']['additionalDetails']
            # Call function to create the object
            objStoreRespStatus = storeToOCIObjStore(ociObjStoreSvc, ociCmptID, ociBucketName, ociObjName, json.dumps(cgProblem))
            respData['OBJ_STORE_RESP_STATUS'] = objStoreRespStatus
        except Exception as e:
            respData['EXCEPTION_MESSAGE'] = str(e)
            respData['EXCEPTION_MESSAGE_CLASS'] = str(e.__class__)
        sys.stderr.write(json.dumps(respData))
        return response.Response(ctx, response_data=json.dumps(respData), headers={'Content-Type': 'application/json'})
    # This function creates an object in OCI Object in OCI Object Store
    def storeToOCIObjStore(ociObjStoreSvc, cmptID, bucketName, objName, dataStr):
        objStoreNS = ociObjStoreSvc.get_namespace(compartment_id=cmptID).data
        objBody = io.BytesIO(dataStr.encode('utf-8'))
        objStoreResp = ociObjStoreSvc.put_object(objStoreNS, bucketName, objName, objBody)
        return objStoreResp.status
  4. Create an application for your function and locate it in the compartment from which you plan to call the function.
  5. In Cloud Guard, ensure that the Cloud Event rule is enabled for the responder recipe for which you want to receive notifications.
    1. From the Cloud Guard options panel on the left, select Responder Recipes.
    2. Click the name of the recipe for which you want to configure notifications.
    3. On the detail page for the responder recipe, in the Responder Rules section, locate the row for the Cloud Events rule.
    4. If the entry in the Status column for the Cloud Events rule is Disabled:
      1. Open the Actions menu Image of Action menu and select Edit.
      2. In the Edit Responder Rule dialog box, drop down the Status list and select Enabled.
      3. Click Save.
  6. In Cloud Guard, ensure that the target for which you want to receive notifications has the responder recipe that you just checked added, with automatic execution enabled.
    1. From the Cloud Guard options panel on the left, select Targets.
    2. On the Targets page, in the Target Name column, click the name of the target about which you want to receive notifications.
    3. On the details page for that target, under Resources on the left, click Responder Recipes.
      • If the name of the responder recipe appears under Recipe Name, it is already added.
      • If nothing is listed under Recipe Name, click Add Recipe and select the responder recipe to add.
      • If a different responder recipe appears under Recipe Name:
        1. Open the Actions menu Image of Action menu and select Remove, then confirm the removal.
        2. Click Add Recipe and select the responder recipe to add.
    4. Ensure that the Cloud Event responder rule is set to execute automatically:
      1. Under Recipe Name, click the link for the responder recipe.
      2. On the details page for the responder recipe, in the Responder Rules section, locate the row for Cloud Event responder rule.
      3. In that row, open the Actions menu Image of Action menu, and select Edit.
      4. In the Configure Responder Rule dialog box, Setting section, check the Rule Trigger setting.
      5. If Rule Trigger is set to Ask me before executing rule:
        1. Select Execute Automatically.
        2. Select the CONFIRM EXECUTE AUTOMATICALLY check box.
        3. Click Save.
  7. In the Events service, configure a rule to specify conditions under which a notification is sent.
    1. Ensure that you are in the reporting region of the tenancy where the responder recipe is active.

      To see the reporting region, from the Cloud Guard options panel on the left, select Settings.

      To see the region that you are in, drop down the regions list at the top of the page.

    2. From the Oracle Cloud menu, select Observability & Management , then click Events Service.
    3. Under List Scope, ensure that the Compartment selected is either the compartment where the resource exists, or a parent of that compartment.
    4. Click Create Rule.
    5. On the Create Rule page, enter a Display Name for the rule.
    6. (Optional) Enter a Description for the rule.
    7. In the Rule Conditions section:
      • Set Condition to Event Type.
      • Set Service Name to Cloud Guard.
      • Set Event Type to the type of event for which you want to be notified:
        • Detected - Problem
        • Remediated - Problem
        • Target - Information
    8. To add another rule condition, in the Rule Conditions section, click Another Condition.
      Note

      Multiple rules are ANDed to limit the scope for which a notification is sent. To trigger a notification, all conditions must be true.
      1. Set first item, for example, to Attribute.
      2. Set second item to the parameter on which you want to filter.

        For example, if first item is Attribute, you might set Attribute Name to riskLevel.

      3. Set third item to the value for the parameter on which you want to filter.

        For example, if you set first item to Attribute, and then set Attribute Name to riskLevel, you might set third item to Critical.

      4. (Optional) To add another rule condition to further limit the scope for which a notification is sent, click Another Condition, then repeat the preceding substeps.
    9. In the Actions section:
      1. Set Action Type to Functions.
      2. Select the Functions Compartment that contains the function application.
      3. Select the Function Application that contains the function that you want to run.

        If you see "None available in selected compartment," the function application you created is not found in the Functions Compartment that you selected.

      4. Select the Function to run.
    10. Click Create Rule at the bottom of the page.
      The details page for the rule you created appears.
  8. Watch for activity for the Cloud Event responder rule with status Succeeded, on either the Problems or Responder Activity page.
    This activity confirms that the Cloud Event responder rule is being triggered and is creating events for that problem in the Events service.