Configuring Notifications

Use the Events and Notifications services to send notifications, whenever Cloud 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 Cloud Guard Events topic 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

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.

Cloud Guard Events

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

Cloud Guard resources that emit events:

Note

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

To receive notifications when a responder recipe is triggered, you must perform the following tasks (for details, see Notifying through Email or Slack or Notifying through OCI Functions):

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

Cloud Guard Event Types

These are the event types that Cloud Guard emits:


Friendly Name	Trigger	Event Type
Cloud Guard - Announcements	Cloud Guard announces a new feature	`com.oraclecloud.cloudguard.announcements`
Cloud Guard - Status	Cloud Guard's status (enabled/disabled) changes	`com.oraclecloud.cloudguard.status`

The following table summarizes the actions, status, and reasons for Cloud Guard event types.


Event Type	Action Leading to Event	Status Field in Event Details	Reason Field in Event Details
Cloud Guard - Announcements	Cloud Guard announces a new feature	Not applicable	Varies with announcement - example: `New Detector Rule added by Cloud Guard`
Cloud Guard - Status	User (`actor`) disabled Cloud Guard	`CLOUDGUARD_DISABLED`	`Cloud Guard is disabled`

Problem Event Types

These are the event types that problems emit:


Friendly Name	Trigger	Event Type
Detected - Problem	Cloud Guard detects a problem	`com.oraclecloud.cloudguard.problemdetected`
Dismissed - Problem	A user dismisses a problem	`com.oraclecloud.cloudguard.problemdetected`
Problem Threshold Reached	Certain threshold limits are reached, because of excessive audit signals from services such as VCN or Identity.	`com.oraclecloud.cloudguard.problemthresholdreached`
Remediated-Problem	A responder configured to automatically remediate a detected problem performs the remediation.	`com.oraclecloud.cloudguard.problemremediated`

