Pin individual entities in graph (#251299)

## Summary

Part of the fixes needed to close
#239954

PRs:
1. #251299 <-- this PR
2. #250105

API allows for pinning events/alerts by document ID but we don't have a
proper way to represent that in the UI so we're skipping for now

### Screenshots

<details><summary>Pinning no entities from the group</summary>
<img width="1660" height="842" alt="Screenshot 2026-02-02 at 19 18 56"
src="https://github.com/user-attachments/assets/407c4b99-f0a2-441f-8731-e5b5a1101734"
/>
</details> 

<details><summary>Pinning "admin2@example.com" entity</summary>
<img width="1665" height="952" alt="Screenshot 2026-02-02 at 19 22 15"
src="https://github.com/user-attachments/assets/b45f8bbf-cd11-4db9-ae9a-37813b4919fa"
/>
</details> 

<details><summary>Pinning "admin2@example.com" and
"admin-user2@example.com" entities</summary>
<img width="1659" height="1023" alt="Screenshot 2026-02-02 at 19 23 11"
src="https://github.com/user-attachments/assets/f701d0ea-debb-40d5-ade3-1c0d356e2d62"
/>
</details> 

<details><summary>Pinning all entities in actor node</summary>
<img width="1661" height="1479" alt="Screenshot 2026-02-02 at 19 28 10"
src="https://github.com/user-attachments/assets/20938268-0161-4767-a9d5-904bb6cde446"
/>
</details> 

<details><summary>pinnedIds field sent in the request payload</summary>
<img width="927" height="311" alt="Screenshot 2026-02-02 at 19 35 56"
src="https://github.com/user-attachments/assets/c9052483-5dff-4e1d-a1cb-b979c3bbf5b5"
/>
</details> 

### How to test

1. Deploy a local env using the following command:
`yarn es snapshot --license trial -E
xpack.security.authc.api_key.enabled=true`
2. Run kibana using `yarn start --no-base-path`
3. Go to `Advanced settings` and make sure these toggles are on:
    - `securitySolution:enableGraphVisualization`
    - `securitySolution:enableAssetInventory`
4. Run these commands:
    ```bash
node scripts/es_archiver load
x-pack/solutions/security/test/cloud_security_posture_functional/es_archives/logs_gcp_audit
--es-url http://elastic:changeme@localhost:9200 --kibana-url
http://elastic:changeme@localhost:5601
    
node scripts/es_archiver load
x-pack/solutions/security/test/cloud_security_posture_functional/es_archives/security_alerts_modified_mappings
--es-url http://elastic:changeme@localhost:9200 --kibana-url
http://elastic:changeme@localhost:5601
    
node scripts/es_archiver load
x-pack/solutions/security/test/cloud_security_posture_functional/es_archives/entity_store
--es-url http://elastic:changeme@localhost:9200 --kibana-url
http://elastic:changeme@localhost:5601
    
node scripts/es_archiver load
x-pack/solutions/security/test/cloud_security_posture_functional/es_archives/entity_store_v2
--es-url http://elastic:changeme@localhost:9200 --kibana-url
http://elastic:changeme@localhost:5601
    ```
5. Go to Security -> Explore -> Network/Users/Hosts
6. Open an event's flyout, then expand Graph Visualization. Apply
filters to see events from September, 1st 2017 till Now. Add an
`event.action` filter set to "google.iam.admin.v1.CreateUser", then keep
adding `user.entity.id` or `event.id` filters set to the IDs in the
entity node using the `OR` operator
7. Individual entities/events/alerts should be pinned correctly in the
graph, outside the entity/label groups

### Checklist

- [ ] 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)
- [ ]
[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
- [ ] 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.
- [ ] [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

Author: albertoblaz

x-pack/solutions/security/packages/kbn-cloud-security-posture/common/schema/graph/v1.ts

@@ -9,6 +9,8 @@ import { schema } from '@kbn/config-schema';
 
 export const INDEX_PATTERN_REGEX = /^[^A-Z^\\/?"<>|\s#,]+$/;
 
+const PINNED_IDS_MAX_SIZE = 1024;
+
 /**
  * Entity ID for relationship queries.
  * isOrigin indicates whether this entity is the center/origin of the graph
@@ -23,6 +25,7 @@ export const graphRequestSchema = schema.object({
   nodesLimit: schema.maybe(schema.number()),
   showUnknownTarget: schema.maybe(schema.boolean()),
   query: schema.object({
+    pinnedIds: schema.maybe(schema.arrayOf(schema.string(), { maxSize: PINNED_IDS_MAX_SIZE })),
     // Origin event IDs - optional, may be empty when opening from entity flyout
     originEventIds: schema.maybe(
       schema.arrayOf(schema.object({ id: schema.string(), isAlert: schema.boolean() }))

x-pack/solutions/security/packages/kbn-cloud-security-posture/graph/src/components/graph_investigation/graph_investigation.tsx

@@ -17,6 +17,10 @@ import { Panel } from '@xyflow/react';
 import { getEsQueryConfig } from '@kbn/data-service';
 import { EuiFlexGroup, EuiFlexItem, EuiProgress } from '@elastic/eui';
 import useSessionStorage from 'react-use/lib/useSessionStorage';
+import {
+  GRAPH_ACTOR_ENTITY_FIELDS,
+  GRAPH_TARGET_ENTITY_FIELDS,
+} from '@kbn/cloud-security-posture-common/constants';
 import { Graph, isEntityNode, type NodeProps } from '../../..';
 import { Callout } from '../callout/callout';
 import { type UseFetchGraphDataParams, useFetchGraphData } from '../../hooks/use_fetch_graph_data';
@@ -30,7 +34,11 @@ import { analyzeDocuments } from '../node/label_node/analyze_documents';
 import { EVENT_ID, GRAPH_NODES_LIMIT, TOGGLE_SEARCH_BAR_STORAGE_KEY } from '../../common/constants';
 import { Actions } from '../controls/actions';
 import { AnimatedSearchBarContainer, useBorder } from './styles';
-import { CONTROLLED_BY_GRAPH_INVESTIGATION_FILTER, addFilter } from './search_filters';
+import {
+  CONTROLLED_BY_GRAPH_INVESTIGATION_FILTER,
+  addFilter,
+  getFilterValues,
+} from './search_filters';
 import { useEntityNodeExpandPopover } from '../popovers/node_expand/use_entity_node_expand_popover';
 import { useLabelNodeExpandPopover } from '../popovers/node_expand/use_label_node_expand_popover';
 import type { NodeViewModel } from '../types';
@@ -284,6 +292,13 @@ export const GraphInvestigation = memo<GraphInvestigationProps>(
       return lastValidEsQuery.current;
     }, [dataView, kquery, notifications, searchFilters, uiSettings]);
 
+    const pinnedIds = useMemo(() => {
+      return getFilterValues(searchFilters, [
+        ...GRAPH_ACTOR_ENTITY_FIELDS,
+        ...GRAPH_TARGET_ENTITY_FIELDS,
+      ]).map(String);
+    }, [searchFilters]);
+
     const { data, refresh, isFetching, isError, error } = useFetchGraphData({
       req: {
         query: {
@@ -292,6 +307,7 @@ export const GraphInvestigation = memo<GraphInvestigationProps>(
           esQuery,
           start: timeRange.from,
           end: timeRange.to,
+          pinnedIds,
         },
         nodesLimit: GRAPH_NODES_LIMIT,
       },

x-pack/solutions/security/packages/kbn-cloud-security-posture/graph/src/components/graph_investigation/search_filters.test.ts

@@ -20,6 +20,7 @@ import {
   addFilter,
   containsFilter,
   removeFilter,
+  getFilterValues,
 } from './search_filters';
 
 const dataViewId = 'test-data-view';
@@ -303,4 +304,72 @@ describe('search_filters', () => {
       expect(newFilters[1].meta.params).toHaveLength(2);
     });
   });
+
+  describe('getFilterValues', () => {
+    it('should return empty array for empty filters', () => {
+      const filters: Filter[] = [];
+
+      expect(getFilterValues(filters, key)).toEqual([]);
+    });
+
+    it('should return value from phrase filter with matching key', () => {
+      const filters: Filter[] = [buildFilterMock(key, value)];
+
+      expect(getFilterValues(filters, key)).toEqual([value]);
+    });
+
+    it('should return empty array when key does not match', () => {
+      const filters: Filter[] = [buildFilterMock('other-key', value)];
+
+      expect(getFilterValues(filters, key)).toEqual([]);
+    });
+
+    it('should return values from combined filter', () => {
+      const filters: Filter[] = [
+        buildCombinedFilterMock([buildFilterMock(key, 'value1'), buildFilterMock(key, 'value2')]),
+      ];
+
+      expect(getFilterValues(filters, key)).toEqual(['value1', 'value2']);
+    });
+
+    it('should skip disabled filters', () => {
+      const disabledFilter = buildFilterMock(key, value);
+      disabledFilter.meta.disabled = true;
+      const filters: Filter[] = [disabledFilter, buildFilterMock(key, 'enabled-value')];
+
+      expect(getFilterValues(filters, key)).toEqual(['enabled-value']);
+    });
+
+    it('should handle multiple keys', () => {
+      const filters: Filter[] = [
+        buildFilterMock('key1', 'value1'),
+        buildFilterMock('key2', 'value2'),
+        buildFilterMock('key3', 'value3'),
+      ];
+
+      expect(getFilterValues(filters, ['key1', 'key2'])).toEqual(['value1', 'value2']);
+    });
+
+    it('should return values from mixed phrase and combined filters', () => {
+      const filters: Filter[] = [
+        buildFilterMock(key, 'phrase-value'),
+        buildCombinedFilterMock([
+          buildFilterMock(key, 'combined-value1'),
+          buildFilterMock('other-key', 'other-value'),
+        ]),
+      ];
+
+      expect(getFilterValues(filters, key)).toEqual(['phrase-value', 'combined-value1']);
+    });
+
+    it('should handle readonly string array for keys', () => {
+      const readonlyKeys = ['key1', 'key2'] as const;
+      const filters: Filter[] = [
+        buildFilterMock('key1', 'value1'),
+        buildFilterMock('key2', 'value2'),
+      ];
+
+      expect(getFilterValues(filters, readonlyKeys)).toEqual(['value1', 'value2']);
+    });
+  });
 });

x-pack/solutions/security/packages/kbn-cloud-security-posture/graph/src/components/graph_investigation/search_filters.ts

@@ -16,6 +16,7 @@ import type { Filter, PhraseFilter } from '@kbn/es-query';
 import type {
   CombinedFilter,
   PhraseFilterMetaParams,
+  PhraseFilterValue,
 } from '@kbn/es-query/src/filters/build_filters';
 
 export const CONTROLLED_BY_GRAPH_INVESTIGATION_FILTER = 'graph-investigation';
@@ -167,3 +168,45 @@ export const removeFilter = (filters: Filter[], key: string, value: string) => {
 
   return filters;
 };
+
+/**
+ * Helper function to extract filter value(s) from a single filter.
+ * Handles both simple phrase filters and combined filters recursively.
+ */
+const getFilterValue = (
+  filter: Filter,
+  keys: string[]
+): PhraseFilterValue[] | PhraseFilterValue | null => {
+  if (isCombinedFilter(filter)) {
+    return filter.meta.params
+      .map((param) => getFilterValue(param, keys))
+      .filter((value): value is PhraseFilterValue | PhraseFilterValue[] => value !== null)
+      .flat();
+  }
+
+  return filter.meta.key && keys.includes(filter.meta.key)
+    ? (filter.meta.params as PhraseFilterMetaParams)?.query
+    : null;
+};
+
+/**
+ * Extracts all values from filters that match the specified keys.
+ * Handles both simple phrase filters and combined filters.
+ * Skips disabled filters.
+ *
+ * @param filters - The list of filters to extract values from.
+ * @param key - The key or array of keys to match against filter keys.
+ * @returns An array of all values from matching filters.
+ */
+export const getFilterValues = (
+  filters: Filter[],
+  key: string | readonly string[]
+): PhraseFilterValue[] => {
+  const keys = Array.isArray(key) ? key : [key];
+
+  return filters
+    .filter((filter) => !filter.meta.disabled)
+    .map((filter) => getFilterValue(filter, keys as string[]))
+    .filter((value): value is PhraseFilterValue | PhraseFilterValue[] => value !== null)
+    .flat();
+};

x-pack/solutions/security/packages/kbn-cloud-security-posture/graph/src/hooks/use_fetch_graph_data.ts

@@ -85,13 +85,13 @@ export const useFetchGraphData = ({
   options,
 }: UseFetchGraphDataParams): UseFetchGraphDataResult => {
   const queryClient = useQueryClient();
-  const { esQuery, originEventIds, start, end } = req.query;
+  const { esQuery, originEventIds, start, end, pinnedIds } = req.query;
   const {
     services: { http },
   } = useKibana();
   const QUERY_KEY = useMemo(
-    () => ['useFetchGraphData', originEventIds, start, end, esQuery],
-    [end, esQuery, originEventIds, start]
+    () => ['useFetchGraphData', originEventIds, start, end, esQuery, pinnedIds],
+    [end, esQuery, originEventIds, start, pinnedIds]
   );
 
   const { isLoading, isError, data, isFetching, error } = useQuery<GraphResponse>(

x-pack/solutions/security/plugins/cloud_security_posture/server/routes/graph/fetch_events_graph.ts

@@ -40,6 +40,7 @@ interface BuildEsqlQueryParams {
   isEnrichPolicyExists: boolean;
   spaceId: string;
   alertsMappingsIncluded: boolean;
+  pinnedIds?: string[];
 }
 
 /**
@@ -56,6 +57,7 @@ export const fetchEvents = async ({
   indexPatterns,
   spaceId,
   esQuery,
+  pinnedIds,
 }: {
   esClient: IScopedClusterClient;
   logger: Logger;
@@ -66,6 +68,7 @@ export const fetchEvents = async ({
   indexPatterns: string[];
   spaceId: string;
   esQuery?: EsQuery;
+  pinnedIds?: string[];
 }): Promise<EsqlToRecords<EventEdge>> => {
   const originAlertIds = originEventIds.filter((originEventId) => originEventId.isAlert);
 
@@ -98,6 +101,7 @@ export const fetchEvents = async ({
     isEnrichPolicyExists,
     spaceId,
     alertsMappingsIncluded,
+    pinnedIds,
   });
 
   logger.trace(`Executing query [${query}]`);
@@ -114,6 +118,7 @@ export const fetchEvents = async ({
         ...originEventIds
           .filter((originEventId) => originEventId.isAlert)
           .map((originEventId, idx) => ({ [`og_alrt_id${idx}`]: originEventId.id })),
+        ...(pinnedIds ?? []).map((id, idx) => ({ [`pinned_id${idx}`]: id })),
       ],
     })
     .toRecords<EventEdge>();
@@ -196,6 +201,25 @@ const checkEnrichPolicyExists = async (
   }
 };
 
+/**
+ * Generates ESQL statement for evaluating pinned IDs.
+ * This checks if the document _id, actorEntityId, or targetEntityId matches any of the pinned IDs.
+ */
+const buildPinnedEsql = (pinnedIds?: string[]): string => {
+  if (!pinnedIds || pinnedIds.length === 0) {
+    return '| EVAL pinned = TO_STRING(null)';
+  }
+
+  const pinnedParamsStr = pinnedIds.map((_id, idx) => `?pinned_id${idx}`).join(', ');
+
+  return `| EVAL pinned = CASE(
+    _id IN (${pinnedParamsStr}), _id,
+    actorEntityId IN (${pinnedParamsStr}), actorEntityId,
+    targetEntityId IN (${pinnedParamsStr}), targetEntityId,
+    null
+  )`;
+};
+
 /**
  * Generates ESQL statements for building entity fields with enrichment data.
  * This is used when entity store enrichment is available (via LOOKUP JOIN or ENRICH).
@@ -253,6 +277,7 @@ const buildEsqlQuery = ({
   isEnrichPolicyExists,
   spaceId,
   alertsMappingsIncluded,
+  pinnedIds,
 }: BuildEsqlQueryParams): string => {
   const SECURITY_ALERTS_PARTIAL_IDENTIFIER = '.alerts-security.alerts-';
   const enrichPolicyName = getEnrichPolicyId(spaceId);
@@ -293,6 +318,7 @@ const buildEsqlQuery = ({
 ${targetEntityIdEvals}
 | MV_EXPAND actorEntityId
 | MV_EXPAND targetEntityId
+${buildPinnedEsql(pinnedIds)}
 | EVAL actorEntityFieldHint = CASE(
 ${actorFieldHintCases},
     ""
@@ -425,9 +451,12 @@ ${buildEnrichedEntityFieldsEsql()}
       targetEntityType,
       targetEntitySubType,
       isOrigin,
-      isOriginAlert
+      isOriginAlert,
+      pinned
+| EVAL pinnedSort = CASE(pinned IS NULL, 1, 0)
+| SORT action DESC, pinnedSort ASC, isOrigin
 | LIMIT 1000
-| SORT action DESC, isOrigin`;
+| DROP pinnedSort`;
 
   return query;
 };

x-pack/solutions/security/plugins/cloud_security_posture/server/routes/graph/fetch_graph.test.ts

@@ -95,6 +95,7 @@ describe('fetchGraph', () => {
       indexPatterns: baseParams.indexPatterns,
       spaceId: baseParams.spaceId,
       esQuery: undefined,
+      pinnedIds: undefined,
     });
   });
 
@@ -211,4 +212,30 @@ describe('fetchGraph', () => {
       'Failed to fetch entity relationships: Connection refused'
     );
   });
+
+  describe('Pinned IDs', () => {
+    it('should pass pinnedIds to fetchEvents when provided', async () => {
+      const pinnedIds = ['entity-1', 'entity-2'];
+
+      await fetchGraph({ ...baseParams, pinnedIds });
+
+      expect(mockedFetchEvents).toHaveBeenCalledWith(
+        expect.objectContaining({ pinnedIds: ['entity-1', 'entity-2'] })
+      );
+    });
+
+    it('should pass pinnedIds as undefined to fetchEvents when not provided', async () => {
+      await fetchGraph(baseParams);
+
+      expect(mockedFetchEvents).toHaveBeenCalledWith(
+        expect.objectContaining({ pinnedIds: undefined })
+      );
+    });
+
+    it('should pass empty pinnedIds array to fetchEvents when provided as empty', async () => {
+      await fetchGraph({ ...baseParams, pinnedIds: [] });
+
+      expect(mockedFetchEvents).toHaveBeenCalledWith(expect.objectContaining({ pinnedIds: [] }));
+    });
+  });
 });

x-pack/solutions/security/plugins/cloud_security_posture/server/routes/graph/fetch_graph.ts

@@ -22,6 +22,7 @@ export interface FetchGraphParams {
   spaceId: string;
   esQuery?: EsQuery;
   entityIds?: EntityId[];
+  pinnedIds?: string[];
 }
 
 export interface FetchGraphResult {
@@ -47,6 +48,7 @@ export const fetchGraph = async ({
   spaceId,
   esQuery,
   entityIds,
+  pinnedIds,
 }: FetchGraphParams): Promise<FetchGraphResult> => {
   // Only fetch events when originEventIds or esQuery are provided
   const hasOriginEventIds = originEventIds.length > 0;
@@ -68,6 +70,7 @@ export const fetchGraph = async ({
           indexPatterns,
           spaceId,
           esQuery,
+          pinnedIds,
         }).catch((error) => {
           logger.error(`Failed to fetch events: ${error.message}`);
           throw error;

x-pack/solutions/security/plugins/cloud_security_posture/server/routes/graph/route.ts

@@ -43,8 +43,8 @@ export const defineGraphRoute = (router: CspRouter) =>
       async (context: CspRequestHandlerContext, request, response) => {
         const cspContext = await context.csp;
         const { nodesLimit, showUnknownTarget = false } = request.body;
-        const { originEventIds, start, end, indexPatterns, esQuery, entityIds } = request.body
-          .query as GraphRequest['query'];
+        const { originEventIds, start, end, indexPatterns, esQuery, entityIds, pinnedIds } = request
+          .body.query as GraphRequest['query'];
         const spaceId = await cspContext.spacesService?.getSpaceId(request);
         const isGraphEnabled = await (
           await context.core
@@ -70,6 +70,7 @@ export const defineGraphRoute = (router: CspRouter) =>
               end,
               esQuery,
               entityIds,
+              pinnedIds,
             },
             showUnknownTarget,
             nodesLimit,