Skip to content

Commit

Permalink
[Security Solution][Detection Engine] deprecates siem signals migrati…
Browse files Browse the repository at this point in the history
…on APIs (elastic#202662)

## Summary

 - addresses part of elastic#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 <[email protected]>
  • Loading branch information
vitaliidm and kibanamachine authored Dec 10, 2024
1 parent 6e145f9 commit 3d46ead
Show file tree
Hide file tree
Showing 17 changed files with 76 additions and 12 deletions.
4 changes: 4 additions & 0 deletions oas_docs/output/kibana.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down
1 change: 1 addition & 0 deletions src/platform/packages/shared/kbn-doc-links/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -372,6 +372,7 @@ export interface DocLinks {
readonly assetCriticality: string;
};
readonly detectionEngineOverview: string;
readonly signalsMigrationApi: string;
};
readonly query: {
readonly eql: string;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1136,6 +1138,7 @@ paths:
- Security Detections API
- Alerts migration API
post:
deprecated: true
description: >
Initiate a migration of detection alerts.
Expand Down Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand All @@ -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();
Expand All @@ -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 () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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,
Expand All @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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,
Expand All @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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({
Expand All @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,19 @@ 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');
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({
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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,
Expand All @@ -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);
Expand Down
1 change: 1 addition & 0 deletions x-pack/plugins/security_solution/server/plugin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,7 @@ export class Plugin implements ISecuritySolutionPlugin {
previewRuleDataClient,
this.telemetryReceiver,
this.pluginContext.env.packageInfo.buildFlavor === 'serverless',
core.docLinks,
this.endpointContext
);

Expand Down
11 changes: 6 additions & 5 deletions x-pack/plugins/security_solution/server/routes/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -81,6 +81,7 @@ export const initRoutes = (
previewRuleDataClient: IRuleDataClient,
previewTelemetryReceiver: ITelemetryReceiver,
isServerless: boolean,
docLinks: DocLinksServiceSetup,
endpointContext: EndpointAppContext
) => {
registerFleetIntegrationsRoutes(router);
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 3d46ead

Please sign in to comment.