[SecuritySolution] Create a Security Risk Scoring AI Assistant tool (elastic#233647)

## Summary


* Introduces a new AI Assistant tool that retrieves entity risk score
data.
* Enhances the alert contribution and anonymises it.
* Adds a button to the risk score contribution flyout tab that opens the
assistant with a preconfigured context and suggested query.
* Add an experimental flag: `riskScoreAssistantToolEnabled`

<img width="600" alt="Screenshot 2025-09-03 at 14 23 00"
src="https://github.com/user-attachments/assets/d8f93d4b-a058-403b-9d74-ee78a7abdd0e"
/>
<img width="600" alt="Screenshot 2025-09-03 at 14 41 24"
src="https://github.com/user-attachments/assets/24bcad0d-65b4-4e29-94c7-320678519380"
/>
<img width="600" alt="Screenshot 2025-09-03 at 14 22 31"
src="https://github.com/user-attachments/assets/f747ca1d-2c9a-4400-91ab-1d020b3e89d6"
/>

### How to test it?
**Basic scenario**
* Kibana installed with alerts data and AI connectors (Please reach out
if you need to configure a connector)
* Experimental flag enabled `riskScoreAssistantToolEnabled`
* Enable risk engine
* Open an entity flyout and expand the risk contributions tab
* Click "Explain with AI Assistant"
* It should open the flyout with a pre-configure prompt and context
* Send the prompt, and the Assistant should answer your question

**Asset that fields are properly anonymised**
* Kibana installed with alerts data and AI connectors (Please reach out
if you need to configure a connector)
* Experimental flag enabled `riskScoreAssistantToolEnabled`
* Enable risk engine
* Run Docker for Desktop
* Run phoenix `node scripts/phoenix.js`
* Open an entity flyout and expand the risk contributions tab
* Click "Explain with AI Assistant"
* It should open the flyout with a pre-configure prompt and context
* Send the prompt, and the Assistant should answer your question
* Open Phoenix web and assert that we don't send the entity data
(user.name, host.name) to the LLM
* You can also disable `user.name` and `host.name` fields anonymisation.
Please test different scenarios

**Disable scenario**
* Kibana installed with alerts data and AI connectors (Please reach out
if you need to configure a connector)
* Enable risk engine
* When the feature is disabled:
  * Option 1: Disable the AI assistant in the advanced settings
  * Option 2: Test with basic license
* Option 3: Experimental flag is disabled
`riskScoreAssistantToolEnabled`
* It should not display the button


*** To generate realistic risky alerts, you can use the Attack discovery
datascript: `node
x-pack/solutions/security/plugins/security_solution/scripts/load_attack_discovery_data.js`


*** Phoenix local config
```
# OTelemetry
# `node scripts/phoenix` from kibana root
telemetry.enabled: true
telemetry.tracing.enabled: true

telemetry.tracing.exporters.phoenix.base_url: "http://0.0.0.0:6006"
telemetry.tracing.exporters.phoenix.public_url: "http://0.0.0.0:6006"

```

### Checklist

Reviewers should verify this PR satisfies this list as well.

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

Author: machadoum

x-pack/solutions/security/plugins/elastic_assistant/server/lib/prompt/tool_prompts.ts

@@ -136,6 +136,14 @@ If no relevant information is found, inform the user you could not locate the re
         'Call this for knowledge about the latest n open and acknowledged alerts (sorted by `kibana.alert.risk_score`) in the environment, or when answering questions about open alerts. Do not call this tool for alert count or quantity. The output is an array of the latest n open and acknowledged alerts.',
     },
   },
+  {
+    promptId: 'EntityRiskScoreTool',
+    promptGroupId,
+    prompt: {
+      default:
+        "Call this for knowledge about the latest entity risk score and the inputs that contributed to the calculation (sorted by 'kibana.alert.risk_score') in the environment, or when answering questions about how critical or risky an entity is. When informing the risk score value for a entity you must use the normalized field 'calculated_score_norm'.",
+    },
+  },
   {
     promptId: 'defendInsightsTool',
     promptGroupId,

x-pack/solutions/security/plugins/elastic_assistant/server/lib/telemetry/event_based_telemetry.ts

@@ -72,6 +72,14 @@ export const KNOWLEDGE_BASE_EXECUTION_ERROR_EVENT: EventTypeOpts<{
   },
 };
 
