Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Security Solution] Extend the /upgrade/_perform API endpoint's contract migrating to Zod #189790

Merged
merged 8 commits into from
Aug 5, 2024
Merged

[Security Solution] Extend the /upgrade/_perform API endpoint's contract migrating to Zod #189790

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6006a3d
Create schema
jpdjere Aug 2, 2024
1c69de0
remvoe legacy schema
jpdjere Aug 2, 2024
119b187
USe new types
jpdjere Aug 2, 2024
30283f7
Add comment
jpdjere Aug 2, 2024
b325afa
Fix switch
jpdjere Aug 2, 2024
da46e23
Address comments
jpdjere Aug 5, 2024
baaa1a8
Add unit tests
jpdjere Aug 5, 2024
9247384
Merge branch 'main' into create-upgrade-perform-schema
jpdjere Aug 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions ...ution/common/api/detection_engine/prebuilt_rules/model/aggregated_prebuilt_rules_error.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,17 @@
* 2.0.
*/

export interface AggregatedPrebuiltRuleError {
message: string;
status_code?: number;
rules: Array<{
rule_id: string;
name?: string;
}>;
}
import { z } from 'zod';
import { RuleName, RuleSignatureId } from '../../model/rule_schema/common_attributes.gen';

export type AggregatedPrebuiltRuleError = z.infer<typeof AggregatedPrebuiltRuleErrorSchema>;
export const AggregatedPrebuiltRuleErrorSchema = z.object({
message: z.string(),
status_code: z.number().optional(),
rules: z.array(
z.object({
rule_id: RuleSignatureId,
name: RuleName.optional(),
})
),
});
244 changes: 163 additions & 81 deletions ...on/api/detection_engine/prebuilt_rules/perform_rule_upgrade/perform_rule_upgrade_route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,94 +5,176 @@
* 2.0.
*/

import { enumeration } from '@kbn/securitysolution-io-ts-types';
import * as t from 'io-ts';
import { z } from 'zod';

import type { RuleResponse } from '../../model';
import type { AggregatedPrebuiltRuleError } from '../model';
import {
RuleSignatureId,
RuleVersion,
RuleName,
RuleTagArray,
RuleDescription,
Severity,
SeverityMapping,
RiskScore,
RiskScoreMapping,
RuleReferenceArray,
RuleFalsePositiveArray,
ThreatArray,
InvestigationGuide,
SetupGuide,
RelatedIntegrationArray,
RequiredFieldArray,
MaxSignals,
BuildingBlockType,
RuleIntervalFrom,
RuleInterval,
RuleExceptionList,
RuleNameOverride,
TimestampOverride,
TimestampOverrideFallbackDisabled,
TimelineTemplateId,
TimelineTemplateTitle,
IndexPatternArray,
DataViewId,
RuleQuery,
QueryLanguage,
RuleFilterArray,
SavedQueryId,
KqlQueryLanguage,
} from '../../model/rule_schema/common_attributes.gen';
import {
MachineLearningJobId,
AnomalyThreshold,
} from '../../model/rule_schema/specific_attributes/ml_attributes.gen';
import {
ThreatQuery,
ThreatMapping,
ThreatIndex,
ThreatFilters,
ThreatIndicatorPath,
} from '../../model/rule_schema/specific_attributes/threat_match_attributes.gen';
import {
NewTermsFields,
HistoryWindowStart,
} from '../../model/rule_schema/specific_attributes/new_terms_attributes.gen';
import { RuleResponse } from '../../model/rule_schema/rule_schemas.gen';
import { AggregatedPrebuiltRuleErrorSchema } from '../model';

export enum PickVersionValues {
BASE = 'BASE',
CURRENT = 'CURRENT',
TARGET = 'TARGET',
}
export type PickVersionValues = z.infer<typeof PickVersionValues>;
export const PickVersionValues = z.enum(['BASE', 'CURRENT', 'TARGET', 'MERGED']);
export type PickVersionValuesEnum = typeof PickVersionValues.enum;
export const PickVersionValuesEnum = PickVersionValues.enum;

