Skip to main content Skip to section navigation
U.S. flag

An official website of the United States government

Auditing activity

Table of Contents

All operations performed on organizations and spaces are logged as events. This includes over 75 distinct events which describe the action taken and the user who authorized the action. Event logs are useful for continuous security, compliance and monitoring actions taken on the system. For example, you can use event logs from cloud.gov to help meet the Audit and Accountability (AU) requirements of the NIST 800-53 family of controls.

To audit events, you’ll need the Org Manager or Org Auditor roles for your organization, as discussed in managing teammates.

There are two way of auditing events. The quickest way is to use the cloud.gov dashboard and navigate to Cloud Foundry on the left navigation. Then select your relevant Organization. From there you can view the users and their roles from the Users menu, or all the recent events from the Events menu. There’s no ability to view logins as such, since they’re global events, not specific to any organization.

Or you use the Cloud Foundry command line tooling. The remainder of this guide uses the cf curl command to issue commands against the /v2/events API. For users who wish to build this into their systems, the API can be accessed using the API Documentation.

To use the following commands you will need:

  • The cf command line tool, as described in our getting started guide
  • The jq command line tool, available for MacOS (brew install jq) or Windows

All Events as JSON

To list all events: cf curl /v2/events

List All User Access Changes as JSON

To list all organization and space events, such as adding a SpaceDeveloper:

export GUID=$(cf org YOUR-ORG --guid)
AUDIT_TYPES="audit.user.space_developer_add,audit.user.space_developer_remove,audit.user.space_auditor_add,audit.user.space_auditor_remove,audit.user.space_manager_add,audit.user.space_manager_remove"
cf curl "/v2/events?q=type+IN+${AUDIT_TYPES}&q=organization_guid:$GUID"

List All User Access Changes as CSV

JSON is useful, but might not be a format the compliance team is familiar with. To print the events as a CSV file instead, first download the jq tool which will transform JSON into CSV. Next add the following command to the end of the first command:

 | jq -c -r '.resources[].entity | [ .timestamp, .actor, .type, .metadata.request.name ] | @csv' | sed -e s/\"//g

For example, the full command would be:

GUID=$(cf org YOUR-ORG --guid)
AUDIT_TYPES="audit.user.space_developer_add,audit.user.space_developer_remove,audit.user.space_auditor_add,audit.user.space_auditor_remove,audit.user.space_manager_add,audit.user.space_manager_remove"
cf curl "/v2/events?q=type+IN+${AUDIT_TYPES}&q=organization_guid:$GUID" | \
  jq -c -r '.resources[].entity | [ .timestamp, .actor, .type, .metadata.request.name ] | @csv' | \
  sed -e s/\"//g

Which will provide a table that can be imported into Excel:

Timestamp User Performing Action Action Type User
2018-02-05T19:36:19Z sandbox-bot audit.user.space_manager_add user.name@example.gov

List All Route Changes as CSV

To list all route changes for a organization:

GUID=$(cf org YOUR-ORG --guid)
AUDIT_TYPES="audit.route.create,audit.route.delete-request,audit.route.update"
cf curl "/v2/events?q=type+IN+${AUDIT_TYPES}&q=organization_guid:${GUID}" | \
   jq -c -r '.resources[].entity | [.timestamp, .actor_username, .type, .actee_name, .metadata.request.app ] | @csv' | \
   sed -e s/\"//g
Timestamp User Performing Action Action Type Route App GUID
2018-02-05T19:36:19Z user.name@example.gov audit.route.update myapproute 7950afc2-dd7b-4a70-80a0-8f7207fd1382

List All Service Instance Events as CSV

To list all events where a service is created, updated, unbound or deleted:

GUID=$(cf org YOUR-ORG --guid)
AUDIT_TYPES="audit.service_instance.create,audit.service_instance.bind_route,audit.service_instance.update,audit.service_instance.unbind_route,audit.service_instance.delete"
cf curl "/v2/events?q=type+IN+${AUDIT_TYPES}&q=organization_guid:$GUID" | \
  jq -c -r '.resources[].entity | [ .timestamp, .actor_username, .type, .actee_name ] | @csv' | \
  sed -e s/\"//g
Timestamp User Performing Action Action Type Service Name
2018-02-05T19:36:19Z user.name@example.gov audit.service_instance.create my-service-name

List All Service Bindings as CSV

To list all events where a service is bound to a application:

GUID=$(cf org YOUR-ORG --guid)
AUDIT_TYPES="audit.service_binding.create,service_instance.bind_route,audit.service_instance.unbind_route"
cf curl "/v2/events?q=type+IN+${AUDIT_TYPES}&q=organization_guid:$GUID" | \
  jq -c -r '.resources[].entity | [.timestamp, .actor_username, .type, .metadata.request.relationships.app.data.guid, .metadata.request.relationships.service_instance.data.guid ] | @csv'  | \
  sed -e s/\"//g
Timestamp User Performing Action Action Type App GUID Service GUID
2018-02-05T19:36:19Z sandbox-bot audit.service_binding.create d613b9a4-a536-47d2-8aa5-b7360c5e2f21 7950afc2-dd7b-4a70-80a0-8f7207fd1382

List All Service Events as JSON

To list all changes to services such as databases and s3 buckets:

GUID=$(cf org YOUR-ORG --guid)
AUDIT_TYPES="audit.service.create,audit.service.delete,audit.service.update,audit.service_binding.create,audit.service_binding.delete,service_instance.bind_route,audit.service_instance.create,audit.service_instance.delete,audit.service_instance.unbind_route,audit.service_instance.update"
cf curl "/v2/events?q=type+IN+${AUDIT_TYPES}&q=organization_guid:$GUID"

cloud.gov

An official website of the U.S. General Services Administration

Looking for U.S. government information and services?
Visit USA.gov