Azure Data Explorer
The Azure Data Explorer connector enables seamless integration with Swimlane, providing the ability to execute KQL queries and retrieve query-related information directly within automated workflows.
Azure Data Explorer is a fast and highly scalable data exploration service for log and telemetry data. The Azure Data Explorer Connector for Swimlane Turbine allows users to execute KQL queries and retrieve detailed query information, enabling powerful data analysis within security workflows. By integrating with Azure Data Explorer, Swimlane Turbine users can enhance their security automation playbooks with advanced data analytics capabilities, streamline incident investigation, and gain deeper insights from their telemetry data.
Limitations
None to date.
Supported Versions
This Azure Data Explorer Connector uses the latest version API.
Additional Docs
Configuration
Prerequisites
To utilize the Azure Data Explorer connector with Swimlane, ensure you have the following prerequisites:
- OAuth 2.0 client credentials authentication with the following parameters:
- Cluster Name: The name of your Azure Data Explorer cluster.
- Client ID: The application (client) ID registered in Azure Active Directory.
- Client Secret: The secret key generated for the registered application.
- Scopes: The scopes of access requested for the token, typically in the format 'https://.kusto.windows.net/.default'.ο»Ώ
- Region: The geographical region where your Azure Data Explorer cluster is hosted.
Authentication Methods
OAuth 2.0 Client Credentials Authentication:
- Cluster Name: Name of the Azure Data Explorer cluster to connect to.
- Client ID: Application (client) ID registered in Azure AD to authenticate.
- Client Secret: Secret generated for the registered application in Azure AD.
- Scopes: Specific permissions that the application should request.
- Region: Geographic region where your Azure Data Explorer cluster is hosted.
- Tenant ID: Directory (tenant) ID in Azure AD associated with the service.
- Token URL: URL to retrieve the OAuth 2.0 token.
In order to set up the asset, you need the following:
- Azure Application Client ID
- Azure Application Client Secret
- Azure Tenant ID
- Azure Data Explorer Cluster
Steps to create the Azure app:
- Go to the App Registration page in the Azure portal.
- Click New Registration.
- Enter a name for your new application and choose Accounts in this organizational directory only, then click Register at the bottom.
- Navigate to the API permissions tab on the left navigation menu.
- Select Add a permission.
- Select Microsoft Graph.
- Select Application permissions, then mark all the permissions you need for the actions you are using (See suggested permissions at the top of the asset setup section).
- Click the Add permissions button at the bottom of the page.
- Select Grant admin consent for your organization, then your permissions should look as below.
- Navigate to the Certificates & secrets tab and select New client secret.
- Fill out the description and expiration, then click the Add button at the bottom.
- The Value of the secret you just created is the Client Secret needed for the Swimlane asset.
- Navigate to the Overview tab on the left menu.
- The Client ID and Tenant ID needed in the asset are shown on this page.
The Client ID, Tenant ID, and Client Secret described in the steps above are the credentials you need for the asset.
Password Flow (Delegated Auth)
- Use Delegated Permissions, instead of Application Permissions, and generate Client ID, Tenant ID, and Client Secret as described in the above Client Credential Flow Authentication.
- We also need an Username and a Password for this authentication.
After generation of Client ID, Tenant ID, Client Secret go to Azure Data Explorer and create a Cluster.
- Open the cluster, In the left-hand menu, under Security + networking, select Permissions.
- Select Add, and select the role you want to assign.
- After click on the role, a left side nav bar open and click on Enterprise Applicaitons tab.
- Search for the APP which you want to give permissions and select the app.
Capabilities
This Azure Data Explorer Connector provides the following capabilities:
- Get Query Information
- Launch KQL Query
Get Query Information
- Retrieve details about a specific query in Azure Data Explorer using provided parameters and headers Link Here.
Get Query Information
- Executes a Kusto Query Language (KQL) query in Azure Data Explorer with specified JSON body and headers Link Here.
Configurations
Azure Data Explorer Oauth 2.0 Client Credentials
Authenticates using oauth 2.0 client credentials.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
clusterName | Azure Data Explorer Cluster Name. | string | Required |
region | Azure Data Explorer Region. | string | Required |
token_url | Token URL. Format should be in the form of https://login.microsoftonline.com/ο»Ώ/oauth2/token. | string | Optional |
client_id | The client ID. | string | Required |
client_secret | The client secret. | string | Required |
resource | Permission scopes for this action. | string | Required |
tenant_id | The tenant ID. | string | Optional |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Get Query Information
Retrieve details about a specific query in Azure Data Explorer using provided CSL parameters and headers.
Endpoint
- URL: /v2/rest/query
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.db | string | Optional | The name of the database that is the target of the query or management command. |
parameters.csl | string | Required | The text of the query or management command to execute. |
parameters.properties | string | Optional | Request properties that modify how the request is processed and its results. |
headers | object | Required | HTTP headers for the request |
headers.Host | string | Required | The qualified domain name that the request was sent to. For example, help.kusto.windows.net. |
headers.Expect | string | Optional | The expected response from the server. It can be set to 100-Continue. |
headers.x-ms-client-request-id | string | Optional | A unique identifier for the request. |
headers.x-ms-user-id | string | Optional | The same friendly name as x-ms-user. |
headers.x-ms-app | string | Optional | The friendly name of the application making the request. |
headers.x-ms-user | string | Optional | The friendly name of the user making the request. |
headers.x-ms-client-version | string | Optional | The friendly version identifier for the client making the request. |
headers.x-ms-readonly | string | Optional | If specified, it forces the request to run in read-only mode which prevents the request from changing data. |
Input Example
{"parameters":{"db":"string","csl":"string","properties":"string"},"headers":{"Host":"string","Expect":"string","x-ms-client-request-id":"string","x-ms-user-id":"string","x-ms-app":"string","x-ms-user":"string","x-ms-client-version":"string","x-ms-readonly":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"Content-Type":"application/json","Date":"Tue, 04 Feb 2025 12:04:15 GMT","Server":"Kestrel","Cache-Control":"no-store,no-cache","Content-Encoding":"gzip","Pragma":"no-cache","Transfer-Encoding":"chunked","Vary":"Accept-Encoding","x-ms-client-request-id":"unspecified;7d4ccafa-513a-4596-81c9-47a399a11f06","x-ms-activity-id":"2512d0de-7eaf-4409-84bb-e0a1e16c6757","Strict-Transport-Security":"max-age=2592000; includeSubDomains"},"reason":"OK","json_body":[{"Fra...
Launch KQL Query
Executes a Kusto Query Language (KQL) query within Azure Data Explorer using the provided JSON body and headers.
Endpoint
- URL: /v2/rest/query
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
headers | object | Required | HTTP headers for the request |
headers.Host | string | Required | The qualified domain name that the request was sent to. For example, help.kusto.windows.net. |
headers.Expect | string | Optional | The expected response from the server. It can be set to 100-Continue. |
headers.x-ms-client-request-id | string | Optional | A unique identifier for the request. |
headers.x-ms-user-id | string | Optional | The same friendly name as x-ms-user. |
headers.x-ms-app | string | Optional | The friendly name of the application making the request. |
headers.x-ms-user | string | Optional | The friendly name of the user making the request. |
headers.x-ms-client-version | string | Optional | The friendly version identifier for the client making the request. |
headers.x-ms-readonly | string | Optional | If specified, it forces the request to run in read-only mode which prevents the request from changing data. |
db | string | Optional | The name of the database that is the target of the query or management command. |
csl | string | Optional | The text of the query or management command to execute. |
properties | string | Optional | Request properties that modify how the request is processed and its results. |
Input Example
{"json_body":{"db":"Samples","csl":"print Test=\"Hello, World!\"","properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"},\"Parameters\":{},\"ClientRequestId\":\"MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1\"}"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"Content-Type":"application/json","Date":"Tue, 04 Feb 2025 12:03:23 GMT","Server":"Kestrel","Content-Encoding":"gzip","Transfer-Encoding":"chunked","Vary":"Accept-Encoding","x-ms-client-request-id":"unspecified;7d728610-38f7-49ea-a001-3f3aafb89312","x-ms-activity-id":"14d87bfa-d0ea-44d8-9da9-b50212715d72","Strict-Transport-Security":"max-age=2592000; includeSubDomains"},"reason":"OK","json_body":[{"FrameType":"DataSetHeader","IsProgressive":false,"Version":...
Response Headers
Header | Description | Example |
|---|---|---|
Cache-Control | Directives for caching mechanisms | no-store,no-cache |
Content-Encoding | HTTP response header: Content-Encoding | gzip |
Content-Type | The media type of the resource | application/json |
Date | The date and time at which the message was originated | Tue, 04 Feb 2025 12:04:15 GMT |
Pragma | HTTP response header: Pragma | no-cache |
Server | Information about the software used by the origin server | Kestrel |
Strict-Transport-Security | HTTP response header: Strict-Transport-Security | max-age=2592000; includeSubDomains |
Transfer-Encoding | HTTP response header: Transfer-Encoding | chunked |
Vary | HTTP response header: Vary | Accept-Encoding |
x-ms-activity-id | HTTP response header: x-ms-activity-id | 2512d0de-7eaf-4409-84bb-e0a1e16c6757 |
x-ms-client-request-id | HTTP response header: x-ms-client-request-id | unspecified;7d4ccafa-513a-4596-81c9-47a399a11f06 |