export const TPickVersionValues = enumeration('PickVersionValues', PickVersionValues);
const createUpgradeFieldSchema = <T extends z.ZodType>(fieldSchema: T) =>
z
.union([
z.object({
pick_version: PickVersionValues,
}),
z.object({
pick_version: z.literal('RESOLVED'),
resolved_value: fieldSchema,
}),
])
.optional();

export const RuleUpgradeSpecifier = t.exact(
t.intersection([
t.type({
rule_id: t.string,
/**
* This parameter is needed for handling race conditions with Optimistic Concurrency Control.
* Two or more users can call upgrade/_review and upgrade/_perform endpoints concurrently.
* Also, in general the time between these two calls can be anything.
* The idea is to only allow the user to install a rule if the user has reviewed the exact version
* of it that had been returned from the _review endpoint. If the version changed on the BE,
* upgrade/_perform endpoint will return a version mismatch error for this rule.
*/
revision: t.number,
/**
* The target version to upgrade to.
*/
version: t.number,
}),
t.partial({
pick_version: TPickVersionValues,
}),
])
);
export type RuleUpgradeSpecifier = t.TypeOf<typeof RuleUpgradeSpecifier>;
export type RuleUpgradeSpecifier = z.infer<typeof RuleUpgradeSpecifier>;
export const RuleUpgradeSpecifier = z.object({
rule_id: RuleSignatureId,
revision: z.number(),
version: RuleVersion,
pick_version: PickVersionValues.optional(),
// Fields that can be customized during the upgrade workflow
// as decided in: https://github.com/elastic/kibana/issues/186544
fields: z
.object({
name: createUpgradeFieldSchema(RuleName),
tags: createUpgradeFieldSchema(RuleTagArray),
description: createUpgradeFieldSchema(RuleDescription),
severity: createUpgradeFieldSchema(Severity),
severity_mapping: createUpgradeFieldSchema(SeverityMapping),
risk_score: createUpgradeFieldSchema(RiskScore),
risk_score_mapping: createUpgradeFieldSchema(RiskScoreMapping),
references: createUpgradeFieldSchema(RuleReferenceArray),
false_positives: createUpgradeFieldSchema(RuleFalsePositiveArray),
threat: createUpgradeFieldSchema(ThreatArray),
note: createUpgradeFieldSchema(InvestigationGuide),
setup: createUpgradeFieldSchema(SetupGuide),
related_integrations: createUpgradeFieldSchema(RelatedIntegrationArray),
required_fields: createUpgradeFieldSchema(RequiredFieldArray),
max_signals: createUpgradeFieldSchema(MaxSignals),
building_block_type: createUpgradeFieldSchema(BuildingBlockType),
from: createUpgradeFieldSchema(RuleIntervalFrom),
interval: createUpgradeFieldSchema(RuleInterval),
exceptions_list: createUpgradeFieldSchema(RuleExceptionList),
rule_name_override: createUpgradeFieldSchema(RuleNameOverride),
timestamp_override: createUpgradeFieldSchema(TimestampOverride),
timestamp_override_fallback_disabled: createUpgradeFieldSchema(
TimestampOverrideFallbackDisabled
),
timeline_id: createUpgradeFieldSchema(TimelineTemplateId),
timeline_title: createUpgradeFieldSchema(TimelineTemplateTitle),
index: createUpgradeFieldSchema(IndexPatternArray),
data_view_id: createUpgradeFieldSchema(DataViewId),
query: createUpgradeFieldSchema(RuleQuery),
language: createUpgradeFieldSchema(QueryLanguage),
filters: createUpgradeFieldSchema(RuleFilterArray),
saved_id: createUpgradeFieldSchema(SavedQueryId),
machine_learning_job_id: createUpgradeFieldSchema(MachineLearningJobId),
anomaly_threshold: createUpgradeFieldSchema(AnomalyThreshold),
threat_query: createUpgradeFieldSchema(ThreatQuery),
threat_mapping: createUpgradeFieldSchema(ThreatMapping),
threat_index: createUpgradeFieldSchema(ThreatIndex),
threat_filters: createUpgradeFieldSchema(ThreatFilters),
threat_indicator_path: createUpgradeFieldSchema(ThreatIndicatorPath),
threat_language: createUpgradeFieldSchema(KqlQueryLanguage),
new_terms_fields: createUpgradeFieldSchema(NewTermsFields),
history_window_start: createUpgradeFieldSchema(HistoryWindowStart),
})
.optional(),
});

