kibana/x-pack/plugins/cases

Case

This plugin provides cases management in Kibana

Docs

Report Bug · Request Feature

Table of Contents

• Cases API
• Cases UI

Cases API

Explore the API docs »

Cases UI

Embed Cases UI components in any Kibana plugin

• Add CasesUiStart to Kibana plugin StartServices dependencies:

cases: CasesUiStart;

CasesContext setup

To use any of the Cases UI hooks you must first initialize CasesContext in your plugin.

Without a CasesContext the hooks won't work and won't be able to render.

CasesContext works a bridge between your plugin and the Cases UI. It effectively renders the Cases UI.

To initialize the CasesContext you can use this code:

// somewhere high on your plugin render tree
<CasesContext
  owner={[PLUGIN_CASES_OWNER_ID]}
  permissions={CASES_PERMISSIONS}
  features={CASES_FEATURES}
>
  <RouteRender /> {/* or something similar */}
</CasesContext/>

props:

prop	type	description
PLUGIN_CASES_OWNER_ID	string	The owner string for your plugin. e.g: securitySolution
CASES_PERMISSIONS	CasesPermissions	CasesPermissions object defining the user's permissions
CASES_FEATURES	CasesFeatures	CasesFeatures object defining the features to enable/disable

Cases UI client

The cases UI client exports the following contract:

Property	Description	Type
api	Methods related to the Cases API	object
ui	Cases UI components	object
hooks	Cases React hooks	object
helpers	Cases helpers	object

You can get the cases UI client from the useKibana hook start services. Example:

const { cases } = useKibana().services;
// call in the return as you would any component
cases.getCases({
  basePath: '/investigate/cases',
  permissions: {
    all: true,
    read: true,
  },
  owner: ['securitySolution'],
  features: { alerts: { sync: false }, metrics: ['alerts.count', 'lifespan'] }
  timelineIntegration: {
    plugins: {
      parsingPlugin,
      processingPluginRenderer,
      uiPlugin,
    },
    hooks: {
      useInsertTimeline,
    },
  },
});

api

getRelatedCases

Returns all cases where the alert is attached to.

Arguments

Property	Description	Type
alertId	The alert ID	string
query	The alert ID	object

query

Property	Description	Type
owner	The type of cases to retrieve given an alert ID. If no owner is provided, all cases that the user has access to will be returned.	string | string[] | undefined

Response

An array of:

Property	Description	Type
id	The ID of the case	string
title	The title of the case	string

find

Retrieves a paginated subset of cases.

Arguments

Property	Description	Type
query	The request parameters	object
signal	The abort signal	Optional, AbortSignal

query

Property	Description	Type
defaultSearchOperator	The default operator to use for the simple_query_string. Defaults to OR.	Optional, string
fields	The fields in the entity to return in the response.	Optional, array of strings
from	Returns only cases that were created after a specific date. The date must be specified as a KQL data range or date match expression.	Optional, string
owner	A filter to limit the retrieved cases to a specific set of applications. Valid values are: cases, observability, and securitySolution. If this parameter is omitted, the response contains all cases that the user has access to read.
page	The page number to return. Defaults to 1 .	Optional, integer
perPage	The number of rules to return per page. Defaults to 20 .	Optional, integer
reporters	Filters the returned cases by the reporter's `username.	Optional, string or array of strings
search	simple_query_string query that filters the objects in the response.	Optional, string
searchFields	The fields to perform the simple_query_string parsed query against.	Optional, string or array of strings
severity	The severity of the case. Valid values are: critical, high, low, and medium.	Optional, string
sortField	Determines which field is used to sort the results,createdAt or updatedAt. Defaults to createdAt.	Optional, string
sortOrder	Determines the sort order, which can be desc or asc. Defaults to desc.	Optional, string
status	Filters the returned cases by state, which can be open, in-progress, or closed.	Optional, string
tags	Filters the returned cases by tags.	Optional, string or array of strings
to	Returns only cases that were created before a specific date. The date must be specified as a KQL data range or date match expression.	Optional, string

getCasesStatus

Returns the number of cases that are open, closed, and in progress.

Arguments

Property	Description	Type
query	The request parameters	object
signal	The abort signal	Optional, AbortSignal

query

Property	Description	Type
from	Returns only cases that were created after a specific date. The date must be specified as a KQL data range or date match expression.	Optional, string
owner	A filter to limit the retrieved cases to a specific set of applications. Valid values are: cases, observability, and securitySolution. If this parameter is omitted, the response contains all cases that the user has access to read.
to	Returns only cases that were created before a specific date. The date must be specified as a KQL data range or date match expression.	Optional, string

getCasesMetrics

Returns the number of cases that are open, closed, and in progress.

Arguments

Property	Description	Type
query	The request parameters	object
signal	The abort signal	Optional, AbortSignal

query

Property	Description	Type
features	The metrics to retrieve.	Optional, array of strings
from	Returns only cases that were created after a specific date. The date must be specified as a KQL data range or date match expression.	Optional, string
owner	A filter to limit the retrieved cases to a specific set of applications. Valid values are: cases, observability, and securitySolution. If this parameter is omitted, the response contains all cases that the user has access to read.
to	Returns only cases that were created before a specific date. The date must be specified as a KQL data range or date match expression.	Optional, string

