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:

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

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

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

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"