Integrate Oracle Cloud Guard with External Systems Using OCI Events and Functions

Oracle Cloud Guard service was released recently. It helps customers monitor their OCI resources and maintain a strong security posture. For people who are new to Cloud Guard, following are some resources for learning about Cloud Guard concepts and use-cases:

• Oracle Cloud Guard
• Oracle Cloud Guard Service Documentation

And some blog posts:

• Automating Cloud Security with Security Posture Management
• Discovering and fixing weak cloud security posture with Oracle Cloud Guard
• How Oracle is helping you maintain a strong security posture in the cloud 

Cloud Guard continuously collects and analyzes configuration, audit logs and other information in a customer’s tenancy and reports its findings as “Problems” based on its Detector Recipes. Customers can then work on addressing these findings to improve their security posture by either using Responder Recipes or other means such as manual or programmatic ways.

 Customers may have use-cases to integrate Cloud Guard with external systems. For example, some customers may want to export this data out to their central SIEM system for further analyses and actions. Others may want to create tickets in their service management systems for addressing the identified problems.

Customers could meet such use-cases by leveraging the rich integration capabilities provided by Cloud Guard and other OCI services. Cloud Guard also provides APIs ad SDKs that could be used for integration.

In this blog I would like to describe how we can leverage OCI Event Service and Oracle Functions to meet such use-cases. Readers are expected to be familiar with Cloud Guard, Event Service and Functions concepts and how they work. While I provide links to documentation and other resources, this blog is not meant to be an introduction to these topics.

Functions are small bundles of code provided by customers that run on Oracle managed infrastructure so that they don’t have to worry about managing this infrastructure. With Oracle Functions, customers can develop their applications in Python, Java, Node.js and other languages. Customers also have the capability to invoke OCI and third party APIs from within functions. Functions can be used to connect to and integrate with external third-party systems to implement a variety of use-cases. Here are a couple of examples:

• When Cloud Guard triggers detects a problem, transform and send the problem data to an external SIEM system like (Splunk, IBM QRadar etc.) over syslog or HTTP
• For Critical events, create a ticket in service management system like Oracle Service Cloud (formerly RightNow) or Service Now.

Solutions describing these and other specific use-cases deserve a blog-post of their own. The purpose of this blog-post is to provide you a general idea of how to design such solutions, the components involved and how they fit together. Let us start with a simple architecture diagram:

First, I want to describe the configuration needed to wire the solution and then in the end we will look at some salient steps needed for developing a function. Lets’ get started.

There are two different types of rules in a responder recipe – Notification and Remediation. At present, “Cloud Event” is the only rule of type notification. Rest all are of type remediation. There is no configuration associated with the Cloud Event rule. It can either be enabled or disabled. For the solution that is described in this blog post, it needs to be kept enabled.

Cloud Guard allows customers to define their own recipes. This can be done by cloning the Oracle managed recipes, configuring/customizing them and associating them with Targets. If you are creating your own responder recipes, make sure to keep the Cloud Event rule enabled.

Cloud Guard sends an event to the OCI Event Service for every problem detected in the scope of a target. Once an event is handed off to the Event Service, Cloud Guard’s job is done, and the Event Service takes over. Depending on the defined configuration that a customer has, the Event Service then processes the event.

As an example, for this blog, I want to act on all problems detected by Cloud Guard for resources that reside in a specific compartment. The following screen capture shows how the Event Matching part of Event Rule configuration for this use-case looks like in OCI console:

Event Service supports the following actions when an event matches a rule:

• Sending the event data to a Notifications Topic,
• Writing the event data to an OCI Stream
• Invoking an Oracle Function with the event data

As an example, in the following screenshot, the event service will invoke a serverless function, send notification to a topic and write data to a stream.

That completes the necessary configuration. Lets’ look at how a sample event for a Cloud Guard Problem looks like. The following screen capture shows that the event envelope contains data for a Cloud Guard Problem and the corresponding resource in the “data” field which in turn contains “additionalDetails” field. Some fields that may be of significance for various use-cases are highlighted:

Now lets’ look at how to develop a sample Python based function to process this data. Please note that OCI supports writing functions in other languages like Java, Node.js etc as well

In the remainder of this blog post, I am going to describe the important steps of developing a function. It is not meant to be a complete tutorial on Oracle Functions. Readers who are new to Oracle Functions could refer to a quick start tutorial and service documentation for more information.

The function is invoked with data from the event as value of parameter “data” of the handler function. This is how we can get a JSON representation of the event data:

funDataStr = data.read().decode('utf-8')
funData =  json.loads(funDataStr)

Function configuration could be obtained from the "ctx" parameter of the handler function as follows:

config = ctx.Config()

We can store and pass various configuration items which are key and value pairs of type string. The obtained configuration is a Python dictionary like object.

In order to invoke OCI APIs from inside a function we can use a resource principal like this:

ociResPrncplSigner = oci.auth.signers.get_resource_principals_signer()
ociObjStoreSvc = oci.object_storage.ObjectStorageClient(config={}, signer=ociResPrncplSigner)

As can be seen from the screen capture showing a Cloud Guard Problem above, the details of a problem are inside "additionalDetails" element which itself is inside the "data" element. Usual JSON manipulation techniques could be used to extract the values of various fields and perform transformations/analyses to drive further decisions.

Customers can invoke APIs for external services from inside functions in order to achieve various integration use-cases. For example - 

• If the riskLevel is CRITICAL, calling the public APIs for a service management system to open a ticket with relevant details populated from other fields in the problem.
• Calling an external SIEM system's APIs to send the entire data across for further analysis. The data can be enriched by using OCI APIs that could be called as I have shown above.

That is it. Hopefully this gives you a good mental model of the design needed to build a solution that meets your use-case.