ui

Arguments:

Property	Description
permissions	CasesPermissions object defining the user's permissions
owner	string[]; owner ids of the cases
basePath	string; path to mount the Cases router on top of
useFetchAlertData	(alertIds: string[]) => [boolean, Record<string, unknown>]; fetch alerts
disableAlerts?	boolean (default: false) flag to not show alerts information
actionsNavigation?	CasesNavigation<string, 'configurable'>
ruleDetailsNavigation?	CasesNavigation<string | null | undefined, 'configurable'>
onComponentInitialized?	() => void; callback when component has initialized
showAlertDetails?	(alertId: string, index: string) => void; callback to show alert details
features?	CasesFeatures object defining the features to enable/disable
features?.alerts.sync	boolean (default: true) defines wether the alert sync action should be enabled/disabled
features?.metrics	string[] (default: []) defines the metrics to show in the Case Detail View. Allowed metrics: "alerts.count", "alerts.users", "alerts.hosts", "connectors", "lifespan".
timelineIntegration?.editor_plugins	Plugins needed for integrating timeline into markdown editor.
timelineIntegration?.editor_plugins.parsingPlugin	Plugin;
timelineIntegration?.editor_plugins.processingPluginRenderer	React.FC<TimelineProcessingPluginRendererProps & { position: EuiMarkdownAstNodePosition }>
timelineIntegration?.editor_plugins.uiPlugin?	EuiMarkdownEditorUiPlugin
timelineIntegration?.hooks.useInsertTimeline	(value: string, onChange: (newValue: string) => void): UseInsertTimelineReturn
timelineIntegration?.ui?.renderInvestigateInTimelineActionComponent?	(alertIds: string[]) => JSX.Element; space to render InvestigateInTimelineActionComponent

getCases

UI component:

getAllCasesSelectorModal

Arguments:

Property	Description
permissions	CasesPermissions object defining the user's permissions
owner	string[]; owner ids of the cases
alertData?	Omit<CommentRequestAlertType, 'type'>; alert data to post to case
hiddenStatuses?	CaseStatuses[]; array of hidden statuses
onRowClick	(theCase?: Case) => void; callback for row click, passing case in row
updateCase?	(theCase: Case) => void; callback after case has been updated
onClose?	() => void called when the modal is closed without selecting a case

UI component:

getCreateCaseFlyout

Arguments:

Property	Description
permissions	CasesPermissions object defining the user's permissions
owner	string[]; owner ids of the cases
onClose	() => void; callback when create case is canceled
onSuccess	(theCase: Case) => Promise<void>; callback passing newly created case after pushCaseToExternalService is called
afterCaseCreated?	(theCase: Case) => Promise<void>; callback passing newly created case before pushCaseToExternalService is called
disableAlerts?	boolean (default: false) flag to not show alerts information

UI component:

getRecentCases

Arguments:

Property	Description
permissions	CasesPermissions object defining the user's permissions
owner	string[]; owner ids of the cases
maxCasesToShow	number; number of cases to show in widget

UI component:

hooks

getUseCasesAddToNewCaseFlyout

Returns an object containing two methods: open and close to either open or close the add to new case flyout. You can use this hook to prompt the user to create a new case with some attachments directly attached to it. e.g.: alerts or text comments.

Arguments:

Property	Description
permissions	CasesPermissions object defining the user's permissions
onClose	() => void; callback when create case is canceled
onSuccess	(theCase: Case) => Promise<void>; callback passing newly created case after pushCaseToExternalService is called
afterCaseCreated?	(theCase: Case) => Promise<void>; callback passing newly created case before pushCaseToExternalService is called
attachments?	CaseAttachments; array of SupportedCaseAttachment (see types) that will be attached to the newly created case

returns: an object with open and close methods to open or close the flyout.

open() and close() don't take any arguments. They will open or close the flyout at will.

getUseCasesAddToExistingCaseModal

Returns an object containing two methods: open and close to either open or close the case selector modal.

You can use this hook to prompt the user to select a case and get the selected case. You can also pass attachments directly and have them attached to the selected case after selection. e.g.: alerts or text comments.

Arguments:

Property	Description
onRowClick	(theCase?: Case) => void; callback for row click, passing case in row
updateCase?	(theCase: Case) => void; callback after case has been updated
onClose?	() => void called when the modal is closed without selecting a case
attachments?	CaseAttachments; array of SupportedCaseAttachment (see types) that will be attached to the newly created case

helpers

canUseCases

Returns the Cases capabilities for the current user. Specifically:

Property	Description	Type
crud	Denotes if the user has all access to Cases	boolean
read?	Denotes if the user has read access to Cases	boolean

getRuleIdFromEvent

Returns an object with a rule id and name of the event passed. This helper method is necessary to bridge the gap between previous events schema and new ones.

Arguments:

property	Description	Type
event	Event containing an ecs attribute with ecs data and a data attribute with nonEcs data.	object