+const toolCountSchema: SchemaValue<number | undefined> = {
+  type: 'long',
+  _meta: {
+    description: 'Number of times tool was invoked.',
+    optional: true,
+  },
+};
+
 export const INVOKE_ASSISTANT_SUCCESS_EVENT: EventTypeOpts<{
   assistantStreamingEnabled: boolean;
   actionTypeId: string;
@@ -87,6 +95,7 @@ export const INVOKE_ASSISTANT_SUCCESS_EVENT: EventTypeOpts<{
     SecurityLabsKnowledgeBaseTool?: number;
     ProductDocumentationTool?: number;
     CustomTool?: number;
+    EntityRiskScoreTool?: number;
   };
   model?: string;
   isOssModel?: boolean;
@@ -133,69 +142,16 @@ export const INVOKE_ASSISTANT_SUCCESS_EVENT: EventTypeOpts<{
     },
     toolsInvoked: {
       properties: {
-        AlertCountsTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        GenerateESQLTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        AskAboutESQLTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        ProductDocumentationTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        KnowledgeBaseRetrievalTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        KnowledgeBaseWriteTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        OpenAndAcknowledgedAlertsTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        SecurityLabsKnowledgeBaseTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
-        CustomTool: {
-          type: 'long',
-          _meta: {
-            description: 'Number of times tool was invoked.',
-            optional: true,
-          },
-        },
+        AlertCountsTool: toolCountSchema,
+        GenerateESQLTool: toolCountSchema,
+        AskAboutESQLTool: toolCountSchema,
+        ProductDocumentationTool: toolCountSchema,
+        KnowledgeBaseRetrievalTool: toolCountSchema,
+        KnowledgeBaseWriteTool: toolCountSchema,
+        OpenAndAcknowledgedAlertsTool: toolCountSchema,
+        SecurityLabsKnowledgeBaseTool: toolCountSchema,
+        CustomTool: toolCountSchema,
+        EntityRiskScoreTool: toolCountSchema,
       },
     },
   },

x-pack/solutions/security/plugins/security_solution/common/experimental_features.ts

