add entity query templates with examples (#15306)

* add entity query templates with examples

* fix spelling

* adding EntityQueryTemplates to readme file

* fix lint

Author: ori-licht

specification/securityinsights/resource-manager/Microsoft.SecurityInsights/preview/2021-03-01-preview/EntityQueryTemplates.json

@@ -0,0 +1,310 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "Security Insights",
+    "description": "API spec for Microsoft.SecurityInsights (Azure Security Insights) resource provider",
+    "version": "2021-03-01-preview"
+  },
+  "host": "management.azure.com",
+  "schemes": [
+    "https"
+  ],
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "security": [
+    {
+      "azure_auth": [
+        "user_impersonation"
+      ]
+    }
+  ],
+  "securityDefinitions": {
+    "azure_auth": {
+      "type": "oauth2",
+      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
+      "flow": "implicit",
+      "description": "Azure Active Directory OAuth2 Flow",
+      "scopes": {
+        "user_impersonation": "impersonate your user account"
+      }
+    }
+  },
+  "paths": {
+    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{operationalInsightsResourceProvider}/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/entityQueryTemplates": {
+      "get": {
+        "x-ms-examples": {
+          "Get all entity query templates.": {
+            "$ref": "./examples/entityQueryTemplates/GetEntityQueryTemplates.json"
+          }
+        },
+        "tags": [
+          "EntityQueries"
+        ],
+        "description": "Gets all entity query templates.",
+        "operationId": "EntityQueryTemplates_List",
+        "parameters": [
+          {
+            "$ref": "#/parameters/EntityQueryTemplateKind"
+          },
+          {
+            "$ref": "../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter"
+          },
+          {
+            "$ref": "../../../../../common-types/resource-management/v2/types.json#/parameters/SubscriptionIdParameter"
+          },
+          {
+            "$ref": "../../../../../common-types/resource-management/v2/types.json#/parameters/ResourceGroupNameParameter"
+          },
+          {
+            "$ref": "../../../common/1.0/types.json#/parameters/OperationalInsightsResourceProvider"
+          },
+          {
+            "$ref": "../../../common/1.0/types.json#/parameters/WorkspaceName"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/EntityQueryTemplateList"
+            }
+          },
+          "default": {
+            "description": "Error response describing why the operation failed.",
+            "schema": {
+              "$ref": "../../../common/1.0/types.json#/definitions/CloudError"
+            }
+          }
+        },
+        "x-ms-pageable": {
+          "nextLinkName": "nextLink"
+        }
+      }
+    },
+    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{operationalInsightsResourceProvider}/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/entityQueryTemplates/{entityQueryTemplateId}": {
+      "get": {
+        "x-ms-examples": {
+          "Get an Activity entity query template.": {
+            "$ref": "./examples/entityQueryTemplates/GetActivityEntityQueryTemplateById.json"
+          }
+        },
+        "tags": [
+          "EntityQueries"
+        ],
+        "description": "Gets an entity query.",
+        "operationId": "EntityQueryTemplates_Get",
+        "parameters": [
+          {
+            "$ref": "../../../../../common-types/resource-management/v2/types.json#/parameters/ApiVersionParameter"
+          },
+          {
+            "$ref": "../../../../../common-types/resource-management/v2/types.json#/parameters/SubscriptionIdParameter"
+          },
+          {
+            "$ref": "../../../../../common-types/resource-management/v2/types.json#/parameters/ResourceGroupNameParameter"
+          },
+          {
+            "$ref": "../../../common/1.0/types.json#/parameters/OperationalInsightsResourceProvider"
+          },
+          {
+            "$ref": "../../../common/1.0/types.json#/parameters/WorkspaceName"
+          },
+          {
+            "$ref": "#/parameters/EntityQueryTemplateId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "schema": {
+              "$ref": "#/definitions/EntityQueryTemplate"
+            }
+          },
+          "default": {
+            "description": "Error response describing why the operation failed.",
+            "schema": {
+              "$ref": "../../../common/1.0/types.json#/definitions/CloudError"
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "EntityQueryTemplateKind": {
+      "description": "The kind of the entity query template.",
+      "enum": [
+        "Activity"
+      ],
+      "type": "string",
+      "x-ms-enum": {
+        "modelAsString": true,
+        "name": "EntityQueryTemplateKind",
+        "values": [
+          {
+            "value": "Activity"
+          }
+        ]
+      }
+    },
+    "EntityQueryTemplateList": {
+      "description": "List of all the entity query templates.",
+      "properties": {
+        "nextLink": {
+          "description": "URL to fetch the next set of entity query templates.",
+          "readOnly": true,
+          "type": "string"
+        },
+        "value": {
+          "description": "Array of entity query templates.",
+          "items": {
+            "$ref": "#/definitions/EntityQueryTemplate"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "value"
+      ],
+      "type": "object"
+    },
+    "EntityQueryTemplate": {
+      "allOf": [
+        {
+          "$ref": "../../../common/1.0/types.json#/definitions/Resource"
+        }
+      ],
+      "description": "Specific entity query template.",
+      "discriminator": "kind",
+      "properties": {
+        "kind": {
+          "$ref": "#/definitions/EntityQueryTemplateKind",
+          "description": "the entity query template kind"
+        }
+      },
+      "type": "object",
+      "required": [
+        "kind"
+      ]
+    },
+    "ActivityEntityQueryTemplate": {
+      "description": "Represents Activity entity query.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/EntityQueryTemplate"
+        }
+      ],
+      "properties": {
+        "properties": {
+          "$ref": "#/definitions/ActivityEntityQueryTemplateProperties",
+          "description": "Activity entity query properties",
+          "x-ms-client-flatten": true
+        }
+      },
+      "type": "object",
+      "x-ms-discriminator-value": "Activity"
+    },
+    "ActivityEntityQueryTemplateProperties": {
+      "description": "Describes activity entity query properties",
+      "properties": {
+        "title": {
+          "description": "The entity query title",
+          "type": "string"
+        },
+        "content": {
+          "description": "The entity query content to display in timeline",
+          "type": "string"
+        },
+        "description": {
+          "description": "The entity query description",
+          "type": "string"
+        },
+        "queryDefinitions": {
+          "description": "The Activity query definitions",
+          "properties": {
+            "query": {
+              "description": "The Activity query to run on a given entity",
+              "type": "string"
+            },
+            "summarizeBy": {
+              "description": "The dimensions we want to summarize the timeline results on, this is comma separated list",
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        "dataTypes": {
+          "description": "List of required data types for the given entity query template",
+          "items": {
+            "$ref": "#/definitions/DataTypeDefinitions"
+          },
+          "type": "array"
+        },
+        "inputEntityType": {
+          "$ref": "EntityDefinitions.json#/definitions/EntityInnerType",
+          "description": "The type of the query's source entity"
+        },
+        "requiredInputFieldsSets": {
+          "description": "List of the fields of the source entity that are required to run the query",
+          "items": {
+            "description": "Sub sets of the field of the source entity that are required to run the query",
+            "items": {
+              "description": "Required input field name",
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "type": "array"
+        },
+        "entitiesFilter": {
+          "description": "The query applied only to entities matching to all filters",
+          "type": "object",
+          "additionalProperties": {
+            "description": "Filter field name",
+            "items": {
+              "description": "Filter field values",
+              "type": "string"
+            },
+            "type": "array"
+          }
+        }
+      },
+      "type": "object"
+    },
+    "DataTypeDefinitions": {
+      "description": "The data type definition",
+      "properties": {
+        "dataType": {
+          "description": "The data type name",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "parameters": {
+    "EntityQueryTemplateId": {
+      "description": "entity query template ID",
+      "in": "path",
+      "name": "entityQueryTemplateId",
+      "required": true,
+      "type": "string",
+      "x-ms-parameter-location": "method"
+    },
+    "EntityQueryTemplateKind": {
+      "description": "The entity template query kind we want to fetch",
+      "in": "query",
+      "name": "kind",
+      "required": false,
+      "enum": [
+        "Activity"
+      ],
+      "type": "string",
+      "x-ms-parameter-location": "method"
+    }
+  }
+}

specification/securityinsights/resource-manager/Microsoft.SecurityInsights/preview/2021-03-01-preview/examples/entityQueryTemplates/GetActivityEntityQueryTemplateById.json

@@ -0,0 +1,58 @@
+{
+  "parameters": {
+    "api-version": "2021-03-01-preview",
+    "subscriptionId": "d0cfe6b2-9ac0-4464-9919-dccaee2e48c0",
+    "resourceGroupName": "myRg",
+    "workspaceName": "myWorkspace",
+    "operationalInsightsResourceProvider": "Microsoft.OperationalIinsights",
+    "entityQueryTemplateId": "07da3cc8-c8ad-4710-a44e-334cdcb7882b"
+  },
+  "responses": {
+    "200": {
+      "body": {
+        "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/entityQueryTemplates/07da3cc8-c8ad-4710-a44e-334cdcb7882b",
+        "name": "07da3cc8-c8ad-4710-a44e-334cdcb7882b",
+        "type": "Microsoft.SecurityInsights/entityQueryTemplate",
+        "kind": "Activity",
+        "properties": {
+          "title": "An account was deleted on this host",
+          "content": "On '{{Computer}}' the account '{{TargetAccount}}' was deleted by '{{AddedBy}}'",
+          "description": "Account deleted on host",
+          "queryDefinitions": {
+            "query": "let GetAccountActions = (v_Host_Name:string, v_Host_NTDomain:string, v_Host_DnsDomain:string, v_Host_AzureID:string, v_Host_OMSAgentID:string){\nSecurityEvent\n| where EventID in (4725, 4726, 4767, 4720, 4722, 4723, 4724)\n// parsing for Host to handle variety of conventions coming from data\n| extend Host_HostName = case(\nComputer has '@', tostring(split(Computer, '@')[0]),\nComputer has '\\\\', tostring(split(Computer, '\\\\')[1]),\nComputer has '.', tostring(split(Computer, '.')[0]),\nComputer\n)\n| extend Host_NTDomain = case(\nComputer has '\\\\', tostring(split(Computer, '\\\\')[0]), \nComputer has '.', tostring(split(Computer, '.')[-2]), \nComputer\n)\n| extend Host_DnsDomain = case(\nComputer has '\\\\', tostring(split(Computer, '\\\\')[0]), \nComputer has '.', strcat_array(array_slice(split(Computer,'.'),-2,-1),'.'), \nComputer\n)\n| where (Host_HostName =~ v_Host_Name and Host_NTDomain =~ v_Host_NTDomain) \nor (Host_HostName =~ v_Host_Name and Host_DnsDomain =~ v_Host_DnsDomain) \nor v_Host_AzureID =~ _ResourceId \nor v_Host_OMSAgentID == SourceComputerId\n| project TimeGenerated, EventID, Activity, Computer, TargetAccount, TargetUserName, TargetDomainName, TargetSid, SubjectUserName, SubjectUserSid, _ResourceId, SourceComputerId\n| extend AddedBy = SubjectUserName\n// Future support for Activities\n| extend timestamp = TimeGenerated, HostCustomEntity = Computer, AccountCustomEntity = TargetAccount\n};\nGetAccountActions('{{Host_HostName}}', '{{Host_NTDomain}}', '{{Host_DnsDomain}}', '{{Host_AzureID}}', '{{Host_OMSAgentID}}')\n \n| where EventID == 4726 "
+          },
+          "inputEntityType": "Host",
+          "requiredInputFieldsSets": [
+            [
+              "Host_HostName",
+              "Host_NTDomain"
+            ],
+            [
+              "Host_HostName",
+              "Host_DnsDomain"
+            ],
+            [
+              "Host_AzureID"
+            ],
+            [
+              "Host_OMSAgentID"
+            ]
+          ],
+          "entitiesFilter": {
+            "Host_OsFamily": [
+              "Windows"
+            ]
+          },
+          "dataTypes": [
+            {
+              "dataType": "AuditLogs"
+            },
+            {
+              "dataType": "SecurityEvent"
+            }
+          ]
+        }
+      }
+    }
+  }
+}