export type UpgradeSpecificRulesRequest = t.TypeOf<typeof UpgradeSpecificRulesRequest>;
export const UpgradeSpecificRulesRequest = t.exact(
t.intersection([
t.type({
mode: t.literal(`SPECIFIC_RULES`),
rules: t.array(RuleUpgradeSpecifier),
}),
t.partial({
pick_version: TPickVersionValues,
}),
])
);
export type UpgradeSpecificRulesRequest = z.infer<typeof UpgradeSpecificRulesRequest>;
export const UpgradeSpecificRulesRequest = z.object({
mode: z.literal('SPECIFIC_RULES'),
rules: z.array(RuleUpgradeSpecifier),
pick_version: PickVersionValues.optional(),
});

export const UpgradeAllRulesRequest = t.exact(
t.intersection([
t.type({
mode: t.literal(`ALL_RULES`),
}),
t.partial({
pick_version: TPickVersionValues,
}),
])
);
export type UpgradeAllRulesRequest = z.infer<typeof UpgradeAllRulesRequest>;
export const UpgradeAllRulesRequest = z.object({
mode: z.literal('ALL_RULES'),
pick_version: PickVersionValues.optional(),
});

export const PerformRuleUpgradeRequestBody = t.union([
UpgradeAllRulesRequest,
UpgradeSpecificRulesRequest,
]);
export type PerformRuleUpgradeRequestBody = t.TypeOf<typeof PerformRuleUpgradeRequestBody>;
export type SkipRuleUpgradeReason = z.infer<typeof SkipRuleUpgradeReason>;
export const SkipRuleUpgradeReason = z.enum(['RULE_UP_TO_DATE']);
export type SkipRuleUpgradeReasonEnum = typeof SkipRuleUpgradeReason.enum;
export const SkipRuleUpgradeReasonEnum = SkipRuleUpgradeReason.enum;

export enum SkipRuleUpgradeReason {
RULE_UP_TO_DATE = 'RULE_UP_TO_DATE',
}
export type SkippedRuleUpgrade = z.infer<typeof SkippedRuleUpgrade>;
export const SkippedRuleUpgrade = z.object({
rule_id: z.string(),
reason: SkipRuleUpgradeReason,
});

export interface SkippedRuleUpgrade {
rule_id: string;
reason: SkipRuleUpgradeReason;
}
export type PerformRuleUpgradeResponseBody = z.infer<typeof PerformRuleUpgradeResponseBody>;
export const PerformRuleUpgradeResponseBody = z.object({
summary: z.object({
total: z.number(),
succeeded: z.number(),
skipped: z.number(),
failed: z.number(),
}),
results: z.object({
updated: z.array(RuleResponse),
skipped: z.array(SkippedRuleUpgrade),
}),
errors: z.array(AggregatedPrebuiltRuleErrorSchema),
});

export interface PerformRuleUpgradeResponseBody {
summary: {
total: number;
succeeded: number;
skipped: number;
failed: number;
};
results: {
updated: RuleResponse[];
skipped: SkippedRuleUpgrade[];
};
errors: AggregatedPrebuiltRuleError[];
}
export type PerformRuleUpgradeRequestBody = z.infer<typeof PerformRuleUpgradeRequestBody>;
export const PerformRuleUpgradeRequestBody = z.union([
UpgradeAllRulesRequest,
UpgradeSpecificRulesRequest,
]);
23 changes: 14 additions & 9 deletions ...ib/detection_engine/prebuilt_rules/api/perform_rule_upgrade/perform_rule_upgrade_route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,19 @@
*/

