Keen documentation
Open Keen ↗

Administering Keen

Bitwarden organisation event log

Chapter 35 of 40

Bitwarden

Bitwarden is a built-in, read-only ingester for the organisation event log of the Bitwarden Public API. It collects sign-ins, vault item activity and changes to members, groups, collections, policies and organisation settings, from Bitwarden's cloud or a self-hosted server.

Create the API key and configure Keen

  1. In the Bitwarden Admin Console, open Settings → Organisation info and select View API key. The Public API is available to Teams and Enterprise organisations.
  2. Copy the client_id, which begins organization., and the client_secret. This key can also manage members, groups and policies in Bitwarden: Keen only reads events with it, but store it as carefully as an owner's credentials and rotate it if it is exposed.
  3. Set these in Keen's .env and recreate the API, worker and beat containers:
    KEEN_BITWARDEN_ENABLED=true
    KEEN_BITWARDEN_BASE_URL=https://api.bitwarden.com
    KEEN_BITWARDEN_IDENTITY_URL=https://identity.bitwarden.com
    KEEN_BITWARDEN_CLIENT_ID=organization.YOUR_ORGANISATION_ID
    KEEN_BITWARDEN_CLIENT_SECRET=YOUR_CLIENT_SECRET
    KEEN_BITWARDEN_CONFIG_PATH=/app/config/bitwarden.yml
    KEEN_BITWARDEN_POLL_SECONDS=900
    
ServerAPI URLIdentity URL
Bitwarden cloud, UShttps://api.bitwarden.comhttps://identity.bitwarden.com
Bitwarden cloud, EUhttps://api.bitwarden.euhttps://identity.bitwarden.eu
Self-hostedhttps://vault.example.org/apihttps://vault.example.org/identity

Create a named Bitwarden source for each organisation; the Environment default connection uses the deployment settings.

Going deeper: transport security

Each run signs in for itself. The client secret is sent to the identity URL alone, in the body of the sign-in request, and the short-lived access token that returns is sent to the API URL alone, in the Authorization header; neither appears in a URL, and the token is not kept after the run. HTTPS and certificate verification are mandatory for both URLs, redirects are refused, each request ends within two minutes and responses are limited to 8 MiB. Keen's ingestion network policy applies to a self-hosted server, including KEEN_INGESTION_ALLOWED_CIDRS for private networks. A saved client secret is write-only, and changing either URL requires it to be entered again.

Select the event log in Keen

Define a Bitwarden source with its two URLs, client ID and client secret, then select Add input on that source in Sources & evidence mapping and enter the stream events, the one stream Bitwarden offers. An optional label becomes the event's system; otherwise it is Bitwarden. The shipped stream list is empty, so enabling the adapter alone collects nothing; add the stream, then use Ingest runners → Run Bitwarden or wait for the scheduled run.

Going deeper: the YAML file and its settings

Administrators can also manage config/bitwarden.yml; saved web-UI configuration overrides it.

ui_name: Bitwarden
badge_color: '#175DDC'
streams:
  - stream: events
    # label: Company vault
initial_lookback_days: 30
window_hours: 24
overlap_minutes: 60
max_pages: 100

initial_lookback_days is how far back the first run reads (0 to 367). window_hours is the span of the log read at a time (1 to 168), overlap_minutes how far each window reaches back for events reported late (0 to 1,440) and max_pages the pages one run reads (1 to 1,000).

Going deeper: windows, late events and limits

Keen reads the log in windows of time, oldest first, from its cursor to the present. Each page of a window is stored and committed before the next is requested, and the cursor moves to a window's end only when every page of it is stored, so a failure never skips events. A run that reaches max_pages inside a window keeps Bitwarden's paging value and the next run continues that window; if Bitwarden no longer accepts the value, the window is read again from its first page.

Bitwarden apps report some events, such as an item being viewed, a little after they happen, so each window reaches back overlap_minutes before its start. Bitwarden gives an event no identifier, so Keen recognises one it has already stored by its content, and a window read twice stores nothing twice. Two events alike in every field, including the time to a fraction of a second, are therefore stored as one.

An entry that is not an event object is left out and counted as invalid_records in the run's result. An event without a readable date is dated when it was collected. HTTP 429 and transient failures keep the cursor and are retried on the next scheduled run.

Map Bitwarden evidence

Choose Create mapping, source bitwarden. Bitwarden identifies each kind of event by a numeric type, which Keen names in the event action:

TypesEvent actions
1000–1010user.logged_in, user.changed_password, user.updated_two_step_login, user.disabled_two_step_login, user.failed_login, user.failed_two_step_login, user.exported_vault and other account events
1100–1117item.created, item.edited, item.deleted, item.viewed, item.password_viewed, item.password_copied, item.autofilled, item.trashed, item.restored and other item events
1300–1402collection.created, collection.edited, collection.deleted, group.created, group.edited, group.deleted
1500–1516member.invited, member.confirmed, member.edited, member.removed, member.revoked, member.restored, member.password_reset, member.device_approved and other membership events
1600–1609organization.settings_edited, organization.vault_purged, organization.vault_exported, organization.sso_enabled, organization.sso_disabled and other organisation events
1700, 2000–2003, 2100policy.modified, domain.added, domain.removed, domain.verified, domain.not_verified, secret.accessed

A type Keen does not know yet is stored as event. and its number, such as event.4242, and can be mapped by that action. Failed sign-ins (user.failed_login, user.failed_two_step_login) have outcome failure; every other event has info. The actor is the acting user's Bitwarden identifier: the Public API's event log carries no names or email addresses.

Example: source bitwarden, action organization.vault_exported, mapped to your data-export control. A second mapping on outcome failure records failed sign-ins.

Going deeper: useful JSON paths
  • event.type, event.date, event.ipAddress, event.device
  • event.actingUserId, event.memberId, event.groupId, event.collectionId, event.policyId, event.itemId

The whole event Bitwarden returned is kept under event in the payload and in the artifact, through the standard Keen redaction, artifact storage, SHA-256 and framework-rule pipeline. Keen's redaction treats any field whose name contains “secret” as a secret, so a Secrets Manager event's secretId is stored as REDACTED.

Scope

This adapter reads the organisation event log. It does not read vault items, members, groups, collections or policies, and it changes nothing in Bitwarden. Start collection soon after enabling it: the first run reads back only as far as initial_lookback_days and as far as Bitwarden still holds events. The source is unavailable in demo environments.

Official documentation: