IBM Cloud Docs
Enabling event notifications for Security and Compliance Center

Enabling event notifications for Security and Compliance Center

As an administrator of IBM Cloud® Security and Compliance Center, you might want to send notifications of events in Security and Compliance Center to other users, or human destinations, by using email, SMS, or other supported delivery channels. Additionally, you might want to send these notifications of events to other applications to build logic by using event-driven programming that uses webhooks, for example. This action is made possible by the integration between Security and Compliance Center and IBM Cloud® Event Notifications.

Events for Security and Compliance Center

Review the following sections to learn about the events that are generated by specific Security and Compliance Center components.

Table 1. List of events that apply to Security and Compliance Center
Event type Subtype Description
com.ibm.cloud.compliance.test An event is sent when you test the connection between Security and Compliance Center and a connected Event Notifications service instance.
com.ibm.cloud.compliance.posture posture-scan-completed An event is sent when a scan is complete.
com.ibm.cloud.compliance.posture posture-scan-failure-threshold-limit-exceeds An event is sent when your specified threshold of failed controls is met.
com.ibm.cloud.compliance.posture posture-scan-new-resource-in-inventory An event is sent when a new resource is found in your inventory.

Enabling notifications

Events that are generated by the Security and Compliance Center can be forwarded to an Event Notifications service instance that is available in the same account. To get started, be sure that you have:

Connecting to Event Notifications in the console

Before you can enable notifications for Security and Compliance Center, be sure that you have an Event Notifications service instance that is in the same account. Then, you can use the Settings > Event Notifications section in the Security and Compliance Center UI to connect the services.

The image shows the Event Notifications screen in the Security and Compliance Center UI.
Figure 1. Connecting to Event Notifications

  1. In the console, click the Menu icon Menu icon > Security and Compliance.

  2. In the Security and Compliance Center navigation, click Settings.

  3. In the Event Notifications section, and click Connect.

  4. In the side panel, review the source details for the connection. Optionally, provide a description.

  5. Select the resource group and Event Notifications service instance that you want to connect.

    If an IAM authorization between Security and Compliance Center and Event Notifications doesn't exist in your account, a dialog is displayed. Follow the prompts to grant access between the services.

    1. To grant access between Security and Compliance Center and Event Notifications, click Authorize.
    2. In the side panel, select Event Notifications as the target service.
    3. From the list of instances, select the Event Notifications service instance that you want to authorize.
    4. Select the Event Source Manager role.
    5. Click Review.
    6. Click Assign.
  6. To confirm the connection, click Connect.

    A success message is displayed to indicate that Security and Compliance Center is now connected to Event Notifications. If you need to disconnect from Event Notifications later, you can use the options menu options icon > Disconnect to remove the Security and Compliance Center as a source service in the Event Notifications instance.

    If you choose to disconnect Event Notifications, do not delete the IAM authorization between Security and Compliance Center and Event Notifications. The Security and Compliance Center uses the existing authorization to unregister from Event Notifications. If an Event Notifications instance is deleted, any authorizations that exist between the service and Security and Compliance Center are also deleted by IAM.

Connecting to Event Notifications with the API

Before you can enable notifications for Security and Compliance Center, be sure that you have an Event Notifications service instance that is in the same account. Then, you can connect to Event Notifications programmatically by calling the Security and Compliance Center API.

The following example shows a query that you can use to register your Security and Compliance Center source details with Event Notifications.

You can find the event_notifications_instance_crn value in the console by going to the Resource list and clicking the Event Notifications instance row.

curl -X PATCH 
  --location --header "Authorization: Bearer {IAM_token}" 
  --header "Accept: application/json" 
  --header "Content-Type: application/json-patch+json" 
  --data '{ 
            "event_notifications": { 
              "instance_crn": "crn:v1:staging:public:event-notifications:us-south:a/130003ea8bfa43c5aacea07a86da3000:1c858449-3537-45b8-9d39-2707115b4cc7::" 
              }, 
            "object_storage": { 
              "instance_crn": "crn:v1:staging:public:cloud-object-storage:global:a/130003ea8bfa43c5aacea07a86da3000:1c858449-3537-45b8-9d39-2707115b4cc7::", 
              "bucket": "scc-bucket" 
            } 
          }' "
  https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3/settings"
eventNotificationsModel := &securityandcompliancecenterapiv3.EventNotifications{
  InstanceCrn: &eventNotificationsCrnForUpdateSettingsLink,
  SourceDescription: core.StringPtr("This source is used for integration with IBM Cloud Security and Compliance Center."),
  SourceName: core.StringPtr("compliance"),
}

objectStorageModel := &securityandcompliancecenterapiv3.ObjectStorage{
  InstanceCrn: &objectStorageCrnForUpdateSettingsLink,
  Bucket: &objectStorageBucketForUpdateSettingsLink,
  BucketLocation: &objectStorageLocationForUpdateSettingsLink,
}

