[Entity Analytics] Parameterise refresh on resolution bulk writes (elastic#268467)

## Summary

Fixes the 403 returned by `POST
/api/security/entity_store/resolution/link` and `/unlink` on serverless
with `platform_engineer` role (caught in e2e tests). Root cause:
`bulkUpdateEntityDocs` called `esClient.bulk({ refresh: true })`, which
requires the `indices:admin/refresh/unpromotable` action — not granted
to `platform_engineer` on `.entities.v2.latest.*`.

This PR replaces the hardcoded `refresh: true` with a configurable
`refresh` option on `bulkUpdateEntityDocs`, defaulting to `'wait_for'`.
Both `'wait_for'` and `false` only require `write` privilege.

Caller settings:

| Caller | Setting | Why |
| --- | --- | --- |
| UI flyout routes (`/resolution/link`, `/resolution/unlink`) |
`'wait_for'` (default) | UI immediately refetches the resolution group;
without read-your-writes guarantee the refetch might get stale state |
| CSV upload (`processRow`) | `false` | `'wait_for'` adds ~1s per row in
sequential CSV processing; 200-row uploads were exceeding the HTTP
socket timeout. With `false`, 200 rows complete in ~2s. Trade-off:
within a single upload, two rows resolving the same alias to different
targets silently take the last writer (though this matches existing
"latest wins" semantics) |
| Automated resolution maintainer | `false` | Buckets are pre-collected
in memory; nothing within the same task run reads back the write, so the
refresh wait is dead time |

Fixes elastic#266752
Related: elastic#266589 (Cypress e2e that surfaced the bug)

### Checklist

- [x] Any text added follows [EUI's writing
guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses
sentence case text and includes [i18n
support](https://github.com/elastic/kibana/blob/main/src/platform/packages/shared/kbn-i18n/README.md)
- [x]
[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)
was added for features that require explanation or tutorials
- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
- [x] If a plugin configuration key changed, check if it needs to be
allowlisted in the cloud and added to the [docker
list](https://github.com/elastic/kibana/blob/main/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker)
- [x] This was checked for breaking HTTP API changes, and any breaking
changes have been approved by the breaking-change committee. The
`release_note:breaking` label should be applied in these situations.
- [x] [Flaky Test
Runner](https://ci-stats.kibana.dev/trigger_flaky_test_runner/1) was
used on any tests changed
- [x] The PR description includes the appropriate Release Notes section,
and the correct `release_note:*` label is applied per the
[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)
- [x] Review the [backport
guidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing)
and apply applicable `backport:*` labels.

### Identify risks

- **Stale read for ~1s after CSV upload / maintainer write.** Severity:
low. Mitigation: the CSV per-row response is built from in-process
state, not a re-read; the maintainer doesn't read back its own writes
within a run. Subsequent reads from a different request will see the new
state after the next natural index refresh (<1s).
- **"Last write wins" within a single CSV upload.** Severity: low.
Mitigation: matches the broader "latest wins" approach already accepted.

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>

Author: 2 people

oas_docs/output/kibana.serverless.yaml

@@ -76103,7 +76103,7 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Link one or more entities to a target entity, creating a resolution group. Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
+        Link one or more entities to a target entity, creating a resolution group. Changes become visible on subsequent reads after the next index refresh (typically <1s). Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
       operationId: post-security-entity-store-resolution-link
       parameters:
         - description: A required header to protect against CSRF attacks
@@ -76217,7 +76217,7 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Remove one or more entities from their resolution group. Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
+        Remove one or more entities from their resolution group. Changes become visible on subsequent reads after the next index refresh (typically <1s). Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
       operationId: post-security-entity-store-resolution-unlink
       parameters:
         - description: A required header to protect against CSRF attacks

oas_docs/output/kibana.yaml

@@ -81312,7 +81312,7 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Link one or more entities to a target entity, creating a resolution group. Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
+        Link one or more entities to a target entity, creating a resolution group. Changes become visible on subsequent reads after the next index refresh (typically <1s). Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
       operationId: post-security-entity-store-resolution-link
       parameters:
         - description: A required header to protect against CSRF attacks
@@ -81426,7 +81426,7 @@ paths:
 
         Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
 
-        Remove one or more entities from their resolution group. Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
+        Remove one or more entities from their resolution group. Changes become visible on subsequent reads after the next index refresh (typically <1s). Requires an enterprise license.<br/><br/>[Required authorization] Route required privileges: securitySolution AND securitySolution-entity-analytics.
       operationId: post-security-entity-store-resolution-unlink
       parameters:
         - description: A required header to protect against CSRF attacks

x-pack/solutions/security/plugins/entity_store/server/domain/resolution/resolution_client.test.ts

@@ -99,7 +99,7 @@ describe('ResolutionClient', () => {
       });
       expect(mockEsClient.bulk).toHaveBeenCalledWith(
         expect.objectContaining({
-          refresh: true,
+          refresh: 'wait_for',
           operations: expect.arrayContaining([
             expect.objectContaining({
               update: expect.objectContaining({
@@ -111,6 +111,21 @@ describe('ResolutionClient', () => {
       );
     });
 
+    it('should forward refresh: false to the bulk call when caller passes it', async () => {
+      const targetDoc = createEntityDoc('target-1');
+      const entity1Doc = createEntityDoc('entity-1');
+
+      mockEsClient.search.mockResolvedValueOnce(
+        createSearchResponse([targetDoc, entity1Doc]) as never
+      );
+      mockEsClient.search.mockResolvedValueOnce(createSearchResponse([]) as never);
+      mockEsClient.bulk.mockResolvedValueOnce({ errors: false, items: [] } as never);
+
+      await client.linkEntities('target-1', ['entity-1'], { refresh: false });
+
+      expect(mockEsClient.bulk).toHaveBeenCalledWith(expect.objectContaining({ refresh: false }));
+    });
+
     it('should pass nested doc payloads to ES bulk (not flat dotted keys)', async () => {
       const targetDoc = createEntityDoc('target-1');
       const entity1Doc = createEntityDoc('entity-1');
@@ -348,7 +363,7 @@ describe('ResolutionClient', () => {
       expect(result).toEqual({ unlinked: ['alias-1'], skipped: [] });
       expect(mockEsClient.bulk).toHaveBeenCalledWith(
         expect.objectContaining({
-          refresh: true,
+          refresh: 'wait_for',
           operations: expect.arrayContaining([
             expect.objectContaining({
               doc: {
@@ -366,6 +381,17 @@ describe('ResolutionClient', () => {
       );
     });
 
+    it('should forward refresh: false to the bulk call when caller passes it', async () => {
+      const aliasDoc = createEntityDoc('alias-1', 'user', 'target-1');
+
+      mockEsClient.search.mockResolvedValueOnce(createSearchResponse([aliasDoc]) as never);
+      mockEsClient.bulk.mockResolvedValueOnce({ errors: false, items: [] } as never);
+
+      await client.unlinkEntities(['alias-1'], { refresh: false });
+
+      expect(mockEsClient.bulk).toHaveBeenCalledWith(expect.objectContaining({ refresh: false }));
+    });
+
     it('should throw EntitiesNotFoundError when entities are missing', async () => {
       mockEsClient.search.mockResolvedValueOnce(createSearchResponse([]) as never);
 

x-pack/solutions/security/plugins/entity_store/server/domain/resolution/resolution_client.ts

@@ -20,6 +20,7 @@ import {
   ResolutionUpdateError,
   SelfLinkError,
 } from '../errors';
+import type { RefreshOption } from '../../infra/elasticsearch/resolution';
 import {
   searchEntitiesByIds,
   searchByResolvedToField,
@@ -54,6 +55,11 @@ export interface ResolutionGroup {
   group_size: number;
 }
 
+/** Options forwarded to the underlying bulk write. */
+export interface ResolutionWriteOptions {
+  refresh?: RefreshOption;
+}
+
 interface FetchedEntities {
   sources: Map<string, Record<string, unknown>>;
   docIds: Map<string, string>;
@@ -75,7 +81,12 @@ export class ResolutionClient {
    * Validates chain prevention (can't link an alias) and has-aliases prevention
    * (can't link an entity that has aliases pointing to it).
    */
-  public async linkEntities(targetId: string, rawEntityIds: string[]): Promise<LinkResult> {
+  public async linkEntities(
+    targetId: string,
+    rawEntityIds: string[],
+    options: ResolutionWriteOptions = {}
+  ): Promise<LinkResult> {
+    const { refresh = 'wait_for' } = options;
     const index = getLatestEntitiesIndexName(this.namespace);
 
     // 1. Deduplicate entity_ids
@@ -133,7 +144,7 @@ export class ResolutionClient {
       docId: docIds.get(entityId)!,
       doc: { [RESOLVED_TO_FIELD]: targetId },
     }));
-    const linkResult = await bulkUpdateEntityDocs(this.esClient, { index, updates });
+    const linkResult = await bulkUpdateEntityDocs(this.esClient, { index, updates, refresh });
 
     this.throwOnBulkErrors(linkResult, `linking entities to '${targetId}'`);
 
@@ -144,7 +155,11 @@ export class ResolutionClient {
    * Unlinks alias entities by removing their resolved_to field.
    * Unlinked entities become standalone.
    */
-  public async unlinkEntities(rawEntityIds: string[]): Promise<UnlinkResult> {
+  public async unlinkEntities(
+    rawEntityIds: string[],
+    options: ResolutionWriteOptions = {}
+  ): Promise<UnlinkResult> {
+    const { refresh = 'wait_for' } = options;
     const index = getLatestEntitiesIndexName(this.namespace);
 
     // 1. Deduplicate and fetch all entities
@@ -176,7 +191,7 @@ export class ResolutionClient {
       docId: docIds.get(entityId)!,
       doc: { [RESOLVED_TO_FIELD]: null },
     }));
-    const unlinkResult = await bulkUpdateEntityDocs(this.esClient, { index, updates });
+    const unlinkResult = await bulkUpdateEntityDocs(this.esClient, { index, updates, refresh });
 
     this.throwOnBulkErrors(unlinkResult, 'unlinking entities');
 

x-pack/solutions/security/plugins/entity_store/server/infra/elasticsearch/resolution.ts

@@ -91,6 +91,24 @@ interface BulkFieldUpdate {
   doc: Record<string, unknown>;
 }
 
+/**
+ * Refresh option for bulk writes against the latest entities index.
+ *
+ * - `'wait_for'` (default): block until the next scheduled refresh fires
+ *   (typically <1s). Read-your-writes guaranteed on subsequent searches.
+ *   Only requires `write` privilege.
+ * - `false`: return immediately; the doc becomes searchable on the next
+ *   natural refresh. Stale reads possible for ~1s. Only requires `write`.
+ *
+ * `true` is intentionally not supported: forcing a refresh requires the
+ * `indices:admin/refresh/unpromotable` action.
+ *
+ * Caller guidance: UI routes rely on the default so the immediate refetch
+ * sees the new state. Bulk callers (CSV upload, automated maintainer) pass
+ * `false` to avoid the per-write refresh wait.
+ */
+export type RefreshOption = boolean | 'wait_for';
+
 /**
  * Bulk updates entity documents by pre-computed _id.
  * Uses retry_on_conflict to handle concurrent modifications.
@@ -100,18 +118,20 @@ export const bulkUpdateEntityDocs = (
   params: {
     index: string;
     updates: BulkFieldUpdate[];
+    refresh?: RefreshOption;
   }
 ): Promise<BulkResponse> => {
-  const operations = params.updates.flatMap(({ docId, doc }) => [
+  const { index, updates, refresh = 'wait_for' } = params;
+  const operations = updates.flatMap(({ docId, doc }) => [
     {
       update: {
-        _index: params.index,
+        _index: index,
         _id: docId,
         retry_on_conflict: RETRY_ON_CONFLICT,
       },
     },
     { doc: unflattenObject(doc) },
   ]);
 
-  return esClient.bulk({ operations, refresh: true });
+  return esClient.bulk({ operations, refresh });
 };

x-pack/solutions/security/plugins/entity_store/server/maintainers/automated_resolution/__tests__/run.test.ts

@@ -206,7 +206,9 @@ describe('Automated Resolution', () => {
         createDeps(state, mockEsClient, mockResolutionClient)
       );
 
-      expect(mockLinkEntities).toHaveBeenCalledWith('user-okta', ['user-entra']);
+      expect(mockLinkEntities).toHaveBeenCalledWith('user-okta', ['user-entra'], {
+        refresh: false,
+      });
       expect(result.lastRun?.resolutionsCreated).toBe(1);
     });
 
@@ -236,7 +238,9 @@ describe('Automated Resolution', () => {
         createDeps(state, mockEsClient, mockResolutionClient)
       );
 
-      expect(mockLinkEntities).toHaveBeenCalledWith('user-existing-target', ['user-new']);
+      expect(mockLinkEntities).toHaveBeenCalledWith('user-existing-target', ['user-new'], {
+        refresh: false,
+      });
       expect(result.lastRun?.resolutionsCreated).toBe(1);
     });
 

x-pack/solutions/security/plugins/entity_store/server/maintainers/automated_resolution/run.ts

@@ -302,7 +302,7 @@ async function resolveMatchBuckets(
           .map((e) => e.entityId);
         if (aliasIds.length === 0) continue;
 
-        const result = await resolutionClient.linkEntities(targetId, aliasIds);
+        const result = await resolutionClient.linkEntities(targetId, aliasIds, { refresh: false });
         resolutionsCreated += result.linked.length;
       } else if (unresolvedEntities.length >= 2) {
         // New group: pick target via namespace priority, link the rest
@@ -311,7 +311,9 @@ async function resolveMatchBuckets(
           .filter((e) => e.entityId !== targetEntity.entityId)
           .map((e) => e.entityId);
 
-        const result = await resolutionClient.linkEntities(targetEntity.entityId, aliasIds);
+        const result = await resolutionClient.linkEntities(targetEntity.entityId, aliasIds, {
+          refresh: false,
+        });
         resolutionsCreated += result.linked.length;
       }
       // else: only 1 unresolved, no existing targets → no match, skip

x-pack/solutions/security/plugins/entity_store/server/routes/apis/resolution/link.ts

@@ -39,7 +39,9 @@ export function registerResolutionLink(router: EntityStorePluginRouter) {
       access: 'public',
       summary: 'Link entities',
       description:
-        'Link one or more entities to a target entity, creating a resolution group. Requires an enterprise license.',
+        'Link one or more entities to a target entity, creating a resolution group. ' +
+        'Changes become visible on subsequent reads after the next index refresh ' +
+        '(typically <1s). Requires an enterprise license.',
       options: {
         tags: ['oas-tag:Security entity store'],
       },

x-pack/solutions/security/plugins/entity_store/server/routes/apis/resolution/unlink.ts

@@ -31,7 +31,9 @@ export function registerResolutionUnlink(router: EntityStorePluginRouter) {
       access: 'public',
       summary: 'Unlink entities',
       description:
-        'Remove one or more entities from their resolution group. Requires an enterprise license.',
+        'Remove one or more entities from their resolution group. Changes become ' +
+        'visible on subsequent reads after the next index refresh (typically <1s). ' +
+        'Requires an enterprise license.',
       options: {
         tags: ['oas-tag:Security entity store'],
       },

x-pack/solutions/security/plugins/security_solution/server/lib/entity_analytics/entity_resolution/csv_upload.test.ts

@@ -340,7 +340,7 @@ describe('processResolutionCsvUpload', () => {
         });
     });
 
-    it('should call linkEntities with correct args', async () => {
+    it('should call linkEntities with correct args and refresh: false', async () => {
       mockResolutionClient.linkEntities.mockResolvedValue({
         linked: ['alias:1'],
         skipped: [],
@@ -350,7 +350,9 @@ describe('processResolutionCsvUpload', () => {
       const csv = 'type,user.email,resolved_to\nuser,alias@test.com,target:golden';
       await processResolutionCsvUpload(createMockStream(csv), deps());
 
-      expect(mockResolutionClient.linkEntities).toHaveBeenCalledWith('target:golden', ['alias:1']);
+      expect(mockResolutionClient.linkEntities).toHaveBeenCalledWith('target:golden', ['alias:1'], {
+        refresh: false,
+      });
     });
 
     it('should report success with linked and skipped counts', async () => {