How to consume audit logs from Elastic Cloud Enterprise

In many organisations, the Elastic Stack is run on the Elastic Cloud Enterprise (ECE) platform. This platform enables teams to create, manage, and update Elastic Stack without any prior knowledge.

Since this is a powerful tool, organisations want to be informed about changes in the platform.  Many users might access this web user interface (UI) and create deployments, upgrade them, and add or remove specific settings. All the data is inside the built-in logging and metrics clusters; thus, we can leverage it and use Kibana rules and alerting to create alerts for specific events.

Below, I’ll cover how to use the audit functionality of ECE to be alerted when a critical event happens, as well as review topics and questions that often come up in the audit process.

[Related article: 4 ways the Elastic Platform in the cloud multiplies the benefits of search-powered data analytics solutions]

An API-first approach

Luckily ECE is built upon an API-first approach. Thus every click we do in a UI is backed by an API (application programming interface). Those API calls go against a proxy, and this proxy logs every request in the internal logging and metrics cluster and stores them inside the Kibana data view called services-logs.

Generally speaking, our API is always designed to be prefixed by /api/v1.

Who logged in and when?

Any login goes against the /auth/_login URL using a POST request. A sample document looks like this:

It contains the URL in the path field inside the payload, and we know the username. Don’t worry — the password is permanently excluded. At the bottom of the message, we have a return_code. If this is 200, we can be sure the login worked. If the return_code is missing, the API did not answer, which means a login was tried but was unsuccessful.

Based on the document above, we can create a simple alerting rule to get notified if someone tries to login with philipp and fails at least three times within a certain time.

A deployment was added, altered, and deleted

This section covers everything that is happening to a deployment. Any change — like adding nodes, upgrading to a newer version, or removing nodes — will trigger a plan change, which also goes through an API. The general API for all deployment-related tasks is the following /deployments.

A cluster creation is defined by running a POST against /deployments with a payload that describes a cluster. We won’t go into the payload details, and examples can be found in our documentation. The exciting part is the admin_id and the return_code. This clearly states that philipp created a new deployment. The deployment name is in the payload.name, demo. The return_code is 201 (created) consequently, the API call is successful, and the deployment is created.

Now that the deployment is created, changes will inadvertently be made to it. We can identify any change to a target deployment using the same approach as above. Changes have identical endpoint /deployments instead of a POST, and they leverage PUT and contain the deployment id as a URL parameter. Don’t worry, you don’t need to have a lookup table of deployment ids to deployment names, as the payload contains the name.

When I delete a deployment, I need the deployment id, the DELETE HTTP verb, and the same /deployments endpoint. Sadly, our API does not store the deployment's name in this call, and you can search using the deployment id to get back the name.

Using Kibana rules and alerting, it is easy to handcraft Elasticsearch queries or use threshold alerts to be alerted on certain events.

User created, modified, and deleted

If the user API endpoint is /users, and creating a user is similar to deployment, a POST request is used.

This payload contains the user_name, the associated roles, the full_name, and an email. A common trigger for an alert is when a new ece_platform_admin is assigned to a new or existing user.

Changing an existing user is a PATCH call against the /users/id endpoint, and the id is the user_name. In the example below, the user philipp was modified to be an ece_deployment_manager.

Password changes for existing users

In ECE, any admin can change the password of an existing user. This is similar to a user change, as it is a change request against the user's password. Password change is a PATCH call against the /users/id endpoint. The id is the user_name. The crucial difference is that inside the payload.security, a password field exists. The admin_id, as in the other payloads, explains which users initiated the password change.

Role mappings

Many organisations incorporate login from ECE with a third-party authentication realm, like Active Directory. How to implement it is documented here. The vital part is that we can map groups to roles. Role mapping alterations are a PUT request against the /regions/ece-region/platform/configuration/security API. If someone maps a widely available group as an ECE admin, this should trigger an alert. In the payload, there is payload.role_mappings object that contains the necessary information.

Next step: Dashboard

In this blog, we showed how easily one could use the audit functionality of ECE to be alerted when a critical event happens. When combining all those events, we can build a dashboard to watch what is happening in our ECE.

To learn more about building such a dashboard, read New in Kibana: How we made it easier to manage visualizations and build dashboards.