Retrieving audit events

The Control Plane provides access to retrieve audit events in two ways: through a public listing API offered by the CDP Control Plane audit service, and through export to cloud storage.

Public listing API

The Control Plane audit service offers a basic API endpoint for listing audit events. The API accepts the following parameters:
Parameter name Description Required?
from timestamp Beginning of time range within which to retrieve audit events Y
to timestamp End of time range within which to retrieve audit events Y
request ID Request ID to filter on N
event source Event source to filter on N
page size Number of audit events to return in one response; maximum and default value = 20 N
page token Opaque value from previous listing call used to retrieve the next page N

The result of a listing call is a set of audit events, possibly along with a page token value. In order to get a listing of the next page of audit events, pass the token value in another call, leaving other parameters the same.

Calls to the listing API endpoint are protected as follows:

  • The caller must have the audit/listAuditEvents right.

When an account is first created in the control plane, it is not configured with the information needed to archive audit events to cloud storage. You can use the control plane without configuring archiving, but audit events are subject to purging after 90 days. So, it is important to configure archiving to avoid data loss.

Access to the listing API endpoint is strictly throttled, to prevent the critical audit service from becoming too busy to accept audit events from Control Plane services. The primary means of retrieving audit events is intended to be through cloud storage.

CDP CLI Syntax

To call the API endpoint for listing audit events, use a command line like the following, which includes examples of all of the required options:

cdp audit list-events 
  --from-timestamp 2020-03-01T00:00:00Z
  --to-timestamp 2020-04-01T00:00:00Z

To additionally filter by request ID, use the --request-id option. To additionally filter by event source, use the --event-source option. Paging options work the same way as with other CDP CLI commands.