From 8e99d7a1470db655f162c34c6ccb85f301135a58 Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Thu, 30 Apr 2026 16:55:31 -0700 Subject: [PATCH 01/10] add migration guide draft --- docs/migration-guide.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/migration-guide.md diff --git a/docs/migration-guide.md b/docs/migration-guide.md new file mode 100644 index 0000000..2265ae7 --- /dev/null +++ b/docs/migration-guide.md @@ -0,0 +1,23 @@ +# Migration Guide: Splunk Application to Event Push Delivery + +This guide will outline the process that the Splunk admin will need to follow to successfully upgrade the Bitwarden Splunk application to receive events from their Bitwarden Organizations using a push based model. + +Past versions of the application used a polling based model, where the Splunk application used repeated calls to the Bitwarden API for ingesting event data. After application installation, this required the admin to complete a setup form to enable making authenticated HTTP requests to the Bitwarden API. This polling based model will be deprecated in the newest version of the application, in favor of the new push based model. + +Users will be encouraged to complete setup for the new push based model, where the Bitwarden platform will send events into Splunk via the HTTP Event Collector ([see docs](https://help.splunk.com/en/splunk-enterprise/get-started/get-data-in/9.3/get-data-with-http-event-collector/set-up-and-use-http-event-collector-in-splunk-web)). + +## Upgrading the Application + +Splunk admins will be able to find the Bitwarden application through Splunkbase, where the latest version update will be available for download. This download happens in place on their instance and does not require uninstalling their existing version of the Bitwarden Splunk application. + +Once the application has been updated, **no changes to existing polling setups for receiving events will occur on their own**. This means that when opening the upgraded application, any existing event polling setups will continue to run as they did on previous versions of the app. + +## Complete the Setup for Push Delivery + +While existing event polling setups will still work, the old polling setup form will be removed, and the application admin will be prompted to set up push based event delivery. This process includes a new setup form, which will ensure that the Splunk instance has HEC enabled, a token has been generated for use, and the proper setup in the Bitwarden Admin Console has been completed. + +After following this setup form and entering the HEC endpoint and token into Bitwarden's Admin Console, the user will be prompted to disable their old polling configuration. Upon confirmation, the application will stop polling for events. Note that duplicate events for the Bitwarden Organization will be received in Splunk for the entire timespan where both push and polling based event delivery models are enabled. **For this reason, it is strongly recommended that the admin disable the polling setup immediately after confirmation that events are being received with the push based model.** + +### New Application Users + +First time users of the Bitwarden Splunk application that install the newest version will not have the option to configure polling based event collection. They will only see the push based event delivery setup instructions. From 59e500964f545d74a8bf5f7f29eb4322e4143aea Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Mon, 4 May 2026 17:43:06 -0700 Subject: [PATCH 02/10] polling setup form will remain for now --- docs/migration-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 2265ae7..20ad984 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -14,10 +14,10 @@ Once the application has been updated, **no changes to existing polling setups f ## Complete the Setup for Push Delivery -While existing event polling setups will still work, the old polling setup form will be removed, and the application admin will be prompted to set up push based event delivery. This process includes a new setup form, which will ensure that the Splunk instance has HEC enabled, a token has been generated for use, and the proper setup in the Bitwarden Admin Console has been completed. +While existing event polling setups will still work, the application admin will be prompted to set up push based event delivery. This process includes a new setup form, which will ensure that the Splunk instance has HEC enabled, a token has been generated for use, and the proper setup in the Bitwarden Admin Console has been completed. After following this setup form and entering the HEC endpoint and token into Bitwarden's Admin Console, the user will be prompted to disable their old polling configuration. Upon confirmation, the application will stop polling for events. Note that duplicate events for the Bitwarden Organization will be received in Splunk for the entire timespan where both push and polling based event delivery models are enabled. **For this reason, it is strongly recommended that the admin disable the polling setup immediately after confirmation that events are being received with the push based model.** ### New Application Users -First time users of the Bitwarden Splunk application that install the newest version will not have the option to configure polling based event collection. They will only see the push based event delivery setup instructions. +First time users of the Bitwarden Splunk application that install the newest version will have the option to configure either polling based or push based event collection. From 8d91a6145e4f62030eb1b1ebbadf6ebaa3e88748 Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Tue, 5 May 2026 12:13:48 -0700 Subject: [PATCH 03/10] revisions --- docs/migration-guide.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 20ad984..8f7dc20 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -1,23 +1,31 @@ -# Migration Guide: Splunk Application to Event Push Delivery +# Migration Guide: Event Polling to Push Delivery -This guide will outline the process that the Splunk admin will need to follow to successfully upgrade the Bitwarden Splunk application to receive events from their Bitwarden Organizations using a push based model. +This guide outlines how a Splunk admin can migrate the [Bitwarden Event Logs](https://splunkbase.splunk.com/app/6592) Splunk application from polling events to pushed events from their Bitwarden Organizations. -Past versions of the application used a polling based model, where the Splunk application used repeated calls to the Bitwarden API for ingesting event data. After application installation, this required the admin to complete a setup form to enable making authenticated HTTP requests to the Bitwarden API. This polling based model will be deprecated in the newest version of the application, in favor of the new push based model. +Past versions of the Splunk application exclusively used a polling model, where the application used repeated calls to the Bitwarden API to retrieve event data. New versions of the application include the ability to retrieve events pushed from the Bitwarden platform into a HTTP Event Collector exposed on the Splunk instance ([see docs](https://help.splunk.com/en/splunk-enterprise/get-started/get-data-in/9.3/get-data-with-http-event-collector/set-up-and-use-http-event-collector-in-splunk-web)). -Users will be encouraged to complete setup for the new push based model, where the Bitwarden platform will send events into Splunk via the HTTP Event Collector ([see docs](https://help.splunk.com/en/splunk-enterprise/get-started/get-data-in/9.3/get-data-with-http-event-collector/set-up-and-use-http-event-collector-in-splunk-web)). +## Migration Steps -## Upgrading the Application +In order migrate Bitwarden Organization logs from a polling configuration to a push based configuration, admins will complete the following (each step detailed below): -Splunk admins will be able to find the Bitwarden application through Splunkbase, where the latest version update will be available for download. This download happens in place on their instance and does not require uninstalling their existing version of the Bitwarden Splunk application. +1. Update the Bitwarden Splunk application +2. Complete set up for event push delivery +3. Disable event polling configurations -Once the application has been updated, **no changes to existing polling setups for receiving events will occur on their own**. This means that when opening the upgraded application, any existing event polling setups will continue to run as they did on previous versions of the app. +### Update the Bitwarden Splunk application -## Complete the Setup for Push Delivery +Splunk admins need to update to any version after [TODO: add version number here] through Splunkbase. The download happens in place on their instance and does not require uninstalling their existing version of the Bitwarden Splunk application. -While existing event polling setups will still work, the application admin will be prompted to set up push based event delivery. This process includes a new setup form, which will ensure that the Splunk instance has HEC enabled, a token has been generated for use, and the proper setup in the Bitwarden Admin Console has been completed. +Updating the application will not effect existing event polling configurations, events will continue to be polled just as before the update. -After following this setup form and entering the HEC endpoint and token into Bitwarden's Admin Console, the user will be prompted to disable their old polling configuration. Upon confirmation, the application will stop polling for events. Note that duplicate events for the Bitwarden Organization will be received in Splunk for the entire timespan where both push and polling based event delivery models are enabled. **For this reason, it is strongly recommended that the admin disable the polling setup immediately after confirmation that events are being received with the push based model.** +### Complete set up for event push delivery -### New Application Users +In the application, a new form for configuring event push delivery is present. This set up will ensure that the Splunk instance has HEC enabled, a token has been generated for use, and proper set up in the Bitwarden Admin Console has been completed. -First time users of the Bitwarden Splunk application that install the newest version will have the option to configure either polling based or push based event collection. +The admin will complete this form, and the Bitwarden platform will begin to push event logs for the Organization into Splunk. + +### Disable event polling configurations + +Last, it is important to ensure any remaining polling configurations are removed from the application. This prevents the retrieval of duplicate event logs for the Organization, and should be completed as soon as possible. When both poll and push configurations are enabled for an Organization at the same time, the same events will be ingested twice. + +[TODO: clarify on how we would like to build disabling polling configurations. should the admin delete them manually (i.e. button click), or should completing push based delivery delete polling configurations automatically?)] From 4eb14ce26802933cc9f68fda29e321b953c1b346 Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Wed, 13 May 2026 16:34:09 -0700 Subject: [PATCH 04/10] update disable polling section --- docs/migration-guide.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 8f7dc20..8370961 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -10,7 +10,6 @@ In order migrate Bitwarden Organization logs from a polling configuration to a p 1. Update the Bitwarden Splunk application 2. Complete set up for event push delivery -3. Disable event polling configurations ### Update the Bitwarden Splunk application @@ -24,8 +23,6 @@ In the application, a new form for configuring event push delivery is present. T The admin will complete this form, and the Bitwarden platform will begin to push event logs for the Organization into Splunk. -### Disable event polling configurations +**Note that completing the setup form for event push delivery (push or poll) will automatically disable any existing polling configuration.** For example, if your existing configuration uses polling to retrieve events, completing the setup form for event push delivery will overwrite the old polling configuration. -Last, it is important to ensure any remaining polling configurations are removed from the application. This prevents the retrieval of duplicate event logs for the Organization, and should be completed as soon as possible. When both poll and push configurations are enabled for an Organization at the same time, the same events will be ingested twice. -[TODO: clarify on how we would like to build disabling polling configurations. should the admin delete them manually (i.e. button click), or should completing push based delivery delete polling configurations automatically?)] From a91fa6d18514a02d9bb07e9f53936da109ddd32c Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Wed, 13 May 2026 16:51:13 -0700 Subject: [PATCH 05/10] add note about poll and push not allowed together --- docs/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 8370961..24a98a5 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -23,6 +23,6 @@ In the application, a new form for configuring event push delivery is present. T The admin will complete this form, and the Bitwarden platform will begin to push event logs for the Organization into Splunk. -**Note that completing the setup form for event push delivery (push or poll) will automatically disable any existing polling configuration.** For example, if your existing configuration uses polling to retrieve events, completing the setup form for event push delivery will overwrite the old polling configuration. +**Note that completing the setup form for event push delivery (push or poll) will automatically disable any existing polling configuration.** For example, if your existing configuration uses polling to retrieve events, completing the setup form for event push delivery will overwrite the old polling configuration. Having both event polling and push configurations is not allowed, in order to prevent the same events from being received in Splunk multiple times. From 7a005bacf39b25df6f5109ae8aaa0247ceb0d008 Mon Sep 17 00:00:00 2001 From: Brad <44413459+lastbestdev@users.noreply.github.com> Date: Wed, 27 May 2026 14:01:59 -0700 Subject: [PATCH 06/10] Update docs/migration-guide.md Co-authored-by: Leslie Tilton <23057410+Banrion@users.noreply.github.com> --- docs/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 24a98a5..aa6a203 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -6,7 +6,7 @@ Past versions of the Splunk application exclusively used a polling model, where ## Migration Steps -In order migrate Bitwarden Organization logs from a polling configuration to a push based configuration, admins will complete the following (each step detailed below): +In order to migrate Bitwarden Organization logs from a polling configuration to a push based configuration, admins will complete the following (each step detailed below): 1. Update the Bitwarden Splunk application 2. Complete set up for event push delivery From 50cf20ebb8f61d5eaf14b0234dd86d14c0436b95 Mon Sep 17 00:00:00 2001 From: Brad <44413459+lastbestdev@users.noreply.github.com> Date: Wed, 27 May 2026 14:17:21 -0700 Subject: [PATCH 07/10] Update docs/migration-guide.md Co-authored-by: Leslie Tilton <23057410+Banrion@users.noreply.github.com> --- docs/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index aa6a203..3da4cdc 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -15,7 +15,7 @@ In order to migrate Bitwarden Organization logs from a polling configuration to Splunk admins need to update to any version after [TODO: add version number here] through Splunkbase. The download happens in place on their instance and does not require uninstalling their existing version of the Bitwarden Splunk application. -Updating the application will not effect existing event polling configurations, events will continue to be polled just as before the update. +Updating the application will not affect existing event polling configurations, events will continue to be polled just as before the update. ### Complete set up for event push delivery From 823b882d37d46c2c89eb6a670b6d9b8cb6a6e4c0 Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Thu, 28 May 2026 14:02:51 -0700 Subject: [PATCH 08/10] revisions per feedback --- docs/migration-guide.md | 42 +++++++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 3da4cdc..0f08c5d 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -8,8 +8,9 @@ Past versions of the Splunk application exclusively used a polling model, where In order to migrate Bitwarden Organization logs from a polling configuration to a push based configuration, admins will complete the following (each step detailed below): -1. Update the Bitwarden Splunk application -2. Complete set up for event push delivery +1. [Update the Bitwarden Splunk application](#update-the-bitwarden-splunk-application) +2. [Bitwarden Splunk application: Configure event push delivery (HEC setup)](#bitwarden-splunk-application-configure-event-push-delivery-hec-setup) +3. [Bitwarden Admin Console: Complete setup for event push delivery](#bitwarden-admin-console-complete-set-up-for-event-push-delivery) ### Update the Bitwarden Splunk application @@ -17,12 +18,41 @@ Splunk admins need to update to any version after [TODO: add version number here Updating the application will not affect existing event polling configurations, events will continue to be polled just as before the update. -### Complete set up for event push delivery +### Bitwarden Splunk application: Configure event push delivery (HEC setup) -In the application, a new form for configuring event push delivery is present. This set up will ensure that the Splunk instance has HEC enabled, a token has been generated for use, and proper set up in the Bitwarden Admin Console has been completed. +Once in the updated application, the admin should navigate to the setup form. The setup form includes an option for "push" event delivery. Select it, and the form will assist the admin in ensuring that their Splunk instance is properly configured to receive events using the Http Event Collector (HEC). -The admin will complete this form, and the Bitwarden platform will begin to push event logs for the Organization into Splunk. +Take note of both the HEC endpoint and authentication token, and proceed to the next step where the push delivery is configured in the Bitwarden Admin Console. -**Note that completing the setup form for event push delivery (push or poll) will automatically disable any existing polling configuration.** For example, if your existing configuration uses polling to retrieve events, completing the setup form for event push delivery will overwrite the old polling configuration. Having both event polling and push configurations is not allowed, in order to prevent the same events from being received in Splunk multiple times. +### Bitwarden Admin Console: Complete set up for event push delivery +Login to the Bitwarden Admin Console as a member of the Organization you wish to receive event data for. From there, navigate to the "Integrations" page, then to the "Event management" tab. Locate the Splunk option in the list, and click "Connect Splunk". +The configuration form requires the HEC endpoint and authentication token received from Splunk in the step before. Enter them and save the configuration. + +You have now successfully configured Bitwarden to push Organization event data into your Splunk instance! + + +## Important Notes + +### Event Availability in Splunk + +For either configuration type, you will know event data is being properly delivered into Splunk once you see the Bitwarden Splunk application's included dashboards populate with data. See sections below about when event data should be delivered for each configuration type. + +#### Poll Configurations + +Upon completing the setup form for polling event data in the Bitwarden Splunk application, the application will begin polling Bitwarden endpoints for event data. + +#### Push Configurations + +Upon completing the configuration in Bitwarden's Admin Console for the Organization of your choice, the Bitwarden platform will begin to push events into your Splunk instance. + +### Duplicate or Lost Events + +### Duplicate Events + +Bitwarden event data may be received by Splunk multiple times, which can result in events appearing duplicated. This happens when push and poll configurations are enabled at the same time for the same Bitwarden Organization. This should only happen momentarily, while transitioning between the event delivery configuration types. + +### Missing Events + +Bitwarden event data may be missing if an existing polling configuration is deleted, or a push configuration is not properly completed in the Bitwarden Admin Console. Push configurations will not begin receiving event data until the setup is finished in the Bitwarden Admin Console. \ No newline at end of file From 9b6e8fa861467b8213d2e5387874aa5b842056ca Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Thu, 28 May 2026 14:11:11 -0700 Subject: [PATCH 09/10] add placeholder link to bw help center --- docs/migration-guide.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 0f08c5d..d4a3d4a 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -22,7 +22,7 @@ Updating the application will not affect existing event polling configurations, Once in the updated application, the admin should navigate to the setup form. The setup form includes an option for "push" event delivery. Select it, and the form will assist the admin in ensuring that their Splunk instance is properly configured to receive events using the Http Event Collector (HEC). -Take note of both the HEC endpoint and authentication token, and proceed to the next step where the push delivery is configured in the Bitwarden Admin Console. +Take note of both the HEC endpoint and authentication token, and proceed to the next step where push delivery is configured in the Bitwarden Admin Console. ### Bitwarden Admin Console: Complete set up for event push delivery @@ -32,6 +32,7 @@ The configuration form requires the HEC endpoint and authentication token receiv You have now successfully configured Bitwarden to push Organization event data into your Splunk instance! +Follow the Bitwarden Help Center [documentation](TODO) if necessary. ## Important Notes @@ -49,10 +50,10 @@ Upon completing the configuration in Bitwarden's Admin Console for the Organizat ### Duplicate or Lost Events -### Duplicate Events +#### Duplicate Events Bitwarden event data may be received by Splunk multiple times, which can result in events appearing duplicated. This happens when push and poll configurations are enabled at the same time for the same Bitwarden Organization. This should only happen momentarily, while transitioning between the event delivery configuration types. -### Missing Events +#### Missing Events Bitwarden event data may be missing if an existing polling configuration is deleted, or a push configuration is not properly completed in the Bitwarden Admin Console. Push configurations will not begin receiving event data until the setup is finished in the Bitwarden Admin Console. \ No newline at end of file From da0f2fa59711418dc0136bdb305a60047b9da314 Mon Sep 17 00:00:00 2001 From: Brad Deibert Date: Fri, 29 May 2026 13:36:51 -0700 Subject: [PATCH 10/10] setup --- docs/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-guide.md b/docs/migration-guide.md index d4a3d4a..a9d27e4 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -24,7 +24,7 @@ Once in the updated application, the admin should navigate to the setup form. Th Take note of both the HEC endpoint and authentication token, and proceed to the next step where push delivery is configured in the Bitwarden Admin Console. -### Bitwarden Admin Console: Complete set up for event push delivery +### Bitwarden Admin Console: Complete setup for event push delivery Login to the Bitwarden Admin Console as a member of the Organization you wish to receive event data for. From there, navigate to the "Integrations" page, then to the "Event management" tab. Locate the Splunk option in the list, and click "Connect Splunk".