[Security Solution][Detection Engine] deprecates siem signals migration APIs (#202662)

## Summary

 - addresses part of https://github.com/elastic/kibana/issues/195523
- deprecates
https://www.elastic.co/guide/en/security/current/signals-migration-api.html
APIs according to internal 9.x readiness
[guideline](https://docs.google.com/document/d/1W7csjn6QYjrBjmbXMzSz_JUD4KcmWz8jTTtAWFwgUJM/edit?tab=t.0#heading=h.tui2zvb9gca6)
 
#### How to test deprecated APIs?

1. Run API
https://www.elastic.co/guide/en/security/current/signals-migration-api.html
2. Observe warning deprecation on Kibana Upgrade page

<img width="2540" alt="Screenshot 2024-12-03 at 10 43 59"
src="https://github.com/user-attachments/assets/24fcebb9-2d31-4ca3-a0dc-4ed7861d26a2">

---------

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

oas_docs/output/kibana.yaml

@@ -11087,6 +11087,7 @@ paths:
         - Security Detections API
   /api/detection_engine/signals/finalize_migration:
     post:
+      deprecated: true
       description: |
         Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias.
         The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion,
@@ -11141,6 +11142,7 @@ paths:
         - Security Detections API
   /api/detection_engine/signals/migration:
     delete:
+      deprecated: true
       description: |
         Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
         the migration process. A successful migration will result in both the old and new indices being present.
@@ -11198,6 +11200,7 @@ paths:
       tags:
         - Security Detections API
     post:
+      deprecated: true
       description: |
         Initiate a migration of detection alerts.
         Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly.
@@ -11261,6 +11264,7 @@ paths:
         - Security Detections API
   /api/detection_engine/signals/migration_status:
     post:
+      deprecated: true
       description: Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices.
       operationId: ReadAlertsMigrationStatus
       parameters:

src/platform/packages/shared/kbn-doc-links/src/get_doc_links.ts

@@ -504,6 +504,7 @@ export const getDocLinks = ({ kibanaBranch, buildFlavor }: GetDocLinkOptions): D
       },
       detectionEngineOverview: `${SECURITY_SOLUTION_DOCS}detection-engine-overview.html`,
       aiAssistant: `${SECURITY_SOLUTION_DOCS}security-assistant.html`,
+      signalsMigrationApi: `${SECURITY_SOLUTION_DOCS}signals-migration-api.html`,
     },
     query: {
       eql: `${ELASTICSEARCH_DOCS}eql.html`,

src/platform/packages/shared/kbn-doc-links/src/types.ts

@@ -372,6 +372,7 @@ export interface DocLinks {
       readonly assetCriticality: string;
     };
     readonly detectionEngineOverview: string;
+    readonly signalsMigrationApi: string;
   };
   readonly query: {
     readonly eql: string;

x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml

@@ -9,6 +9,7 @@ paths:
       operationId: CreateAlertsMigration
       x-codegen-enabled: true
       summary: Initiate a detection alert migration
+      deprecated: true
       description: |
         Initiate a migration of detection alerts.
         Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly.

x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml

@@ -9,6 +9,7 @@ paths:
       operationId: AlertsMigrationCleanup
       x-codegen-enabled: true
       summary: Clean up detection alert migrations
+      deprecated: true
       description: |
         Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
         the migration process. A successful migration will result in both the old and new indices being present.

x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml

@@ -9,6 +9,7 @@ paths:
       operationId: FinalizeAlertsMigration
       x-codegen-enabled: true
       summary: Finalize detection alert migrations
+      deprecated: true
       description: |
         Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias.
         The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion,

x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/read_signals_migration_status/read_signals_migration_status.schema.yaml

@@ -9,6 +9,7 @@ paths:
       operationId: ReadAlertsMigrationStatus
       x-codegen-enabled: true
       summary: Retrieve the status of detection alert migrations
+      deprecated: true
       description: Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices.
       tags:
         - Alerts migration API

x-pack/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml

@@ -1010,6 +1010,7 @@ paths:
         - Security Detections API
   /api/detection_engine/signals/finalize_migration:
     post:
+      deprecated: true
       description: >
         Finalize successful migrations of detection alerts. This replaces the
         original index's alias with the successfully migrated index's alias.
@@ -1069,6 +1070,7 @@ paths:
         - Alerts migration API
   /api/detection_engine/signals/migration:
     delete:
+      deprecated: true
       description: >
         Migrations favor data integrity over shard size. Consequently, unused or
         orphaned indices are artifacts of
@@ -1136,6 +1138,7 @@ paths:
         - Security Detections API
         - Alerts migration API
     post:
+      deprecated: true
       description: >
         Initiate a migration of detection alerts.
 
@@ -1204,6 +1207,7 @@ paths:
         - Alerts migration API
   /api/detection_engine/signals/migration_status:
     post:
+      deprecated: true
       description: >-
         Retrieve indices that contain detection alerts of a particular age,
         along with migration information for each of those indices.

x-pack/plugins/security_solution/server/lib/detection_engine/routes/signals/create_signals_migration_route.test.ts

@@ -16,6 +16,7 @@ import { getTemplateVersion } from '../index/check_template_version';
 import { createSignalsMigrationRoute } from './create_signals_migration_route';
 import { SIGNALS_TEMPLATE_VERSION } from '../index/get_signals_template';
 import type { AlertsReindexOptions } from '../../../../../common/api/detection_engine/signals_migration';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 jest.mock('../index/check_template_version');
 jest.mock('@kbn/securitysolution-es-utils', () => {
@@ -31,6 +32,7 @@ jest.mock('../../migrations/get_signal_versions_by_index');
 
 describe('creating signals migrations route', () => {
   let server: ReturnType<typeof serverMock.create>;
+  const docLinks = docLinksServiceMock.createSetupContract();
 
   beforeEach(() => {
     server = serverMock.create();
@@ -42,7 +44,7 @@ describe('creating signals migrations route', () => {
     (getIndexVersionsByIndex as jest.Mock).mockResolvedValue({ 'my-signals-index': -1 });
     (getSignalVersionsByIndex as jest.Mock).mockResolvedValue({ 'my-signals-index': [] });
 
-    createSignalsMigrationRoute(server.router);
+    createSignalsMigrationRoute(server.router, docLinks);
   });
 
   it('passes options to the createMigration', async () => {

x-pack/plugins/security_solution/server/lib/detection_engine/routes/signals/create_signals_migration_route.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { transformError, BadRequestError, getIndexAliases } from '@kbn/securitysolution-es-utils';
 import { buildRouteValidationWithZod } from '@kbn/zod-helpers';
 import { CreateAlertsMigrationRequestBody } from '../../../../../common/api/detection_engine/signals_migration';
@@ -19,7 +20,10 @@ import { isOutdated, signalsAreOutdated } from '../../migrations/helpers';
 import { getIndexVersionsByIndex } from '../../migrations/get_index_versions_by_index';
 import { getSignalVersionsByIndex } from '../../migrations/get_signal_versions_by_index';
 
-export const createSignalsMigrationRoute = (router: SecuritySolutionPluginRouter) => {
+export const createSignalsMigrationRoute = (
+  router: SecuritySolutionPluginRouter,
+  docLinks: DocLinksServiceSetup
+) => {
   router.versioned
     .post({
       path: DETECTION_ENGINE_SIGNALS_MIGRATION_URL,
@@ -36,6 +40,13 @@ export const createSignalsMigrationRoute = (router: SecuritySolutionPluginRouter
         validate: {
           request: { body: buildRouteValidationWithZod(CreateAlertsMigrationRequestBody) },
         },
+        options: {
+          deprecated: {
+            documentationUrl: docLinks.links.securitySolution.signalsMigrationApi,
+            severity: 'warning',
+            reason: { type: 'remove' },
+          },
+        },
       },
       async (context, request, response) => {
         const siemResponse = buildSiemResponse(response);

x-pack/plugins/security_solution/server/lib/detection_engine/routes/signals/delete_signals_migration_route.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { transformError } from '@kbn/securitysolution-es-utils';
 import { buildRouteValidationWithZod } from '@kbn/zod-helpers';
 import { AlertsMigrationCleanupRequestBody } from '../../../../../common/api/detection_engine/signals_migration';
@@ -15,7 +16,10 @@ import { buildSiemResponse } from '../utils';
 import { signalsMigrationService } from '../../migrations/migration_service';
 import { getMigrationSavedObjectsById } from '../../migrations/get_migration_saved_objects_by_id';
 
-export const deleteSignalsMigrationRoute = (router: SecuritySolutionPluginRouter) => {
+export const deleteSignalsMigrationRoute = (
+  router: SecuritySolutionPluginRouter,
+  docLinks: DocLinksServiceSetup
+) => {
   router.versioned
     .delete({
       path: DETECTION_ENGINE_SIGNALS_MIGRATION_URL,
@@ -32,6 +36,13 @@ export const deleteSignalsMigrationRoute = (router: SecuritySolutionPluginRouter
         validate: {
           request: { body: buildRouteValidationWithZod(AlertsMigrationCleanupRequestBody) },
         },
+        options: {
+          deprecated: {
+            documentationUrl: docLinks.links.securitySolution.signalsMigrationApi,
+            severity: 'warning',
+            reason: { type: 'remove' },
+          },
+        },
       },
       async (context, request, response) => {
         const siemResponse = buildSiemResponse(response);

x-pack/plugins/security_solution/server/lib/detection_engine/routes/signals/finalize_signals_migration_route.test.ts

@@ -12,18 +12,20 @@ import { getSignalsMigrationSavedObjectMock } from '../../migrations/saved_objec
 import { finalizeSignalsMigrationRoute } from './finalize_signals_migration_route';
 import type { RuleDataPluginService } from '@kbn/rule-registry-plugin/server';
 import { ruleDataServiceMock } from '@kbn/rule-registry-plugin/server/rule_data_plugin_service/rule_data_plugin_service.mock';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 jest.mock('../../migrations/get_migration_saved_objects_by_id');
 
 describe('finalizing signals migrations', () => {
   let server: ReturnType<typeof serverMock.create>;
+  const docLinks = docLinksServiceMock.createSetupContract();
 
   beforeEach(() => {
     server = serverMock.create();
 
     const ruleDataPluginServiceMock =
       ruleDataServiceMock.create() as unknown as RuleDataPluginService;
-    finalizeSignalsMigrationRoute(server.router, ruleDataPluginServiceMock);
+    finalizeSignalsMigrationRoute(server.router, ruleDataPluginServiceMock, docLinks);
   });
 
   it('returns an empty array error if no migrations exists', async () => {

x-pack/plugins/security_solution/server/lib/detection_engine/routes/signals/finalize_signals_migration_route.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { transformError, BadRequestError } from '@kbn/securitysolution-es-utils';
 import type { RuleDataPluginService } from '@kbn/rule-registry-plugin/server';
 import { buildRouteValidationWithZod } from '@kbn/zod-helpers';
@@ -19,7 +20,8 @@ import { getMigrationSavedObjectsById } from '../../migrations/get_migration_sav
 
 export const finalizeSignalsMigrationRoute = (
   router: SecuritySolutionPluginRouter,
-  ruleDataService: RuleDataPluginService
+  ruleDataService: RuleDataPluginService,
+  docLinks: DocLinksServiceSetup
 ) => {
   router.versioned
     .post({
@@ -37,6 +39,13 @@ export const finalizeSignalsMigrationRoute = (
         validate: {
           request: { body: buildRouteValidationWithZod(FinalizeAlertsMigrationRequestBody) },
         },
+        options: {
+          deprecated: {
+            documentationUrl: docLinks.links.securitySolution.signalsMigrationApi,
+            severity: 'warning',
+            reason: { type: 'remove' },
+          },
+        },
       },
       async (context, request, response) => {
         const siemResponse = buildSiemResponse(response);

x-pack/plugins/security_solution/server/lib/detection_engine/routes/signals/get_signals_migration_status_route.test.ts

@@ -12,6 +12,7 @@ import { getMigrationSavedObjectsByIndex } from '../../migrations/get_migration_
 import { getSignalVersionsByIndex } from '../../migrations/get_signal_versions_by_index';
 import { getSignalsMigrationStatusRoute } from './get_signals_migration_status_route';
 import { getSignalsIndicesInRange } from '../../migrations/get_signals_indices_in_range';
+import { docLinksServiceMock } from '@kbn/core/server/mocks';
 
 jest.mock('../../migrations/get_signals_indices_in_range');
 jest.mock('../../migrations/get_signal_versions_by_index');
@@ -19,10 +20,11 @@ jest.mock('../../migrations/get_migration_saved_objects_by_index');
 
 describe('get signals migration status', () => {
   let server: ReturnType<typeof serverMock.create>;
+  const docLinks = docLinksServiceMock.createSetupContract();
 
   beforeEach(() => {
     server = serverMock.create();
-    getSignalsMigrationStatusRoute(server.router);
+    getSignalsMigrationStatusRoute(server.router, docLinks);
 
     (getSignalsIndicesInRange as jest.Mock).mockResolvedValueOnce(['my-signals-index']);
     (getSignalVersionsByIndex as jest.Mock).mockResolvedValueOnce({

x-pack/plugins/security_solution/server/lib/detection_engine/routes/signals/get_signals_migration_status_route.ts

@@ -5,6 +5,7 @@
  * 2.0.
  */
 
+import type { DocLinksServiceSetup } from '@kbn/core/server';
 import { transformError, getIndexAliases } from '@kbn/securitysolution-es-utils';
 import { buildRouteValidationWithZod } from '@kbn/zod-helpers';
 import { ReadAlertsMigrationStatusRequestQuery } from '../../../../../common/api/detection_engine/signals_migration';
@@ -18,7 +19,10 @@ import { isOutdated, signalsAreOutdated } from '../../migrations/helpers';
 import { getTemplateVersion } from '../index/check_template_version';
 import { buildSiemResponse } from '../utils';
 
-export const getSignalsMigrationStatusRoute = (router: SecuritySolutionPluginRouter) => {
+export const getSignalsMigrationStatusRoute = (
+  router: SecuritySolutionPluginRouter,
+  docLinks: DocLinksServiceSetup
+) => {
   router.versioned
     .get({
       path: DETECTION_ENGINE_SIGNALS_MIGRATION_STATUS_URL,
@@ -35,6 +39,13 @@ export const getSignalsMigrationStatusRoute = (router: SecuritySolutionPluginRou
         validate: {
           request: { query: buildRouteValidationWithZod(ReadAlertsMigrationStatusRequestQuery) },
         },
+        options: {
+          deprecated: {
+            documentationUrl: docLinks.links.securitySolution.signalsMigrationApi,
+            severity: 'warning',
+            reason: { type: 'remove' },
+          },
+        },
       },
       async (context, request, response) => {
         const siemResponse = buildSiemResponse(response);

x-pack/plugins/security_solution/server/plugin.ts

@@ -397,6 +397,7 @@ export class Plugin implements ISecuritySolutionPlugin {
       previewRuleDataClient,
       this.telemetryReceiver,
       this.pluginContext.env.packageInfo.buildFlavor === 'serverless',
+      core.docLinks,
       this.endpointContext
     );
 

x-pack/plugins/security_solution/server/routes/index.ts

@@ -5,7 +5,7 @@
  * 2.0.
  */
 
-import type { StartServicesAccessor, Logger } from '@kbn/core/server';
+import type { StartServicesAccessor, Logger, DocLinksServiceSetup } from '@kbn/core/server';
 import type { IRuleDataClient, RuleDataPluginService } from '@kbn/rule-registry-plugin/server';
 
 import type { EndpointAppContext } from '../endpoint/types';
@@ -81,6 +81,7 @@ export const initRoutes = (
   previewRuleDataClient: IRuleDataClient,
   previewTelemetryReceiver: ITelemetryReceiver,
   isServerless: boolean,
+  docLinks: DocLinksServiceSetup,
   endpointContext: EndpointAppContext
 ) => {
   registerFleetIntegrationsRoutes(router);
@@ -114,10 +115,10 @@ export const initRoutes = (
   setAlertTagsRoute(router);
   setAlertAssigneesRoute(router);
   querySignalsRoute(router, ruleDataClient);
-  getSignalsMigrationStatusRoute(router);
-  createSignalsMigrationRoute(router);
-  finalizeSignalsMigrationRoute(router, ruleDataService);
-  deleteSignalsMigrationRoute(router);
+  getSignalsMigrationStatusRoute(router, docLinks);
+  createSignalsMigrationRoute(router, docLinks);
+  finalizeSignalsMigrationRoute(router, ruleDataService, docLinks);
+  deleteSignalsMigrationRoute(router, docLinks);
   suggestUserProfilesRoute(router, getStartServices);
 
   // Detection Engine index routes that have the REST endpoints of /api/detection_engine/index