updateSettingsOptions := securityAndComplianceCenterApiService.NewUpdateSettingsOptions()
updateSettingsOptions.SetEventNotifications(eventNotificationsModel)
updateSettingsOptions.SetObjectStorage(objectStorageModel)
updateSettingsOptions.SetXCorrelationID("1a2b3c4d-5e6f-4a7b-8c9d-e0f1a2b3c4d5")

settings, response, err := securityAndComplianceCenterApiService.UpdateSettings(updateSettingsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(settings, "", "  ")
fmt.Println(string(b))
EventNotifications eventNotificationsModel = new EventNotifications.Builder()
  .instanceCrn(eventNotificationsCrnForUpdateSettingsLink)
  .sourceDescription("This source is used for integration with IBM Cloud Security and Compliance Center.")
  .sourceName("compliance")
  .build();
ObjectStorage objectStorageModel = new ObjectStorage.Builder()
  .instanceCrn(objectStorageCrnForUpdateSettingsLink)
  .bucket(objectStorageBucketForUpdateSettingsLink)
  .bucketLocation(objectStorageLocationForUpdateSettingsLink)
  .build();
UpdateSettingsOptions updateSettingsOptions = new UpdateSettingsOptions.Builder()
  .eventNotifications(eventNotificationsModel)
  .objectStorage(objectStorageModel)
  .xCorrelationId(xCorrelationIdLink)
  .build();

Response<Settings> response = securityAndComplianceCenterApiService.updateSettings(updateSettingsOptions).execute();
Settings settings = response.getResult();

System.out.println(settings);
// Request models needed by this operation.

// EventNotifications
const eventNotificationsModel = {
  instance_crn: eventNotificationsCrnForUpdateSettingsLink,
  source_description: 'This source is used for integration with IBM Cloud Security and Compliance Center.',
  source_name: 'compliance',
};

// ObjectStorage
const objectStorageModel = {
  instance_crn: objectStorageCrnForUpdateSettingsLink,
  bucket: objectStorageBucketForUpdateSettingsLink,
  bucket_location: objectStorageLocationForUpdateSettingsLink,
};

const params = {
  eventNotifications: eventNotificationsModel,
  objectStorage: objectStorageModel,
  xCorrelationId: xCorrelationIdLink,
};

let res;
try {
  res = await securityAndComplianceCenterApiService.updateSettings(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
event_notifications_model = {
  'instance_crn': event_notifications_crn_for_update_settings_link,
  'source_description': 'This source is used for integration with IBM Cloud Security and Compliance Center.',
  'source_name': 'compliance',
}

object_storage_model = {
  'instance_crn': object_storage_crn_for_update_settings_link,
  'bucket': object_storage_bucket_for_update_settings_link,
  'bucket_location': object_storage_location_for_update_settings_link,
}

response = security_and_compliance_center_api_service.update_settings(
  event_notifications=event_notifications_model,
  object_storage=object_storage_model,
  x_correlation_id=x_correlation_id_link,
)
settings = response.get_result()

print(json.dumps(settings, indent=2))

A successful response returns the CRN value of your connected Event Notifications and Cloud Object Storage service instances. For more information about the required and optional request parameters, see the API docs.

Connecting to Event Notifications with the CLI

Before you can enable notifications for Security and Compliance Center, be sure that you have an Event Notifications service instance that is in the same account. Then, you can connect to Event Notifications programmatically by using the Security and Compliance Center CLI.

The following example shows a command that you can use to register your Security and Compliance Center source details with Event Notifications. When you use the CLI, replace the ID variables and IAM token with the values that are specific to your account. For more information, see the CLI reference.

ibmcloud security-compliance settings update     
  --event-notifications='{
    "instance_crn": "crn:v1:staging:public:event-notifications:us-south:a/ff88f007f9ff4622aac4fbc0eda36255:7199ae60-a214-4dd8-9bf7-ce571de49d01::", 
    "updated_on": "2019-01-01T12:00:00.000Z", 
    "source_id": "crn:v1:staging:public:event-notifications:us-south:a/ff88f007f9ff4622aac4fbc0eda36255:b8b07245-0bbe-4478-b11c-0dce523105fd::", 
    "source_description": "This source is used for integration with IBM Cloud Security and Compliance Center.", 
    "source_name": "compliance"
    }'     
  --object-storage='{
    "instance_crn": "crn:v1:staging:public:cloud-object-storage:global:a/ff88f007f9ff4622aac4fbc0eda36255:7199ae60-a214-4dd8-9bf7-ce571de49d01::", 
    "bucket": "px-scan-results", 
    "bucket_location": "us-south", 
    "bucket_endpoint": "exampleString", 
    "updated_on": "2019-01-01T12:00:00.000Z"
    }'     
  --x-correlation-id=1a2b3c4d-5e6f-4a7b-8c9d-e0f1a2b3c4d5     
  --x-request-id=exampleString

You can find the event_notifications_instance_crn value in the console by going to the Resource list and clicking the Event Notifications instance row.

Sending a test event to Event Notifications from the UI

After you enable notifications for Security and Compliance Center, test your connection to ensure that the events that are generated by Security and Compliance Center are being forwarded to Event Notifications.

Before you can send a test Security and Compliance Center event, you must have topics, destinations, and subscriptions created in your Event Notifications instance. Be sure that the Test configuration event type (com.ibm.cloud.compliance.test) is included as a condition in your Event Notifications topic.

  1. In the Security and Compliance Center UI, click Settings.

  2. In the Event Notifications section, click Send test event.

    A success message is displayed to indicate that the test event was forwarded successfully to Event Notifications.

Sending a test event to Event Notifications by using the API

After you enable notifications for Security and Compliance Center, test your connection to ensure that the events that are generated by Security and Compliance Center are being forwarded to Event Notifications.

Before you can send a test Security and Compliance Center event, you must have topics, destinations, and subscriptions created in your Event Notifications instance. Be sure that the Test configuration event type (com.ibm.cloud.compliance.test) is included as a condition in your Event Notifications topic.

The following example shows a query that you can use to send a test event from the Security and Compliance Center to Event Notifications.

curl -X POST 
  --location --header "Authorization: Bearer {iam_token}" 
  --header "Accept: application/json"
  "https://us-south.compliance.cloud.ibm.com/instances/{instance_id}/v3/test_event"
(securityAndComplianceCenterApi *SecurityAndComplianceCenterApiV3) PostTestEvent(postTestEventOptions *PostTestEventOptions) (result *TestEvent, response *core.DetailedResponse, err error)
PostTestEventOptions postTestEventOptions = new PostTestEventOptions.Builder()
  .xCorrelationId(xCorrelationIdLink)
  .build();

Response<TestEvent> response = securityAndComplianceCenterApiService.postTestEvent(postTestEventOptions).execute();
TestEvent testEvent = response.getResult();

System.out.println(testEvent);
const params = {
  xCorrelationId: xCorrelationIdLink,
};

let res;
try {
  res = await securityAndComplianceCenterApiService.postTestEvent(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
response = security_and_compliance_center_api_service.post_test_event(
  x_correlation_id=x_correlation_id_link,
)
test_event = response.get_result()

print(json.dumps(test_event, indent=2))

A successful response returns {"success": true} to indicate that a test event was forwarded successfully to your connected Event Notifications service instance . For more information, see the API docs.

Sending a test event to Event Notifications by using the CLI

After you enable notifications for Security and Compliance Center, test your connection to ensure that the events that are generated by Security and Compliance Center are being forwarded to Event Notifications.

Before you can send a test Security and Compliance Center event, you must have topics, destinations, and subscriptions created in your Event Notifications instance. Be sure that the Test configuration event type (com.ibm.cloud.compliance.test) is included as a condition in your Event Notifications topic.

The following example shows a query that you can use to send a test event from the Security and Compliance Center to Event Notifications. For more information, view the CLI reference.

ibmcloud security-compliance settings post-test-event     
--x-correlation-id=1a2b3c4d-5e6f-4a7b-8c9d-e0f1a2b3c4d5     
--x-request-id=exampleString

Delivering notifications to select destinations

After you enable notifications for Security and Compliance Center, create topics and subscriptions in Event Notifications so alerts can be forwarded and delivered to your selected destinations.

For a complete list of supported destinations, see the Event Notifications documentation.

Email notifications

You can use the IBM Cloud email service as a delivery channel for Security and Compliance Center event notifications. Create an Event Notifications subscription between an existing topic and the IBM Cloud email service to forward your alerts to various recipients by email.

An email from IBM Cloud that contains information about a Security and Compliance Center event resembles the following example:

Subject: Validation completed: my-test-validation-scan
Body: The following validation scan was successfully completed in the Security and Compliance Center: my-test-validation-scan. You can view the scan results from the Security and Compliance Center in the console. For more information, check out the docs.

To receive detailed information about an event notification in your email, select the Add notification payload option when you create an Event Notifications subscription. Your email displays the notification payload details that are associated with the event.

Webhooks

You can configure a webhook destination so that the properties of an incoming notification can be used programmatically by an app or service. For more information, check out the Event Notifications documentation.

Notification payload details

Successful events that are generated by a Security and Compliance Center component contain various fields that help you to identify the source and details of an event.

Event notifications from Security and Compliance Center contain only metadata properties, such as names or identifiers of resources. Sensitive data, for example API keys or passwords, are not included in generated events.

The metadata properties that are sent to Event Notifications vary depending on the event type and subtype. For example, if an com.ibm.cloud.compliance.posture:posture-scan-completed event takes place, Security and Compliance Center sends a notification payload to Event Notifications that is similar to the following example.

{
    "action": "Validation completed",
    "summary": "my-test-scan",
    "scope": "my-test-scope",
    "profile": "CIS IBM Foundations Benchmark 1.0.0",
    "start_time": "2021-11-24 13:46:21.672",
    "end_time": "2021-11-24 13:46:21.672"
}

Review the following table for more information about event notification properties.

Table 2. Properties in an event notification payload
Property Description
action The type of event that triggered a notification.
summary The name of the validation scan.
scope The name of the scope that is associated with the scan.
profile The name of the profile that is associated with the scan.
start_time The date and time the scan started.
end_time The date and time the scan completed.