KQL plugins in Microsoft Copilot for Security

Article
04/15/2024

Create powerful plugins using Kusto Query Language (KQL) queries to explore your data and discover patterns.

KQL skill settings

Common Settings

These settings are common to all KQL skills.

Settings:
  # What type of KQL endpoint to connect to.
  # One of { Defender, Sentinel, LogAnalytics, Kusto }
  Target: Sentinel
  # A URL to download the KQL query template from.
  # Specify either TemplatUrl or Template but not both.
  TemplateUrl: https://gist.githubusercontent.com/NitinKumarGoel/c862ba63878dd2624acb1b0e260f409a/raw/3a527014757b4ee1f00302a1b34a13e7b83ff77a/gistfile1.txt
  # An inline KQL query template.
  # Specify either TemplatUrl or Template but not both.
  Template: |-
    SigninLogs
    | where UserDisplayName == '{{user}}' or UserPrincipalName == '{{user}}'
    | project TimeGenerated, OperationName, UserDisplayName, UserPrincipalName, Location, ResourceDisplayName, ConditionalAccessStatus, IsInteractive
    | top 100 by TimeGenerated desc

The following table shows the settings that can be configured for any KQL skill targets:

Setting Name	Type	Description	Required
`Template`	string	KQL prompt template. Supports upto 80,000 chars.	Yes, if TemplateUrl isn't specified.
`TemplateUrl`	string	Public URL to download the KQL prompt template (upto 80,000 chars) from.	Yes. Specify either TemplatUrl or Template but not both.
`PackageUrl`	string	Public URL for the zip file with the KQL prompt template in it. Note: This is specified at SkillGroup level. Similar to GPT skill packageurl - example.	Yes, if Template or TemplateUrl aren't specified.
`TemplateFile`	string	Relative path to the KQL prompt template (upto 80,000 chars) within PackageUrl zip file.	Yes, if PackageUrl is specified.

Target specific settings

Target: Sentinel

These settings are valid for KQL skills where the Target is Sentinel.

Settings:
  # The ID of the AAD Organization that the Sentinel workspace is in.
  TenantId:
  # The id of the Azure Subscription that the Sentinel workspace is in.
  SubscriptionId:
  # The name of the Resource Group that the Sentinel workspace is in.
  ResourceGroupName:
  # The name of the Sentinel workspace.
  WorkspaceName:

Target: Kusto

These settings are valid for KQL skills where the Target is Kusto.

Settings:
  # The Kusto cluster URL.
  Cluster: 
  # The Kusto database name.
  Database:

Example

Descriptor:
  Name: SampleDefenderKQL
  DisplayName: My Sample Defender KQL Plugin
  Description: Skills to query email logs in M365 Advanced Hunting

SkillGroups:
  - Format: KQL
    Skills:
      - Name: GetLatestEmailsByRecipient
        DisplayName: Get Latest Emails By Recipient
        Description: Fetches the latest emails received by the user with the specified email address
        Inputs:
          - Name: email
            Description: The email address of the recipient
            Required: true
        Settings:
          Target: Defender
          Template: |-
            EmailEvents
            | where RecipientEmailAddress =~ '{{email}}'
            | project Timestamp, NetworkMessageId, SenderFromAddress, SenderDisplayName, Subject, DeliveryLocation
            | top 100 by Timestamp desc

Share via