Skip to content

Commit

Permalink
[Security Solution] Add UI incentivizers to upgrade prebuilt rules (e…
Browse files Browse the repository at this point in the history
…lastic#211862)

## Summary

Partially addresses elastic#210358

Adds all callouts and logic to incentivize users to upgrade their rules asap. These include:

- [x] Showing a callout on the Rule Management page
- [x] Showing a callout on the Rule Details page
  - [x] Letting users open the Rule Upgrade flyout from the Rule Details page
- [x] Showing a callout on the Rule Editing page
- [x] Showing a callout in the Rule Upgrade flyout if rule has missing base version

This PR also adds related updates to the rule diff algorithms in order to facilitate an easier upgrade experience when rules have missing base versions. These include:

- [x] When the rule has a missing base version and is NOT marked as customized:
  - [x] We should return all the target fields from the diff algorithm as NO_CONFLICT
- [x] When the rule has a missing base version and is marked as customized:
  - [x] We should attempt to merge all non-functional mergeable fields (any field that doesn't have consequences with how the rule runs e.g. tags) and return them as `SOLVABLE_CONFLICT`.
    - **NOTE**: When base versions are missing and the rule is customized, we attempt to merge all mergable, non-functional rule fields. These include all fields covered by the scalar diff array (`tags`, `references`, `new_terms_fields`, `threat_index`). We typically also consider multi-line string fields as mergeable but without three versions of the string, we are currently unable to merge the strings together, so we just return target version.
  - [x] We should pick the target version for all functional mergeable fields (e.g. `index`) and non-mergeable fields and return them as `SOLVABLE_CONFLICT`.

### Screenshots

**Callout on Rule details page w/ flyout button**
![Screenshot 2025-03-03 at 3 58 17 PM](https://github.com/user-attachments/assets/77117cad-fd8c-4b37-8ef7-f66d77f373b8)

---

**Upgrade flyout now accessible from rule details page**
![Screenshot 2025-03-03 at 3 58 25 PM](https://github.com/user-attachments/assets/f78e10fe-0767-44ab-a9c9-a5ae616b8b0e)

---

**Callout on rule editing page**
![Screenshot 2025-03-03 at 3 58 38 PM](https://github.com/user-attachments/assets/be68420f-a612-4e3d-9139-ad65a3d8b9fc)

---

**Dismissible callout on rule management page**
![Screenshot 2025-03-03 at 3 57 52 PM](https://github.com/user-attachments/assets/5227a4d1-474a-44d2-b0bb-fc020e584e8e)

---

**Callout in rule upgrade flyout when rule has missing base version**
![Screenshot 2025-03-03 at 3 58 04 PM](https://github.com/user-attachments/assets/3c1a23fa-f1f0-4301-b392-4c91097a9cb9)

### Checklist

Check the PR satisfies following conditions.

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

(cherry picked from commit 461787b)
  • Loading branch information
dplumlee committed Mar 5, 2025
1 parent ecca188 commit 6eddfbb
Show file tree
Hide file tree
Showing 56 changed files with 2,051 additions and 1,062 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -145,5 +145,6 @@ export interface ThreeWayDiff<TValue> {
* Given the three versions of a value, calculates a three-way diff for it.
*/
export type ThreeWayDiffAlgorithm<TValue> = (
versions: ThreeVersionsOf<TValue>
versions: ThreeVersionsOf<TValue>,
isRuleCustomized: boolean
) => ThreeWayDiff<TValue>;
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import { SortOrder, type RuleObjectId, type RuleSignatureId, type RuleTagArray }
import type { PartialRuleDiff } from '../model';
import type { RuleResponse, RuleVersion } from '../../model/rule_schema';
import { FindRulesSortField } from '../../rule_management';
import { PrebuiltRulesFilter } from '../common/prebuilt_rules_filter';
import { ReviewPrebuiltRuleUpgradeFilter } from '../common/review_prebuilt_rules_upgrade_filter';

export type ReviewRuleUpgradeSort = z.infer<typeof ReviewRuleUpgradeSort>;
export const ReviewRuleUpgradeSort = z.object({
Expand All @@ -27,7 +27,7 @@ export const ReviewRuleUpgradeSort = z.object({
export type ReviewRuleUpgradeRequestBody = z.infer<typeof ReviewRuleUpgradeRequestBody>;
export const ReviewRuleUpgradeRequestBody = z
.object({
filter: PrebuiltRulesFilter.optional(),
filter: ReviewPrebuiltRuleUpgradeFilter.optional(),
sort: ReviewRuleUpgradeSort.optional(),

page: z.coerce.number().int().min(1).optional().default(1),
Expand Down Expand Up @@ -89,4 +89,5 @@ export interface RuleUpgradeInfoForReview {
target_rule: RuleResponse;
diff: PartialRuleDiff;
revision: number;
has_base_version: boolean;
}
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
*/

import { ecsFieldMap } from '@kbn/alerts-as-data-utils';
import type { RequiredField, RequiredFieldInput } from '../../api/detection_engine';
import type { RequiredField, RequiredFieldInput, RuleResponse } from '../../api/detection_engine';

/*
Computes the boolean "ecs" property value for each required field based on the ECS field map.
Expand All @@ -23,3 +23,6 @@ export const addEcsToRequiredFields = (requiredFields?: RequiredFieldInput[]): R
ecs: isEcsField,
};
});

export const isRuleCustomized = (rule: RuleResponse) =>
rule.rule_source.type === 'external' && rule.rule_source.is_customized === true;
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import {
EuiCallOut,
EuiFlexGroup,
EuiFlexItem,
EuiLink,
EuiResizableContainer,
EuiSpacer,
EuiTab,
Expand Down Expand Up @@ -75,6 +76,7 @@ import { usePrebuiltRulesCustomizationStatus } from '../../../rule_management/lo
import { PrebuiltRulesCustomizationDisabledReason } from '../../../../../common/detection_engine/prebuilt_rules/prebuilt_rule_customization_status';
import { ALERT_SUPPRESSION_FIELDS_FIELD_NAME } from '../../../rule_creation/components/alert_suppression_edit';
import { usePrebuiltRuleCustomizationUpsellingMessage } from '../../../rule_management/logic/prebuilt_rules/use_prebuilt_rule_customization_upselling_message';
import { useRuleUpdateCallout } from '../../../rule_management/hooks/use_rule_update_callout';

const EditRulePageComponent: FC<{ rule: RuleResponse }> = ({ rule }) => {
const { addSuccess } = useAppToasts();
Expand Down Expand Up @@ -509,6 +511,16 @@ const EditRulePageComponent: FC<{ rule: RuleResponse }> = ({ rule }) => {
[navigateToApp, ruleId]
);

const upgradeCallout = useRuleUpdateCallout({
rule,
message: ruleI18n.HAS_RULE_UPDATE_EDITING_CALLOUT_MESSAGE,
actionButton: (
<EuiLink onClick={goToDetailsRule} data-test-subj="ruleEditingUpdateRuleCalloutButton">
{ruleI18n.HAS_RULE_UPDATE_EDITING_CALLOUT_BUTTON}
</EuiLink>
),
});

if (
redirectToDetections(
isSignalIndexExists,
Expand Down Expand Up @@ -550,6 +562,7 @@ const EditRulePageComponent: FC<{ rule: RuleResponse }> = ({ rule }) => {
setIsRulePreviewVisible={setIsRulePreviewVisible}
togglePanel={togglePanel}
/>
{upgradeCallout}
{invalidSteps.length > 0 && (
<EuiCallOut title={i18n.SORRY_ERRORS} color="danger" iconType="warning">
<FormattedMessage
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ import { useManualRuleRunConfirmation } from '../../../rule_gaps/components/manu
import { useLegacyUrlRedirect } from './use_redirect_legacy_url';
import { RuleDetailTabs, useRuleDetailsTabs } from './use_rule_details_tabs';
import { useIsExperimentalFeatureEnabled } from '../../../../common/hooks/use_experimental_features';
import { useRuleUpdateCallout } from '../../../rule_management/hooks/use_rule_update_callout';

const RULE_EXCEPTION_LIST_TYPES = [
ExceptionListTypeEnum.DETECTION,
Expand Down Expand Up @@ -254,7 +255,7 @@ const RuleDetailsPageComponent: React.FC<DetectionEngineComponentProps> = ({

const { pollForSignalIndex } = useSignalHelpers();
const [rule, setRule] = useState<RuleResponse | null>(null);
const isLoading = ruleLoading && rule == null;
const isLoading = useMemo(() => ruleLoading && rule == null, [rule, ruleLoading]);

const { starting: isStartingJobs, startMlJobs } = useStartMlJobs();
const startMlJobsIfNeeded = useCallback(async () => {
Expand Down Expand Up @@ -394,6 +395,12 @@ const RuleDetailsPageComponent: React.FC<DetectionEngineComponentProps> = ({
const lastExecutionDate = lastExecution?.date ?? '';
const lastExecutionMessage = lastExecution?.message ?? '';

const upgradeCallout = useRuleUpdateCallout({
rule,
message: ruleI18n.HAS_RULE_UPDATE_DETAILS_CALLOUT_MESSAGE,
onUpgrade: refreshRule,
});

const ruleStatusInfo = useMemo(() => {
return (
<>
Expand Down Expand Up @@ -556,6 +563,7 @@ const RuleDetailsPageComponent: React.FC<DetectionEngineComponentProps> = ({
<>
<NeedAdminForUpdateRulesCallOut />
<MissingPrivilegesCallOut />
{upgradeCallout}
{isBulkDuplicateConfirmationVisible && (
<BulkActionDuplicateExceptionsConfirmation
onCancel={cancelRuleDuplication}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
/*
* 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 { EuiCallOut, EuiSpacer, EuiLink } from '@elastic/eui';
import React, { useMemo } from 'react';
import type { RuleResponse } from '../../../../../common/api/detection_engine';
import * as i18n from './translations';
import { usePrebuiltRulesUpgrade } from '../../hooks/use_prebuilt_rules_upgrade';

interface RuleUpdateCalloutProps {
rule: RuleResponse;
message: string;
actionButton?: JSX.Element;
onUpgrade?: () => void;
}

const RuleUpdateCalloutComponent = ({
rule,
message,
actionButton,
onUpgrade,
}: RuleUpdateCalloutProps): JSX.Element | null => {
const { upgradeReviewResponse, rulePreviewFlyout, openRulePreview } = usePrebuiltRulesUpgrade({
pagination: {
page: 1, // we only want to fetch one result
perPage: 1,
},
filter: { rule_ids: [rule.id] },
onUpgrade,
});

const isRuleUpgradeable = useMemo(
() => upgradeReviewResponse !== undefined && upgradeReviewResponse.total > 0,
[upgradeReviewResponse]
);

const updateCallToActionButton = useMemo(() => {
if (actionButton) {
return actionButton;
}
return (
<EuiLink
onClick={() => openRulePreview(rule.rule_id)}
data-test-subj="ruleDetailsUpdateRuleCalloutButton"
>
{i18n.HAS_RULE_UPDATE_CALLOUT_BUTTON}
</EuiLink>
);
}, [actionButton, openRulePreview, rule.rule_id]);

if (!isRuleUpgradeable) {
return null;
}

return (
<>
<EuiCallOut title={i18n.HAS_RULE_UPDATE_CALLOUT_TITLE} color="primary" iconType="gear">
<p>{message}</p>
{updateCallToActionButton}
</EuiCallOut>
<EuiSpacer size="l" />
{rulePreviewFlyout}
</>
);
};

export const RuleUpdateCallout = React.memo(RuleUpdateCalloutComponent);
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
/*
* 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 { EuiCallOut } from '@elastic/eui';
import * as i18n from './translations';

export const RuleHasMissingBaseVersionCallout = () => (
<EuiCallOut color="warning" size="s">
<p>{i18n.RULE_BASE_VERSION_IS_MISSING_DESCRIPTION}</p>
</EuiCallOut>
);
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import { RuleUpgradeInfoBar } from './rule_upgrade_info_bar';
import { RuleUpgradeCallout } from './rule_upgrade_callout';
import { FieldUpgrade } from './field_upgrade';
import { FieldUpgradeContextProvider } from './field_upgrade_context';
import { RuleHasMissingBaseVersionCallout } from './missing_base_version_callout';

interface RuleUpgradeProps {
ruleUpgradeState: RuleUpgradeState;
Expand Down Expand Up @@ -45,6 +46,12 @@ export const RuleUpgrade = memo(function RuleUpgrade({
targetVersionNumber={ruleUpgradeState.target_rule.version}
/>
<EuiSpacer size="s" />
{!ruleUpgradeState.has_base_version && (
<>
<RuleHasMissingBaseVersionCallout />
<EuiSpacer size="s" />
</>
)}
<RuleUpgradeCallout
numOfSolvableConflicts={numOfSolvableConflicts}
numOfNonSolvableConflicts={numOfNonSolvableConflicts}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,66 +23,72 @@ export function RuleUpgradeCallout({
}: RuleUpgradeCalloutProps): JSX.Element {
if (numOfNonSolvableConflicts > 0) {
return (
<EuiCallOut
title={
<>
<strong>{i18n.UPGRADE_STATUS}</strong>
&nbsp;
<ActionRequiredBadge />
&nbsp;
{i18n.RULE_HAS_CONFLICTS(numOfNonSolvableConflicts + numOfSolvableConflicts)}
</>
}
color="danger"
size="s"
>
<span>{i18n.RULE_HAS_HARD_CONFLICTS_DESCRIPTION}</span>
<ul>
<li>{i18n.RULE_HAS_HARD_CONFLICTS_KEEP_YOUR_CHANGES}</li>
<li>{i18n.RULE_HAS_HARD_CONFLICTS_ACCEPT_ELASTIC_UPDATE}</li>
<li>{i18n.RULE_HAS_HARD_CONFLICTS_EDIT_FINAL_VERSION}</li>
</ul>
</EuiCallOut>
<>
<EuiCallOut
title={
<>
<strong>{i18n.UPGRADE_STATUS}</strong>
&nbsp;
<ActionRequiredBadge />
&nbsp;
{i18n.RULE_HAS_CONFLICTS(numOfNonSolvableConflicts + numOfSolvableConflicts)}
</>
}
color="danger"
size="s"
>
<span>{i18n.RULE_HAS_HARD_CONFLICTS_DESCRIPTION}</span>
<ul>
<li>{i18n.RULE_HAS_HARD_CONFLICTS_KEEP_YOUR_CHANGES}</li>
<li>{i18n.RULE_HAS_HARD_CONFLICTS_ACCEPT_ELASTIC_UPDATE}</li>
<li>{i18n.RULE_HAS_HARD_CONFLICTS_EDIT_FINAL_VERSION}</li>
</ul>
</EuiCallOut>
</>
);
}

if (numOfSolvableConflicts > 0) {
return (
<>
<EuiCallOut
title={
<>
<strong>{i18n.UPGRADE_STATUS}</strong>
&nbsp;
<ReviewRequiredBadge />
&nbsp;
{i18n.RULE_HAS_CONFLICTS(numOfSolvableConflicts)}
</>
}
color="warning"
size="s"
>
<span>{i18n.RULE_HAS_SOFT_CONFLICTS_DESCRIPTION}</span>
<ul>
<li>{i18n.RULE_HAS_SOFT_CONFLICTS_ACCEPT_SUGGESTED_UPDATE}</li>
<li>{i18n.RULE_HAS_SOFT_CONFLICTS_EDIT_FINAL_VERSION}</li>
</ul>
</EuiCallOut>
</>
);
}

return (
<>
<EuiCallOut
title={
<>
<strong>{i18n.UPGRADE_STATUS}</strong>
&nbsp;
<ReviewRequiredBadge />
&nbsp;
{i18n.RULE_HAS_CONFLICTS(numOfSolvableConflicts)}
<ReadyForUpgradeBadge />
</>
}
color="warning"
color="success"
size="s"
>
<span>{i18n.RULE_HAS_SOFT_CONFLICTS_DESCRIPTION}</span>
<ul>
<li>{i18n.RULE_HAS_SOFT_CONFLICTS_ACCEPT_SUGGESTED_UPDATE}</li>
<li>{i18n.RULE_HAS_SOFT_CONFLICTS_EDIT_FINAL_VERSION}</li>
</ul>
<p>{i18n.RULE_IS_READY_FOR_UPGRADE_DESCRIPTION}</p>
</EuiCallOut>
);
}

return (
<EuiCallOut
title={
<>
<strong>{i18n.UPGRADE_STATUS}</strong>
&nbsp;
<ReadyForUpgradeBadge />
</>
}
color="success"
size="s"
>
<p>{i18n.RULE_IS_READY_FOR_UPGRADE_DESCRIPTION}</p>
</EuiCallOut>
</>
);
}
Original file line number Diff line number Diff line change
Expand Up @@ -158,3 +158,11 @@ export const FIELD_MODIFIED_BADGE_DESCRIPTION = i18n.translate(
'This field value differs from the one provided in the original version of the rule.',
}
);

export const RULE_BASE_VERSION_IS_MISSING_DESCRIPTION = i18n.translate(
'xpack.securitySolution.detectionEngine.upgradeFlyout.baseVersionMissingDescription',
{
defaultMessage:
"The original, unedited version of this Elastic rule couldn't be found. This sometimes happens when a rule hasn't been updated in a while. You can still update this rule, but will only have access to its current version and the incoming Elastic update. Updating Elastic rules more often can help you avoid this in the future. We encourage you to review this update carefully and ensure your changes are not accidentally overwritten.",
}
);
Original file line number Diff line number Diff line change
Expand Up @@ -461,3 +461,17 @@ export const LUCENE_LANGUAGE_LABEL = i18n.translate(
defaultMessage: 'Lucene',
}
);

export const HAS_RULE_UPDATE_CALLOUT_TITLE = i18n.translate(
'xpack.securitySolution.detectionEngine.ruleDetails.updateCalloutTitle',
{
defaultMessage: 'Elastic rule update available',
}
);

export const HAS_RULE_UPDATE_CALLOUT_BUTTON = i18n.translate(
'xpack.securitySolution.detectionEngine.ruleDetailsUpdate.calloutButton',
{
defaultMessage: 'Review update',
}
);
Loading

0 comments on commit 6eddfbb

Please sign in to comment.