The following table details the different actions, status, and reasons for the Remediated - Problem 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`

Detected - Problem Example

This is a reference event for detected problems:

{
 "eventType" : "com.oraclecloud.cloudguard.problemdetected",
 "cloudEventsVersion" : "0.1",
 "eventTypeVersion" : "2.0",
 "source" : "CloudGuardResponderEngine",
 "eventTime" : "2020-09-02T18:45:39Z",
 "contentType" : "application/json",
 "data" : {
   "compartmentId" : "ocid1.compartment.oc1..<unique_ID>",
   "compartmentName" : "compartment_name",
   "resourceName" : "problem_name",
   "resourceId" : "ocid1.cloudguardproblem.oc1.iad.<unique_ID>",
   "additionalDetails" : {
     "tenantId" : "ocid1.tenancy.oc1...<unique_ID>",
     "problemDescription" : "problem_description",
     "riskLevel" : "LOW",
     "problemRecommendation" : "example_recommendation",
     "status" : "OPEN",
     "problemType" : "problem_type",
     "resourceName" : "resource_name",
     "resourceId" : "ocid1.vcn.oc1.iad.<unique_ID>",
     "resourceType" : "resource_type",
     "targetId" : "ocid1.cloudguardtarget.oc1..<unique_ID>",
     "labels" : "label1, label2",
     "firstDetected" : "2020-09-02T18:44:44.568Z",
     "lastDetected" : "2020-09-02T18:44:44.568Z",
     "region" : "us-ashburn-1"
   }
 },
 "eventID" : "<unique_ID>",
 "extensions" : {
   "compartmentId" : "ocid1.compartment.oc1..<unique_ID>"
 }
}

Remediated-Problem Example

This is a reference event for remediated problems:

{
 "eventType" : "com.oraclecloud.cloudguard.problemremediated",
 "cloudEventsVersion" : "0.1",
 "eventTypeVersion" : "2.0",
 "source" : "CloudGuardResponderEngine",
 "eventTime" : "2020-09-02T18:47:00Z",
 "contentType" : "application/json",
 "data" : {
   "compartmentId" : "ocid1.compartment.oc1..<unique_ID>",
   "compartmentName" : "compartment_name",
   "resourceName" : "problem_name",
   "resourceId" : "ocid1.cloudguardproblem.oc1.iad.<unique_ID>",
   "additionalDetails" : {
     "tenantId" : "ocid1.tenancy.oc1...<unique_ID>",
     "problemDescription" : "problem_description",
     "riskLevel" : "CRITICAL",
     "problemRecommendation" : "example_recommendation",
     "status" : "RESOLVED",
     "problemType" : "problem_type",
     "resourceName" : "resource_name",
     "resourceId" : "ocid1.vcn.oc1.iad.<unique_ID>",
     "resourceType" : "resource_type",
     "targetId" : "ocid1.cloudguardtarget.oc1..<unique_ID>",
     "labels" : "label1, label2",
     "firstDetected" : "2020-09-02T18:44:44.145Z",
     "lastDetected" : "2020-09-02T18:44:44.145Z",
     "region" : "us-ashburn-1",
     "responderRuleId" : "responder_rule_id"
   }
 },
 "eventID" : "<unique_ID>",
 "extensions" : {
   "compartmentId" : "ocid1.compartment.oc1..<unique_ID>"
 }
}

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.

In Cloud Guard, ensure that the Cloud Event rule is enabled for the responder recipe for which you want to receive notifications.
1. Open the navigation menu and click Identity & Security. Under Cloud Guard, click Recipes. On the Recipes page, click Responder Recipes.
2. Click the name of the recipe for which you want to configure notifications.
3. On the Recipe Details 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 its Actions menu and select Edit.
  2. In the Edit Responder Rule dialog box, drop down the Status list and select Enabled.
  3. Click Save.
In Cloud Guard, ensure that the target for which you want to receive notifications has the user-managed (cloned) responder recipe that you just checked attached, with automatic execution enabled.
1. Open the navigation menu and click Identity & Security. Under Cloud Guard, click Configuration. On the Configuration page, click Targets.
2. On the Targets page, in the Target Name column, click the name of the target covering the compartments for 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 its Actions 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 enabled and 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 its Actions 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 checkbox.
    3. Click Save.
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 panel:
  1. Enter a Name for the topic.
    Avoid entering confidential information.
  2. Optional: Enter a Description for the topic.
    Avoid entering confidential information.
  3. Optional: Specify tagging information.
  4. Click Create.
    The topic you created appears in the list on the Topics page.
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 panel:
  1. Set Protocol for email or Slack notification:
    - Email:
      
      Set Protocol to Email.
      
      Enter the email address that should receive the notifications.
    - Slack:
      
      Set Protocol to Slack.
      
      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.

In the Events service, configure a rule to specify conditions under which a notification is sent.

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.
From the Oracle Cloud menu, select Observability & Management , then click Events Service.
Under List Scope, ensure that the Compartment selected is either the compartment where the resource exists, or a parent of that compartment.
Click Create Rule.
On the Create Rule page, enter a Display Name for the rule.
Avoid entering confidential information.
(Optional) Enter a Description for the rule.
Avoid entering confidential information.
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.
  - Cloud Guard - Announcements
  - Cloud Guard - Status
  - Detected - Problem
  - Remediated - Problem
  - Problem Threshold Reached

To add an attribute filter to the rule, in the Rule Conditions section, click Another Condition.

For example, you could limit:

Cloud Guard - Announcements to only new detector rule announcements.
Cloud Guard - Status to only disabling of Cloud Guard.
Detected - Problem to only problems with risk level 4.

Note

Multiple rules are ANDed to limit the scope for which a notification is sent. To trigger a notification, all conditions must be true.

Set Condition to Attribute.

Set Attribute Name to the parameter on which you want to filter.

For example:

To Limit...	Set Attribute to...	Attribute Name entry...
Cloud Guard - Announcements to only new detector rule announcements	announcement	`DETECTOR_RULE_ADDED`
Cloud Guard - Status to only disabling of Cloud Guard	status	`CLOUDGUARD_DISABLED`
Detected - Problem to risk level 4	riskLevel	`4`

Cloud Guard - Announcements to only new detector rule announcements.
Cloud Guard - Status to only disabling of Cloud Guard.
Detected - Problem to only problems with risk level 4.

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

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.
To add another rule condition to further limit the scope for which a notification is sent, click Another Condition, then repeat the preceding substeps.

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.
Click Create Rule at the bottom of the page.
The details page for the rule you created appears.

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.

Familiarize yourself with Oracle Functions.
If you are working with Oracle Functions for the first time:
- Review the Overview of Functions documentation.
- Ensure that your environment is set up correctly, as described in Preparing for Oracle Functions.
- In particular, review the tasks involved in Creating Applications and Creating and Deploying Functions.
- Check out the available Oracle Functions Quick Start Guides.

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

Create the function application code.

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

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.
Obtain the function configuration from the ctx parameter of the handler function:
```
config = ctx.Config()
```

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)

Use standard JSON techniques to extract the values of various fields from within the data element.
Then use other standard manipulation techniques to perform transformations and analyses to support whatever logic you require to complete the function.
(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

Create an application for your function and locate it in the compartment from which you plan to call the function.
See Creating Applications.
In Cloud Guard, ensure that the Cloud Event rule is enabled for the responder recipe for which you want to receive notifications.
1. Open the navigation menu and click Identity & Security. Under Cloud Guard, click Recipes. On the Recipes page, click 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 its Actions menu and select Edit.
  2. In the Edit Responder Rule dialog box, drop down the Status list and select Enabled.
  3. Click Save.
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. Open the navigation menu and click Identity & Security. Under Cloud Guard, click Configuration. On the Configuration page, click 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 its Actions 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 its Actions 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 checkbox.
    3. Click Save.
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.
  
  Note
  
  The Cloud Guard reporting region is NOT the same thing as the OCI home region.
  
  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.
  Avoid entering confidential information.
6. (Optional) Enter a Description for the rule.
  Avoid entering confidential information.
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. 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.
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.