@@ -125,6 +125,11 @@ export const allowedExperimentalValues = Object.freeze({
    */
   riskScoringRoutesEnabled: true,
 
+  /**
+   * Enables the Risk Score AI Assistant tool.
+   */
+  riskScoreAssistantToolEnabled: false,
+
   /**
    * disables ES|QL rules
    */

x-pack/solutions/security/plugins/security_solution/public/entity_analytics/components/entity_details_flyout/tabs/risk_inputs/ask_ai_assistant.test.tsx

@@ -0,0 +1,167 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { AskAiAssistant } from './ask_ai_assistant';
+import { TestProviders } from '../../../../../common/mock';
+import type { EntityType } from '../../../../../../common/search_strategy';
+
+// Hard code the generated anonymized value for easier testing
+const ANONYMIZED_VALUE = 'anonymized-value';
+jest.mock('@kbn/elastic-assistant-common', () => {
+  const actual = jest.requireActual('@kbn/elastic-assistant-common');
+  return {
+    ...actual,
+    getAnonymizedValue: () => ANONYMIZED_VALUE,
+  };
+});
+
+jest.mock('../../../../../common/hooks/use_experimental_features', () => {
+  const actual = jest.requireActual('../../../../../common/hooks/use_experimental_features');
+  return {
+    ...actual,
+    useIsExperimentalFeatureEnabled: jest.fn().mockReturnValue(true),
+  };
+});
+
+const mockUseFetchAnonymizationFields = jest.fn().mockReturnValue({
+  data: {
+    data: [],
+  },
+});
+
+jest.mock(
+  '@kbn/elastic-assistant/impl/assistant/api/anonymization_fields/use_fetch_anonymization_fields',
+  () => ({
+    useFetchAnonymizationFields: () => mockUseFetchAnonymizationFields(),
+  })
+);
+
+const mockUseAskInAiAssistant = jest.fn();
+jest.mock('./use_ask_ai_assistant', () => {
+  const actual = jest.requireActual('./use_ask_ai_assistant');
+  return {
+    ...actual,
+    useAskAiAssistant: (params: unknown) => mockUseAskInAiAssistant(params),
+  };
+});
+
+describe('ExplainWithAiAssistant', () => {
+  const defaultProps = {
+    entityType: 'user' as EntityType,
+    entityName: 'test-user',
+  };
+
+  const mockShowAssistantOverlay = jest.fn();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockUseFetchAnonymizationFields.mockReturnValue({
+      data: {
+        data: [{ field: 'user.name', allowed: true, anonymized: true }],
+      },
+    });
+    mockUseAskInAiAssistant.mockReturnValue({
+      showAssistantOverlay: mockShowAssistantOverlay,
+      disabled: false,
+    });
+  });
+
+  it('should render the button when AI assistant is enabled', () => {
+    render(<AskAiAssistant {...defaultProps} />, { wrapper: TestProviders });
+
+    expect(screen.getByTestId('explain-with-ai-button')).toBeInTheDocument();
+    expect(screen.getByText('Ask AI Assistant')).toBeInTheDocument();
+  });
+
+  it('should not render the button when AI assistant is disabled', () => {
+    mockUseAskInAiAssistant.mockReturnValue({
+      showAssistantOverlay: mockShowAssistantOverlay,
+      disabled: true,
+    });
+
+    const { container } = render(<AskAiAssistant {...defaultProps} />, {
+      wrapper: TestProviders,
+    });
+
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('should call showAssistantOverlay when button is clicked', () => {
+    render(<AskAiAssistant {...defaultProps} />, { wrapper: TestProviders });
+
+    const button = screen.getByTestId('explain-with-ai-button');
+    fireEvent.click(button);
+
+    expect(mockShowAssistantOverlay).toHaveBeenCalledTimes(1);
+  });
+
+  it('should handle missing anonymization fields data', () => {
+    mockUseFetchAnonymizationFields.mockReturnValue({
+      data: {
+        data: null,
+      },
+    });
+
+    render(<AskAiAssistant {...defaultProps} />, { wrapper: TestProviders });
+
+    expect(screen.getByTestId('explain-with-ai-button')).toBeInTheDocument();
+  });
+
+  it('should use original entity name when anonymized value is not available', () => {
+    mockUseFetchAnonymizationFields.mockReturnValue({
+      data: {
+        data: [],
+      },
+    });
+    render(<AskAiAssistant {...defaultProps} />, { wrapper: TestProviders });
+
+    expect(mockUseAskInAiAssistant).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Explain user 'test-user' Risk Score",
+        description: 'Entity: test-user',
+      })
+    );
+  });
+
+  it('should pass correct props to useExplainInAiAssistant hook', () => {
+    render(<AskAiAssistant {...defaultProps} />, { wrapper: TestProviders });
+
+    expect(mockUseAskInAiAssistant).toHaveBeenCalledWith({
+      title: "Explain user 'test-user' Risk Score",
+      description: 'Entity: test-user',
+      suggestedPrompt: expect.any(String),
+      getPromptContext: expect.any(Function),
+      replacements: expect.any(Object),
+    });
+  });
+
+  it('should generate prompt with anonymized field', async () => {
+    render(<AskAiAssistant {...defaultProps} />, { wrapper: TestProviders });
+
+    const getPromptContext = mockUseAskInAiAssistant.mock.calls[0][0].getPromptContext;
+    const promptContext = await getPromptContext();
+
+    expect(promptContext).toContain(`Identifier: \`${ANONYMIZED_VALUE}\``);
+  });
+
+  it('should work with different entity types', () => {
+    const hostProps = {
+      entityType: 'host' as EntityType,
+      entityName: 'test-host',
+    };
+
+    render(<AskAiAssistant {...hostProps} />, { wrapper: TestProviders });
+
+    expect(mockUseAskInAiAssistant).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Explain host 'test-host' Risk Score",
+      })
+    );
+  });
+});

