Events

Events are arbitrary, non-secret data that can be exchanged between producers (Vault and plugins) and subscribers (Vault components and external users via the API).

Event types

Internal components of Vault as well as external plugins can generate events. These are published to "event types", sometimes called "topics" in some event systems. All events of a specific event type will have the same format for their additional metadata field.

The following events are currently generated by Vault and its builtin plugins automatically:

Event format

Events may be formatted in protobuf binary format or as JSON. See EventReceived in sdk/logical/event.proto in the relevant Vault version for the protobuf schema.

When formatted as JSON, the event conforms to the CloudEvents specification.

• id (string) - CloudEvents unique identifier for the event. The id is unique for each event, and events with the same id represent the same event.

• source (string) - CloudEvents source, which is currently https://vaultproject.io.

• specversion (string) - The CloudEvents specification version this conforms to.

• type (string) - CloudEvents type this event corresponds to, which is currently always *.

• datacontenttype (string) - CloudEvents content type of the event, which is currently always application/json.

• time (string) - ISO 8601-formatted timestamp for when the event was generated.

• data (object) - Vault-specific data.

  • event (Event) - contains the event that happened.

    • id (string) - (repeat of the id parameter)

    • metadata (object) - arbitrary extra data customized for the event type.

  • event_type (string) - the event type that was published.

  • plugin_info (PluginInfo) - information about the plugin that generated the event, if applicable.

    • mount_class (string) - the class of plugin, e.g., secret, auth.

    • mount_accessor (string) - the unique ID of the mounted plugin.

    • mount_path (string) - the path that the plugin is mounted at.

    • plugin (string) - the name of the plugin, e.g., kv.

Here is an example event in JSON format:

{
  "id": "a3be9fb1-b514-519f-5b25-b6f144a8c1ce",
  "source": "https://vaultproject.io/",
  "specversion": "1.0",
  "type": "*",
  "data": {
    "event": {
      "id": "a3be9fb1-b514-519f-5b25-b6f144a8c1ce",
      "metadata": {
        "current_version": "1",
        "data_path": "secret/data/foo",
        "modified": "true",
        "oldest_version": "0",
        "operation": "data-write",
        "path": "secret/data/foo"
      }
    },
    "event_type": "kv-v2/data-write",
    "plugin_info": {
      "mount_class": "secret",
      "mount_accessor": "kv_5dc4d18e",
      "mount_path": "secret/",
      "plugin": "kv"
    }
  },
  "datacontentype": "application/cloudevents",
  "time": "2023-09-12T15:19:49.394915-07:00"
}

Subscribing to events

Vault has an API endpoint, /v1/sys/events/subscribe/{eventType}, that allows users to subscribe to events via a WebSocket stream. This endpoint supports the standard authentication and authorization workflows used by other Vault endpoints. The {eventType} parameter is a non-empty string of what event type to subscribe to, which may contain wildcards (*) to subscribe to multiple events, e.g., kv-v2/data-*.

By default, the events are delivered in protobuf binary format. The endpoint can also format the data as JSON if the json query parameter is set to true:

$ wscat -H "X-Vault-Token: $(vault print token)" --connect 'ws://127.0.0.1:8200/v1/sys/events/subscribe/kv-v2/data-write?json=true'
{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","source":"vault://mycluster","specversion":"1.0","type":"*","data":{"event":{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","metadata":{"current_version":"1","data_path":"secret/data/foo","modified":"true","oldest_version":"0","operation":"data-write","path":"secret/data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-09-12T15:19:49.394915-07:00"}
...

The Vault CLI support this endpoint via the events subscribe command, which will output a stream of JSON for the requested events (one line per event):

$ vault events subscribe kv-v2/data-write
{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","source":"https://vaultproject.io/","specversion":"1.0","type":"*","data":{"event":{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","metadata":{"current_version":"1","data_path":"secret/data/foo","modified":"true","oldest_version":"0","operation":"data-write","path":"secret/data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-09-12T15:19:49.394915-07:00"}
...

Policies

To subscribe to an event, you must have the following policy grants:

1. read capability on /v1/sys/events/subscribe/{eventType}, where {eventType} is the event type that will be subscribed to. The path may contain wildcards.

   An example blanket policy is:

   path "sys/events/subscribe/*" {
       capabilities = ["read"]
   }
   

2. list and subscribe capabilities on the path of the secret for events related to secrets. The policy must also provide a subscribe_event_types entry with the specific events subscribers are allowed to use. For example, to receive events related to the KV secrets engine path, secret/my-data, a valid policy would be:

   path "secret/my-data" {
     capabilities = ["list", "subscribe"]
     subscribe_event_types = ["*"]
   }
   

Vault continuously evaluates policies for WebSocket subscriptions and caches the results for a short period of time to improve performance. As a result, events may still be sent for a few minutes after a token is revoked or a policy is deleted.

Supported versions

For versions where events are disabled by default, you can enable the functionality with the events.alpha1 experiment option in your Vault configuration or from the command line with the -experiments flag. For example:

$ vault server -experiment events.alpha1