import { transformError } from '@kbn/securitysolution-es-utils';
import { buildRouteValidationWithZod } from '@kbn/zod-helpers';
import {
PERFORM_RULE_UPGRADE_URL,
SkipRuleUpgradeReason,
PerformRuleUpgradeRequestBody,
PickVersionValues,
PickVersionValuesEnum,
SkipRuleUpgradeReasonEnum,
} from '../../../../../../common/api/detection_engine/prebuilt_rules';
import type {
PerformRuleUpgradeResponseBody,
SkippedRuleUpgrade,
} from '../../../../../../common/api/detection_engine/prebuilt_rules';
import { assertUnreachable } from '../../../../../../common/utility_types';
import type { SecuritySolutionPluginRouter } from '../../../../../types';
import { buildRouteValidation } from '../../../../../utils/build_validation/route_validation';
import type { PromisePoolError } from '../../../../../utils/promise_pool';
import { buildSiemResponse } from '../../../routes/utils';
import { aggregatePrebuiltRuleErrors } from '../../logic/aggregate_prebuilt_rule_errors';
Expand Down Expand Up @@ -48,7 +48,7 @@ export const performRuleUpgradeRoute = (router: SecuritySolutionPluginRouter) =>
version: '1',
validate: {
request: {
body: buildRouteValidation(PerformRuleUpgradeRequestBody),
body: buildRouteValidationWithZod(PerformRuleUpgradeRequestBody),
},
},
},
Expand All @@ -63,7 +63,8 @@ export const performRuleUpgradeRoute = (router: SecuritySolutionPluginRouter) =>
const ruleAssetsClient = createPrebuiltRuleAssetsClient(soClient);
const ruleObjectsClient = createPrebuiltRuleObjectsClient(rulesClient);

const { mode, pick_version: globalPickVersion = PickVersionValues.TARGET } = request.body;
const { mode, pick_version: globalPickVersion = PickVersionValuesEnum.TARGET } =
request.body;

const fetchErrors: Array<PromisePoolError<{ rule_id: string }>> = [];
const targetRules: PrebuiltRuleAsset[] = [];
Expand Down Expand Up @@ -105,7 +106,7 @@ export const performRuleUpgradeRoute = (router: SecuritySolutionPluginRouter) =>
if (!upgradeableRuleIds.has(rule.rule_id)) {
skippedRules.push({
rule_id: rule.rule_id,
reason: SkipRuleUpgradeReason.RULE_UP_TO_DATE,
reason: SkipRuleUpgradeReasonEnum.RULE_UP_TO_DATE,
});
return;
}
Expand All @@ -132,7 +133,7 @@ export const performRuleUpgradeRoute = (router: SecuritySolutionPluginRouter) =>
const rulePickVersion =
versionSpecifiersMap?.get(current.rule_id)?.pick_version ?? globalPickVersion;
switch (rulePickVersion) {
case PickVersionValues.BASE:
case PickVersionValuesEnum.BASE:
const baseVersion = ruleVersionsMap.get(current.rule_id)?.base;
if (baseVersion) {
targetRules.push({ ...baseVersion, version: target.version });
Expand All @@ -143,10 +144,14 @@ export const performRuleUpgradeRoute = (router: SecuritySolutionPluginRouter) =>
});
}
break;
case PickVersionValues.CURRENT:
case PickVersionValuesEnum.CURRENT:
targetRules.push({ ...current, version: target.version });
break;
case PickVersionValues.TARGET:
case PickVersionValuesEnum.TARGET:
targetRules.push(target);
break;
case PickVersionValuesEnum.MERGED:
// TODO: Implement functionality to handle MERGED
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is an internal endpoint, and we don't use MERGED yet, this should be safe. Defaulting to updating to TARGET anyways, until actual endpoint implementation is finished.

targetRules.push(target);
break;
default:
Expand Down