[Cases] RBAC

x-pack/plugins/cases/README.md

@@ -14,13 +14,17 @@ Case management in Kibana
 ## Table of Contents
 
 - [Cases API](#cases-api)
+- [Cases Client API](#cases-client-api)
 - [Cases UI](#cases-ui)
 - [Case Action Type](#case-action-type) _feature in development, disabled by default_
 
 
 ## Cases API
 [**Explore the API docs »**](https://www.elastic.co/guide/en/security/current/cases-api-overview.html)
 
+## Cases Client API
+[**Cases Client API docs**][cases-client-api-docs]
+
 ## Cases UI
 
 #### Embed Cases UI components in any Kibana plugin
@@ -263,4 +267,4 @@ For IBM Resilient connectors:
 [all-cases-modal-img]: images/all_cases_selector_modal.png
 [recent-cases-img]: images/recent_cases.png
 [case-view-img]: images/case_view.png
-
+[cases-client-api-docs]: docs/cases_client/cases_client_api.md

x-pack/plugins/cases/common/api/cases/case.ts

@@ -31,13 +31,38 @@ const SettingsRt = rt.type({
 });
 
 const CaseBasicRt = rt.type({
+  /**
+   * The description of the case
+   */
   description: rt.string,
+  /**
+   * The current status of the case (open, closed, in-progress)
+   */
   status: CaseStatusRt,
+  /**
+   * The identifying strings for filter a case
+   */
   tags: rt.array(rt.string),
+  /**
+   * The title of a case
+   */
   title: rt.string,
+  /**
+   * The type of a case (individual or collection)
+   */
   [caseTypeField]: CaseTypeRt,
+  /**
+   * The external system that the case can be synced with
+   */
   connector: CaseConnectorRt,
+  /**
+   * The alert sync settings
+   */
   settings: SettingsRt,
+  /**
+   * The plugin owner of the case
+   */
+  owner: rt.string,
 });
 
 const CaseExternalServiceBasicRt = rt.type({
@@ -73,11 +98,31 @@ export const CaseAttributesRt = rt.intersection([
 ]);
 
 const CasePostRequestNoTypeRt = rt.type({
+  /**
+   * Description of the case
+   */
   description: rt.string,
+  /**
+   * Identifiers for the case.
+   */
   tags: rt.array(rt.string),
+  /**
+   * Title of the case
+   */
   title: rt.string,
+  /**
+   * The external configuration for the case
+   */
   connector: CaseConnectorRt,
+  /**
+   * Sync settings for alerts
+   */
   settings: SettingsRt,
+  /**
+   * The owner here must match the string used when a plugin registers a feature with access to the cases plugin. The user
+   * creating this case must also be granted access to that plugin's feature.
+   */
+  owner: rt.string,
 });
 
 /**
@@ -95,23 +140,78 @@ export const CasesClientPostRequestRt = rt.type({
  * has all the necessary fields. CasesClientPostRequestRt is used for validation.
  */
 export const CasePostRequestRt = rt.intersection([
-  rt.partial({ type: CaseTypeRt }),
+  /**
+   * The case type: an individual case (one without children) or a collection case (one with children)
+   */
+  rt.partial({ [caseTypeField]: CaseTypeRt }),
   CasePostRequestNoTypeRt,
 ]);
 
 export const CasesFindRequestRt = rt.partial({
+  /**
+   * Type of a case (individual, or collection)
+   */
   type: CaseTypeRt,
+  /**
+   * Tags to filter by
+   */
   tags: rt.union([rt.array(rt.string), rt.string]),
+  /**
+   * The status of the case (open, closed, in-progress)
+   */
   status: CaseStatusRt,
+  /**
+   * The reporters to filter by
+   */
   reporters: rt.union([rt.array(rt.string), rt.string]),
+  /**
+   * Operator to use for the `search` field
+   */
   defaultSearchOperator: rt.union([rt.literal('AND'), rt.literal('OR')]),
+  /**
+   * The fields in the entity to return in the response
+   */
   fields: rt.array(rt.string),
+  /**
+   * The page of objects to return
+   */
   page: NumberFromString,
+  /**
+   * The number of objects to include in each page
+   */
   perPage: NumberFromString,
+  /**
+   * An Elasticsearch simple_query_string
+   */
   search: rt.string,
-  searchFields: rt.array(rt.string),
+  /**
+   * The fields to perform the simple_query_string parsed query against
+   */
+  searchFields: rt.union([rt.array(rt.string), rt.string]),
+  /**
+   * The field to use for sorting the found objects.
+   *
+   * This only supports, `create_at`, `closed_at`, and `status`
+   */
   sortField: rt.string,
+  /**
+   * The order to sort by
+   */
   sortOrder: rt.union([rt.literal('desc'), rt.literal('asc')]),
+  /**
+   * The owner(s) to filter by. The user making the request must have privileges to retrieve cases of that
+   * ownership or they will be ignored. If no owner is included, then all ownership types will be included in the response
+   * that the user has access to.
+   */
+  owner: rt.union([rt.array(rt.string), rt.string]),
+});
+
+export const CasesByAlertIDRequestRt = rt.partial({
+  /**
+   * 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.
+   */
+  owner: rt.union([rt.array(rt.string), rt.string]),
 });
 
 export const CaseResponseRt = rt.intersection([
@@ -141,6 +241,9 @@ export const CasesFindResponseRt = rt.intersection([
 
 export const CasePatchRequestRt = rt.intersection([
   rt.partial(CaseBasicRt.props),
+  /**
+   * The saved object ID and version
+   */
   rt.type({ id: rt.string, version: rt.string }),
 ]);
 
@@ -172,6 +275,16 @@ export const ExternalServiceResponseRt = rt.intersection([
   }),
 ]);
 
+export const AllTagsFindRequestRt = rt.partial({
+  /**
+   * The owner of the cases to retrieve the tags from. If no owner is provided the tags from all cases
+   * that the user has access to will be returned.
+   */
+  owner: rt.union([rt.array(rt.string), rt.string]),
+});
+
+export const AllReportersFindRequestRt = AllTagsFindRequestRt;
+
 export type CaseAttributes = rt.TypeOf<typeof CaseAttributesRt>;
 /**
  * This field differs from the CasePostRequest in that the post request's type field can be optional. This type requires
@@ -183,6 +296,7 @@ export type CasePostRequest = rt.TypeOf<typeof CasePostRequestRt>;
 export type CaseResponse = rt.TypeOf<typeof CaseResponseRt>;
 export type CasesResponse = rt.TypeOf<typeof CasesResponseRt>;
 export type CasesFindRequest = rt.TypeOf<typeof CasesFindRequestRt>;
+export type CasesByAlertIDRequest = rt.TypeOf<typeof CasesByAlertIDRequestRt>;
 export type CasesFindResponse = rt.TypeOf<typeof CasesFindResponseRt>;
 export type CasePatchRequest = rt.TypeOf<typeof CasePatchRequestRt>;
 export type CasesPatchRequest = rt.TypeOf<typeof CasesPatchRequestRt>;
@@ -194,3 +308,6 @@ export type ESCaseAttributes = Omit<CaseAttributes, 'connector'> & { connector:
 export type ESCasePatchRequest = Omit<CasePatchRequest, 'connector'> & {
   connector?: ESCaseConnector;
 };
+
+export type AllTagsFindRequest = rt.TypeOf<typeof AllTagsFindRequestRt>;
+export type AllReportersFindRequest = AllTagsFindRequest;

x-pack/plugins/cases/common/api/cases/comment.ts

@@ -6,6 +6,7 @@
  */
 
 import * as rt from 'io-ts';
+import { SavedObjectFindOptionsRt } from '../saved_object';
 
 import { UserRT } from '../user';
 
@@ -42,6 +43,7 @@ export const CommentAttributesBasicRt = rt.type({
   ]),
   created_at: rt.string,
   created_by: UserRT,
+  owner: rt.string,
   pushed_at: rt.union([rt.string, rt.null]),
   pushed_by: rt.union([UserRT, rt.null]),
   updated_at: rt.union([rt.string, rt.null]),
@@ -57,6 +59,7 @@ export enum CommentType {
 export const ContextTypeUserRt = rt.type({
   comment: rt.string,
   type: rt.literal(CommentType.user),
+  owner: rt.string,
 });
 
 /**
@@ -72,6 +75,7 @@ export const AlertCommentRequestRt = rt.type({
     id: rt.union([rt.string, rt.null]),
     name: rt.union([rt.string, rt.null]),
   }),
+  owner: rt.string,
 });
 
 const AttributesTypeUserRt = rt.intersection([ContextTypeUserRt, CommentAttributesBasicRt]);
@@ -127,7 +131,17 @@ export const CommentsResponseRt = rt.type({
 
 export const AllCommentsResponseRt = rt.array(CommentResponseRt);
 
+export const FindQueryParamsRt = rt.partial({
+  ...SavedObjectFindOptionsRt.props,
+  /**
+   * If specified the attachments found will be associated to a sub case instead of a case object
+   */
+  subCaseId: rt.string,
+});
+
+export type FindQueryParams = rt.TypeOf<typeof FindQueryParamsRt>;
 export type AttributesTypeAlerts = rt.TypeOf<typeof AttributesTypeAlertsRt>;
+export type AttributesTypeUser = rt.TypeOf<typeof AttributesTypeUserRt>;
 export type CommentAttributes = rt.TypeOf<typeof CommentAttributesRt>;
 export type CommentRequest = rt.TypeOf<typeof CommentRequestRt>;
 export type CommentResponse = rt.TypeOf<typeof CommentResponseRt>;

x-pack/plugins/cases/common/api/cases/configure.ts

@@ -9,18 +9,34 @@ import * as rt from 'io-ts';
 
 import { UserRT } from '../user';
 import { CaseConnectorRt, ConnectorMappingsRt, ESCaseConnector } from '../connectors';
+import { OmitProp } from '../runtime_types';
+import { OWNER_FIELD } from './constants';
 
 // TODO: we will need to add this type rt.literal('close-by-third-party')
 const ClosureTypeRT = rt.union([rt.literal('close-by-user'), rt.literal('close-by-pushing')]);
 
 const CasesConfigureBasicRt = rt.type({
+  /**
+   * The external connector
+   */
   connector: CaseConnectorRt,
+  /**
+   * Whether to close the case after it has been synced with the external system
+   */
   closure_type: ClosureTypeRT,
+  /**
+   * The plugin owner that manages this configuration
+   */
+  owner: rt.string,
 });
 
+const CasesConfigureBasicWithoutOwnerRt = rt.type(
+  OmitProp(CasesConfigureBasicRt.props, OWNER_FIELD)
+);
+
 export const CasesConfigureRequestRt = CasesConfigureBasicRt;
 export const CasesConfigurePatchRt = rt.intersection([
-  rt.partial(CasesConfigureBasicRt.props),
+  rt.partial(CasesConfigureBasicWithoutOwnerRt.props),
   rt.type({ version: rt.string }),
 ]);
 
@@ -38,18 +54,37 @@ export const CaseConfigureResponseRt = rt.intersection([
   CaseConfigureAttributesRt,
   ConnectorMappingsRt,
   rt.type({
+    id: rt.string,
     version: rt.string,
     error: rt.union([rt.string, rt.null]),
+    owner: rt.string,
   }),
 ]);
 
+export const GetConfigureFindRequestRt = rt.partial({
+  /**
+   * The configuration plugin owner to filter the search by. If this is left empty the results will include all configurations
+   * that the user has permissions to access
+   */
+  owner: rt.union([rt.array(rt.string), rt.string]),
+});
+
+export const CaseConfigureRequestParamsRt = rt.type({
+  configuration_id: rt.string,
+});
+
+export const CaseConfigurationsResponseRt = rt.array(CaseConfigureResponseRt);
+
 export type ClosureType = rt.TypeOf<typeof ClosureTypeRT>;
 export type CasesConfigure = rt.TypeOf<typeof CasesConfigureBasicRt>;
 export type CasesConfigureRequest = rt.TypeOf<typeof CasesConfigureRequestRt>;
 export type CasesConfigurePatch = rt.TypeOf<typeof CasesConfigurePatchRt>;
 export type CasesConfigureAttributes = rt.TypeOf<typeof CaseConfigureAttributesRt>;
 export type CasesConfigureResponse = rt.TypeOf<typeof CaseConfigureResponseRt>;
+export type CasesConfigurationsResponse = rt.TypeOf<typeof CaseConfigurationsResponseRt>;
 
 export type ESCasesConfigureAttributes = Omit<CasesConfigureAttributes, 'connector'> & {
   connector: ESCaseConnector;
 };
+
+export type GetConfigureFindRequest = rt.TypeOf<typeof GetConfigureFindRequestRt>;

x-pack/plugins/cases/common/api/cases/constants.ts

@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+
+/**
+ * This field is used for authorization of the entities within the cases plugin. Each entity within Cases will have the owner field
+ * set to a string that represents the plugin that "owns" (i.e. the plugin that originally issued the POST request to
+ * create the entity) the entity.
+ *
+ * The Authorization class constructs a string composed of the operation being performed (createCase, getComment, etc),
+ * and the owner of the entity being acted upon or created. This string is then given to the Security plugin which
+ * checks to see if the user making the request has that particular string stored within it's privileges. If it does,
+ * then the operation succeeds, otherwise the operation fails.
+ *
+ * APIs that create/update an entity require that the owner field be passed in the body of the request.
+ * APIs that search for entities typically require that the owner be passed as a query parameter.
+ * APIs that specify an ID of an entity directly generally don't need to specify the owner field.
+ *
+ * For APIs that create/update an entity, the RBAC implementation checks to see if the user making the request has the
+ * correct privileges for performing that action (a create/update) for the specified owner.
+ * This check is done through the Security plugin's API.
+ *
+ * For APIs that search for entities, the RBAC implementation creates a filter for the saved objects query that limits
+ * the search to only owners that the user has access to. We also check that the objects returned by the saved objects
+ * API have the limited owner scope. If we find one that the user does not have permissions for, we throw a 403 error.
+ * The owner field that is passed in as a query parameter can be used to further limit the results. If a user attempts
+ * to pass an owner that they do not have access to, the owner is ignored.
+ *
+ * For APIs that retrieve/delete entities directly using their ID, the RBAC implementation requests the object first,
+ * and then checks to see if the user making the request has access to that operation and owner. If the user does, the
+ * operation continues, otherwise we throw a 403.
+ */
+export const OWNER_FIELD = 'owner';

x-pack/plugins/cases/common/api/cases/index.ts

@@ -11,3 +11,4 @@ export * from './comment';
 export * from './status';
 export * from './user_actions';
 export * from './sub_case';
+export * from './constants';

x-pack/plugins/cases/common/api/cases/status.ts

@@ -27,4 +27,13 @@ export const CasesStatusResponseRt = rt.type({
   count_closed_cases: rt.number,
 });
 
+export const CasesStatusRequestRt = rt.partial({
+  /**
+   * The owner of the cases to retrieve the status stats from. If no owner is provided the stats for all cases
+   * that the user has access to will be returned.
+   */
+  owner: rt.union([rt.array(rt.string), rt.string]),
+});
+
 export type CasesStatusResponse = rt.TypeOf<typeof CasesStatusResponseRt>;
+export type CasesStatusRequest = rt.TypeOf<typeof CasesStatusRequestRt>;