Débuter avec Log Analytics : Partie 5 – Effectuer des requêtes KQL dans Log Analytics depuis PowerShell

Dans cet article nous allons continuer la série d’articles sur Log Analytics en utilisant PowerShell et l’API Log Analytics pour exécuter des requêtes KQL dans notre workspace.

La série d’article

• Partie 1 : Création du workspace Log Analytics
• Partie 2 : Importation d’informations dans le workspace
• Partie 3 : Création du workbook
• Partie 4 : Ajouter les données Intune dans un workspace Log Analytics
• Partie 5 : Utiliser l’API Log Analytics pour effectuer des requêtes KQL avec PowerShell (vous êtes ici)
• Partie 6 : Créer votre lab à partir de fausses données
• Partie 7 : Donner un meilleur look à vos workbook

Ce que nous souhaitons faire ?

L’idée est la suivante :

• Vous avez un workspace Log Analytics en place
• Vous avez différents logs tel que IntuneDevices
• Vous avez des Custom Logs
• Vous souhaitez interroger les données Log Analytics avec PowerShell

La solution

Pour cela nous procèderons tel que ci-dessous :

1. Création d’une application Azure
2. Ajout d’un secret
3. Assignation d’un rôle à l’application pour Log Analytics
4. Authentification sur le workspace Log Analytics via PowerShell
5. Exécution d’une requête KQL avec PowerShell

Création de l’application Azure

1. Allez dans le portail Azure
2. Allez dans App registrations
3. Cliquez sur New registration
4. Saisissez un nom
5. Laissez par défaut puis cliquez sur Register
6. Allez dans Overview
7. Notez le Client id

Création du client secret

Pour l’authentification nous aurons besoin d’un secret.
Pour le créer, il faudra procéder comme ci-dessous:

1. Cliquez sur Certificates & secrets
2. Cliquez sur New client secret
3. Saisir un nom
4. Choisir un délais d’expiration
5. Cliquez sur Add
6. Votre client secret sera affiché
7. Copiez le quelque part pour le réutiliser

Application Azure et Log Analytics

Afin de pouvoir effectuer des requêtes KQL dans Log Analytics depuis PowerShell et notre application Azure, nous allons devoir configurer un rôle pour le permettre.

Pour cela nous allons procéder comme ci-dessous:

1. Allez dans votre workspace Log Analytics
2. Allez dans Access control (IAM)

3. Cliquez sur Add > Add role assignment

4. Allez dans Roles > Log Analytics Reader> Next
5. Cliquez sur Review + Assign

Interroger Log Analytics avec PowerShell

Dans cette partie nous allons effectuer de simples requêtes KQL sur un workspace Log Analytics.

Authentification

La 1ère étape est d’obtenir un token qui nous permettra de prouver que nous avons l’autorisation pour accéder à Log Analytics au travers de l’application Azure, puis d’y effectuer des requêtes.
Complétez les variables suivantes avec vos données:

$appId = "Application ID de votre application Azure"
$tenantID = "Tenant ID de votre tenant Azure"
$workspace_ID = "ID de workspace Log Analytics"
$appSecret = "Secret de votre application Azure"

Pour obtenir un token, nous utiliserons le code suivant:

# Log Analytics API URL
$LogAnalytics_API_URL = 'https://api.loganalytics.io'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
# Création de l'authentification
$authBody = [Ordered] @{
     resource = "$LogAnalytics_API_URL"
     client_id = "$appId"
     client_secret = "$appSecret"
     grant_type = 'client_credentials'
}
# Obtention du token
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
# Création du header pour récupérer le token et l'utiliser dans une commande
$headers = @{
	'Content-Type' = 'application/json'
	Accept = 'application/json'
	Authorization = "Bearer $token"
}

Exécution de requêtes KQL

Nous allons dans un 1er temps effectuer une requête KQL simple sur la table IntuneDevices.
Cette table permet d’obtenir des informations sur vos appareils enrollés dans Intune.
Depuis le portail vous pouvez faire cela dans la partie Logs.
Ci-dessous la requête que nous souhaitons exécuter :

IntuneDevices | summarize arg_max(TimeGenerated,*) by DeviceName | project DeviceName, CreatedDate

Pour effectuer cela avec PowerShell utilisez le code suivant :

# Votre query
$My_Query = 'IntuneDevices | summarize arg_max(TimeGenerated,*) by DeviceName | project DeviceName, CreatedDate'
# URL permettant d'effectuer des queries en remote
$AdvancedQueries_URL = "https://api.loganalytics.io/v1/workspaces/$workspace_ID/query"
# Conversion de la query en JSON
$Query_Body = @{query = $My_Query} | ConvertTo-Json
# Exécution de la query avec méthode POST (pour faire une action) et récupération du résultat
$Query_response = Invoke-WebRequest -Method Post -Uri $AdvancedQueries_URL -Headers $headers -Body $Query_Body 
# Conversion des infos
$resultsTable = $Query_response.Content | ConvertFrom-Json
$count = 0
foreach ($table in $resultsTable.Tables) {
$count += $table.Rows.Count
}
$results = New-Object object[] $count
$i = 0;
foreach ($table in $resultsTable.Tables) {
    foreach ($row in $table.Rows) {
        $properties = @{}
        for ($columnNum=0; $columnNum -lt $table.Columns.Count; $columnNum++) {
            $properties[$table.Columns[$columnNum].name] = $row[$columnNum]
        }      
        $results[$i] = (New-Object PSObject -Property $properties)
        $null = $i++
    }
}
$results

Nous allons maintenant interroger un Custom Log (un Custom Log est un log que nous créons nous-même afin d’intégrer des données, voir ici).
Dans notre exemple, le Custom Log est un rapport sur l’état des BIOS.
Ci-dessous la requête que nous souhaitons exécuter :

DellBIOSUpdate_CL | project ComputerName_s, BIOSUpToDate_s, ModelFamilyName_s

Ci-dessous le résultat depuis le portail :

Pour effectuer cela avec PowerShell utilisez le code suivant :

# Votre query
$My_Query = 'DellBIOSUpdate_CL | project ComputerName_s, BIOSUpToDate_s, ModelFamilyName_s'
# URL permettant d'effectuer des queries en remote
$AdvancedQueries_URL = "https://api.loganalytics.io/v1/workspaces/$workspace_ID/query"
# Conversion de la query en JSON
$Query_Body = @{query = $My_Query} | ConvertTo-Json
# Exécution de la query avec méthode POST (pour faire une action) et récupération du résultat
$Query_response = Invoke-WebRequest -Method Post -Uri $AdvancedQueries_URL -Headers $headers -Body $Query_Body 
# Conversion des infos
$resultsTable = $Query_response.Content | ConvertFrom-Json
$count = 0
foreach ($table in $resultsTable.Tables) {
$count += $table.Rows.Count
}
$results = New-Object object[] $count
$i = 0;
foreach ($table in $resultsTable.Tables) {
    foreach ($row in $table.Rows) {
        $properties = @{}
        for ($columnNum=0; $columnNum -lt $table.Columns.Count; $columnNum++) {
            $properties[$table.Columns[$columnNum].name] = $row[$columnNum]
        }      
        $results[$i] = (New-Object PSObject -Property $properties)
        $null = $i++
    }
}
$results

Ci-dessous le résultat :