Pin individual entities in graph

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

@@ -12,6 +12,7 @@
 export const graphRequestSchema = schema.object({
   nodesLimit: schema.maybe(schema.number()),
   showUnknownTarget: schema.maybe(schema.boolean()),
+  pinnedEntityIds: schema.maybe(schema.arrayOf(schema.string())),
   query: schema.object({
     originEventIds: 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 pinnedEntities = useMemo(() => {
+      return getFilterValues(searchFilters, [
+        ...GRAPH_ACTOR_ENTITY_FIELDS,
+        ...GRAPH_TARGET_ENTITY_FIELDS,
+      ]).map(String);
+    }, [searchFilters]);
+
     const { data, refresh, isFetching, isError, error } = useFetchGraphData({
       req: {
         query: {
@@ -294,6 +309,7 @@ export const GraphInvestigation = memo<GraphInvestigationProps>(
           end: timeRange.to,
         },
         nodesLimit: GRAPH_NODES_LIMIT,
+        pinnedEntityIds: pinnedEntities,
       },
       options: {
         refetchOnWindowFocus: false,

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

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import { flatten } from 'lodash';
 import {
   BooleanRelation,
   FilterStateStore,
@@ -16,6 +17,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 +169,47 @@ 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 flatten(
+      filter.meta.params
+        .map((param) => getFilterValue(param, keys))
+        .filter((value): value is PhraseFilterValue | PhraseFilterValue[] => value !== null)
+    );
+  }
+
+  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 flatten(
+    filters
+      .filter((filter) => !filter.meta.disabled)
+      .map((filter) => getFilterValue(filter, keys as string[]))
+      .filter((value): value is PhraseFilterValue | PhraseFilterValue[] => value !== null)
+  );
+};

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

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

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

@@ -518,4 +518,90 @@ describe('fetchGraph', () => {
       expect(hasTargetCheck).toBe(false);
     });
   });
+
+  describe('Pinned entity IDs', () => {
+    it('should include pinned entity parameters when pinnedEntityIds are provided', async () => {
+      const pinnedEntityIds = ['entity-1', 'entity-2'];
+      const validIndexPatterns = ['valid_index'];
+      const params = {
+        esClient,
+        logger,
+        start: 0,
+        end: 1000,
+        originEventIds: [] as OriginEventId[],
+        showUnknownTarget: false,
+        indexPatterns: validIndexPatterns,
+        spaceId: 'default',
+        esQuery: undefined as EsQuery | undefined,
+        pinnedEntityIds,
+      };
+
+      await fetchGraph(params);
+
+      expect(esClient.asCurrentUser.helpers.esql).toBeCalledTimes(1);
+      const esqlCallArgs = esClient.asCurrentUser.helpers.esql.mock.calls[0];
+      const query = esqlCallArgs[0].query;
+
+      // Verify EVAL pinned CASE statement is present
+      expect(query).toContain('EVAL pinned = CASE(');
+      expect(query).toContain('actorEntityId IN (?pinned_id0, ?pinned_id1)');
+      expect(query).toContain('targetEntityId IN (?pinned_id0, ?pinned_id1)');
+    });
+
+    it('should use null fallback for pinned when no pinnedEntityIds are provided', async () => {
+      const validIndexPatterns = ['valid_index'];
+      const params = {
+        esClient,
+        logger,
+        start: 0,
+        end: 1000,
+        originEventIds: [] as OriginEventId[],
+        showUnknownTarget: false,
+        indexPatterns: validIndexPatterns,
+        spaceId: 'default',
+        esQuery: undefined as EsQuery | undefined,
+        pinnedEntityIds: undefined,
+      };
+
+      await fetchGraph(params);
+
+      expect(esClient.asCurrentUser.helpers.esql).toBeCalledTimes(1);
+      const esqlCallArgs = esClient.asCurrentUser.helpers.esql.mock.calls[0];
+      const query = esqlCallArgs[0].query;
+
+      // Verify fallback EVAL pinned = TO_STRING(null) is present
+      expect(query).toContain('EVAL pinned = TO_STRING(null)');
+
+      // Verify no pinned_id params
+      const pinnedParams = esqlCallArgs[0].params
+        // @ts-ignore: field is typed as Record<string, string>[]
+        ?.filter((p) => Object.keys(p)[0]?.startsWith('pinned_id'));
+      expect(pinnedParams).toHaveLength(0);
+    });
+
+    it('should use null fallback for pinned when pinnedEntityIds is empty array', async () => {
+      const validIndexPatterns = ['valid_index'];
+      const params = {
+        esClient,
+        logger,
+        start: 0,
+        end: 1000,
+        originEventIds: [] as OriginEventId[],
+        showUnknownTarget: false,
+        indexPatterns: validIndexPatterns,
+        spaceId: 'default',
+        esQuery: undefined as EsQuery | undefined,
+        pinnedEntityIds: [],
+      };
+
+      await fetchGraph(params);
+
+      expect(esClient.asCurrentUser.helpers.esql).toBeCalledTimes(1);
+      const esqlCallArgs = esClient.asCurrentUser.helpers.esql.mock.calls[0];
+      const query = esqlCallArgs[0].query;
+
+      // Verify fallback EVAL pinned = TO_STRING(null) is present
+      expect(query).toContain('EVAL pinned = TO_STRING(null)');
+    });
+  });
 });

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

@@ -39,6 +39,7 @@ interface BuildEsqlQueryParams {
   isEnrichPolicyExists: boolean;
   spaceId: string;
   alertsMappingsIncluded: boolean;
+  pinnedEntityIds?: string[];
 }
 
 export const fetchGraph = async ({
@@ -51,6 +52,7 @@ export const fetchGraph = async ({
   indexPatterns,
   spaceId,
   esQuery,
+  pinnedEntityIds,
 }: {
   esClient: IScopedClusterClient;
   logger: Logger;
@@ -61,6 +63,7 @@ export const fetchGraph = async ({
   indexPatterns: string[];
   spaceId: string;
   esQuery?: EsQuery;
+  pinnedEntityIds?: string[];
 }): Promise<EsqlToRecords<GraphEdge>> => {
   const originAlertIds = originEventIds.filter((originEventId) => originEventId.isAlert);
 
@@ -93,6 +96,7 @@ export const fetchGraph = async ({
     isEnrichPolicyExists,
     spaceId,
     alertsMappingsIncluded,
+    pinnedEntityIds,
   });
 
   logger.trace(`Executing query [${query}]`);
@@ -109,6 +113,7 @@ export const fetchGraph = async ({
         ...originEventIds
           .filter((originEventId) => originEventId.isAlert)
           .map((originEventId, idx) => ({ [`og_alrt_id${idx}`]: originEventId.id })),
+        ...(pinnedEntityIds ?? []).map((id, idx) => ({ [`pinned_id${idx}`]: id })),
       ],
     })
     .toRecords<GraphEdge>();
@@ -282,6 +287,7 @@ const buildEsqlQuery = ({
   isEnrichPolicyExists,
   spaceId,
   alertsMappingsIncluded,
+  pinnedEntityIds,
 }: BuildEsqlQueryParams): string => {
   const SECURITY_ALERTS_PARTIAL_IDENTIFIER = '.alerts-security.alerts-';
   const enrichPolicyName = getEnrichPolicyId(spaceId);
@@ -312,6 +318,21 @@ const buildEsqlQuery = ({
   const actorFieldHintCases = generateFieldHintCases(GRAPH_ACTOR_ENTITY_FIELDS, 'actorEntityId');
   const targetFieldHintCases = generateFieldHintCases(GRAPH_TARGET_ENTITY_FIELDS, 'targetEntityId');
 
+  // Generate pinned entity evaluation
+  // This checks if the current actor or target entity ID matches any of the pinned entity IDs
+  const pinnedEntityEval =
+    pinnedEntityIds && pinnedEntityIds.length > 0
+      ? `| EVAL pinned = CASE(
+    actorEntityId IN (${pinnedEntityIds
+      .map((_id, idx) => `?pinned_id${idx}`)
+      .join(', ')}), actorEntityId,
+    targetEntityId IN (${pinnedEntityIds
+      .map((_id, idx) => `?pinned_id${idx}`)
+      .join(', ')}), targetEntityId,
+    null
+  )`
+      : '| EVAL pinned = TO_STRING(null)';
+
   const query = `FROM ${indexPatterns
     .filter((indexPattern) => indexPattern.length > 0)
     .join(',')} METADATA _id, _index
@@ -325,6 +346,7 @@ const buildEsqlQuery = ({
 ${targetEntityIdEvals}
 | MV_EXPAND actorEntityId
 | MV_EXPAND targetEntityId
+${pinnedEntityEval}
 | EVAL actorEntityFieldHint = CASE(
 ${actorFieldHintCases},
     ""
@@ -452,7 +474,8 @@ ${buildEnrichedEntityFieldsEsql()}
       targetEntityType,
       targetEntitySubType,
       isOrigin,
-      isOriginAlert
+      isOriginAlert,
+      pinned
 | LIMIT 1000
 | SORT action DESC, isOrigin`;