Retrieving audit events

The Control Plane provides access to view/retrieve audit events and archive history in two ways: through the Management Console UI and through the CDP API offered by the CDP Control Plane audit service.

Required role: PowerUser

Management Console UI

With the required permissions, you can view both the audit events and the audit archive history in the Management Console UI.

A list of both the audit events and the archive history are accessible from the main left-hand navigation menu under Audit:

The Audit Events page contains a record of all the events that generate an audit record, along with their name, origin, source, and timestamp.

The Archive History page contains a record of each archive batch that is sent to cloud storage, along with details related to that batch, such as the status, number of events archived, and time of both creation and archive. The archive history gives greater visibility into the audit process and will alert you if an archive run fails to 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 = 50	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.

You can also use the CDP CLI to view the audit archive history. The following command returns the most recent audit archive exports:

cdp audit list-recent-archive-runs