Audit Events

Page last updated:

Overview

Audit events help Cloud Foundry operators monitor actions taken against resources (such as applications) via user or system actions.

Differences from Other Types of Events

Despite being similar in name, audit events are different from Cloud Foundry Usage Events. Unlike usage events, audit events are not suitable for application and service billing.

Another tool to help administrators monitor user actions on Cloud Foundry is Security Event Logging. Unlike Security Event Logs, audit events do not cover all API endpoints, but provide more details about a user’s actions.

View Events

The easiest way to view events for an application is to use the Cloud Foundry CLI:

cf events APP_NAME

This results in the following output:

time                          event                      actor   description
2018-09-04T17:03:49.00-0700   audit.app.droplet.create   admin
2018-09-04T17:03:28.00-0700   audit.app.update           admin   state: STARTED
2018-09-04T17:03:27.00-0700   audit.app.build.create     admin
2018-09-04T17:03:24.00-0700   audit.app.upload-bits      admin
2018-09-04T17:03:24.00-0700   audit.app.map-route        admin
2018-09-04T17:03:24.00-0700   audit.app.create           admin   instances: 1, state: STOPPED, environment_json: [PRIVATE DATA HIDDEN]

This command shows the 50 most recent events for that application. To see more events, or events that are not attributed to an application, use the following Cloud Foundry API endpoint:

GET /v2/events

For documentation about using this endpoint, see the API documentation.

Events are currently only viewable via the v2 api, but user actions in the Cloud Foundry v3 API will still result in audit event creation.

Using Audit Events

The following describes some of the intended use cases of audit events.

Resource History

Usage events allow users, administrators, and operators a view a resource’s history. For example, by looking at usage events for an application, an operator will see information such as when it was last updated, if it has crashed recently, etc.

Querying For Events

A user is able to query the events endpoint with various filters. For example, a user could query for all events of a given type, or all events associated with a resource since a given timestamp.

Allowed filters are enumerated on the API documentation.

External Auditing Warehouse

For auditing and compliance reasons, some operators may wish to keep a record of all audit events that have occured. Because audit events expire and may be purged during a deploy, these operators must maintain an external data warehouse. This way they can store and access events across expiration events and conform to their own compliance requirements.

Types of Audit Events

App Lifecycle (audit.app.*)

  • audit.app.copy-bits
  • audit.app.create
  • audit.app.delete-request
  • audit.app.droplet.create
  • audit.app.droplet.delete
  • audit.app.droplet.download
  • audit.app.droplet.mapped
  • audit.app.map-route
  • audit.app.package.create
  • audit.app.package.delete
  • audit.app.package.download
  • audit.app.package.upload
  • audit.app.process.crash
  • audit.app.process.create
  • audit.app.process.delete
  • audit.app.process.scale
  • audit.app.process.terminate_instance
  • audit.app.process.update
  • audit.app.restage
  • audit.app.ssh-authorized
  • audit.app.ssh-unauthorized
  • audit.app.start
  • audit.app.stop
  • audit.app.task.cancel
  • audit.app.task.create
  • audit.app.unmap-route
  • audit.app.update
  • audit.app.upload-bits

Organization Lifecycle (audit.organization.*)

  • audit.organization.create
  • audit.organization.delete-request
  • audit.organization.update

Route Lifecycle (audit.route.*)

  • audit.route.create
  • audit.route.delete-request
  • audit.route.update

Service Lifecycle (audit.service.*)

  • audit.service.create
  • audit.service.delete
  • audit.service.update

Service Binding Lifecycle (audit.service_binding.*)

  • audit.service_binding.create
  • audit.service_binding.delete

Service Broker Lifecycle (audit.service_broker.*)

  • audit.service_broker.create
  • audit.service_broker.delete
  • audit.service_broker.update

Service Dashboard Client Lifecycle (audit.service_dashboard_client.*)

  • audit.service_dashboard_client.create
  • audit.service_dashboard_client.delete

Service Instance Lifecycle (audit.service_instance.*)

  • audit.service_instance.bind_route
  • audit.service_instance.create
  • audit.service_instance.delete
  • audit.service_instance.share
  • audit.service_instance.unbind_route
  • audit.service_instance.unshare
  • audit.service_instance.update

Service Key Lifecycle (audit.service_key.*)

  • audit.service_key.create
  • audit.service_key.delete

Service Plan Visibility Lifecycle (audit.service_plan_visibility.*)

  • audit.service_plan_visibility.create
  • audit.service_plan_visibility.delete
  • audit.service_plan_visibility.update

Space Lifecycle (audit.space.*)

  • audit.space.create
  • audit.space.delete-request
  • audit.space.update

User Lifecycle (audit.user.*)

  • audit.user.organization_auditor_add
  • audit.user.organization_auditor_remove
  • audit.user.organization_billing_manager_add
  • audit.user.organization_billing_manager_remove
  • audit.user.organization_manager_add
  • audit.user.organization_manager_remove
  • audit.user.organization_user_add
  • audit.user.organization_user_remove
  • audit.user.space_auditor_add
  • audit.user.space_auditor_remove
  • audit.user.space_developer_add
  • audit.user.space_developer_remove
  • audit.user.space_manager_add
  • audit.user.space_manager_remove

User-Provided Service Instance Lifecycle (audit.user_provided_service_instance.*)

  • audit.user_provided_service_instance.create
  • audit.user_provided_service_instance.delete
  • audit.user_provided_service_instance.update

Special Events

  • audit.app.crash
  • blob.remove_orphan

When are events created?

Most events are created when a user acts upon a resource. For example, a user issuing a cf stop APP_NAME command causes an audit.app.stop event to be created and associated with that user.

  • Service events (audit.service*) are created after the service broker has approved an interaction.

  • Crash events (audit.app.crash) are created when Diego marks an application instance as crashed.

  • Blob events (blob.remove_orphan) are created by a daily clean up job and do not represent user action.

Considerations

Audit events can be created at any point during the execution of the action they describe. This means the action associated with the event is not guaranteed to have succeeded.

The audit events table can grow to be very large. So, for performance considerations, certain database migrations may result in the truncation of this table. In other words, this means that a deployment with such a migration will result in a loss of events.

These migrations are exceedingly rare and any release of capi-release that includes one will note this behavior prominently in its release notes.

The order of audit events returned from the API may not match the sequence of events that occurred in the system.

Do not rely on timestamps to sequence events; they may come from different Cloud Controller instances whose times could be slightly mismatched.

Audit events expire after 31 days by default. This is configurable using the capi-release manifest property cc.audit_events.cutoff_age_in_days.

Create a pull request or raise an issue on the source for this page in GitHub