x-pack/solutions/security/plugins/security_solution/public/entity_analytics/components/entity_details_flyout/tabs/risk_inputs/ask_ai_assistant.tsx

@@ -0,0 +1,93 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import React, { useCallback, useMemo } from 'react';
+import { EuiButton, EuiFlexGroup, EuiFlexItem, EuiSpacer } from '@elastic/eui';
+import { FormattedMessage } from '@kbn/i18n-react';
+import { AssistantIcon } from '@kbn/ai-assistant-icon';
+import { getAnonymizedValues } from '@kbn/elastic-assistant-common/impl/data_anonymization/get_anonymized_values';
+import { getAnonymizedValue } from '@kbn/elastic-assistant-common';
+import { useFetchAnonymizationFields } from '@kbn/elastic-assistant';
+import type { AnonymizedValues } from '@kbn/elastic-assistant-common/impl/data_anonymization/types';
+import { useIsExperimentalFeatureEnabled } from '../../../../../common/hooks/use_experimental_features';
+import { EntityTypeToIdentifierField } from '../../../../../../common/entity_analytics/types';
+import type { EntityType } from '../../../../../../common/search_strategy';
+import { useAskAiAssistant } from './use_ask_ai_assistant';
+
+export interface ExplainWithAiAssistantProps<T extends EntityType> {
+  entityType: T;
+  entityName: string;
+}
+
+const CURRENT_REPLACEMENTS = {} as const;
+
+export const AskAiAssistant = <T extends EntityType>({
+  entityType,
+  entityName,
+}: ExplainWithAiAssistantProps<T>) => {
+  const entityField = EntityTypeToIdentifierField[entityType];
+  const { data: anonymizationFields } = useFetchAnonymizationFields();
+  const isAssistantToolEnabled = useIsExperimentalFeatureEnabled('riskScoreAssistantToolEnabled');
+
+  const { anonymizedValues, replacements }: AnonymizedValues = useMemo(() => {
+    if (!anonymizationFields.data) {
+      return { anonymizedValues: [], replacements: CURRENT_REPLACEMENTS };
+    }
+
+    return getAnonymizedValues({
+      anonymizationFields: anonymizationFields.data,
+      currentReplacements: CURRENT_REPLACEMENTS,
+      field: entityField,
+      getAnonymizedValue,
+      rawData: { [entityField]: [entityName] },
+    });
+  }, [anonymizationFields, entityField, entityName]);
+
+  const anonymizedEntityName = anonymizedValues[0] ?? entityName;
+  const getPromptContext = useCallback(
+    async () =>
+      `### The following entity is under investigation:\nType: ${entityType}\nIdentifier: ${`\`${anonymizedEntityName}\``}`,
+    [anonymizedEntityName, entityType]
+  );
+
+  const { showAssistantOverlay, disabled: aiAssistantDisable } = useAskAiAssistant({
+    title: `Explain ${entityType} '${entityName}' Risk Score`,
+    description: `Entity: ${entityName}`,
+    suggestedPrompt: `Explain how inputs contributed to the risk score. Additionally, outline the recommended next steps for investigating or mitigating the risk if the entity is deemed risky.\nTo answer risk score questions, fetch the risk score information and take into consideration the risk score inputs.`,
+    getPromptContext,
+    replacements,
+  });
+
+  if (aiAssistantDisable || !isAssistantToolEnabled) {
+    return null;
+  }
+
+  return (
+    <>
+      <EuiSpacer size="m" />
+      <EuiFlexGroup justifyContent="flexEnd">
+        <EuiFlexItem grow={false}>
+          <EuiButton
+            data-test-subj="explain-with-ai-button"
+            iconType={AssistantIcon}
+            iconSide="right"
+            onClick={() => {
+              showAssistantOverlay();
+            }}
+          >
+            <FormattedMessage
+              id="xpack.securitySolution.flyout.entityDetails.riskInputs.askAiAssistant"
+              defaultMessage="Ask AI Assistant"
+            />
+          </EuiButton>
+        </EuiFlexItem>
+      </EuiFlexGroup>
+    </>
+  );
+};
+
+AskAiAssistant.displayName = 'ExplainWithAiAssistant';