กราฟเชิงปฏิบัติ: การใช้ Microsoft AuditLog Query Graph API (ตัวอย่าง)

บันทึกการตรวจสอบแบบรวมเป็นแหล่งข้อมูลที่ยอดเยี่ยม

นับตั้งแต่เปิดตัวในปี 2016 บันทึกการตรวจสอบแบบรวมเป็นแหล่งข้อมูลที่ดีสำหรับผู้ดูแลระบบผู้เช่า Microsoft 365 บันทึกการตรวจสอบสามารถนำเข้าเหตุการณ์ต่างๆ ได้มากกว่า 1,600 เหตุการณ์ ขึ้นอยู่กับปริมาณงานที่ทำงานอยู่ในผู้เช่า ผู้เช่าที่มีสิทธิ์การใช้งาน Purview Audit (มาตรฐาน) (Office 365 E3) สามารถเข้าถึงกิจกรรมการตรวจสอบได้เป็นเวลา 180 วัน ในขณะที่ผู้เช่าที่มีสิทธิ์การใช้งาน Purview Audit (พรีเมียม) จะสามารถเข้าถึงกิจกรรมได้เป็นเวลา 365 วัน แม้จะมีการจัดรูปแบบข้อมูลที่ไม่คุ้นเคยในเหตุการณ์การตรวจสอบบางอย่างที่สร้างโดยปริมาณงานบางอย่าง แต่ก็ไม่มีข้อสงสัยเกี่ยวกับประโยชน์ของความสามารถในการสืบค้นบันทึกการตรวจสอบเพื่อค้นหาสิ่งที่เกิดขึ้นเมื่ออยู่ภายในผู้เช่า

ตามแผนงาน Microsoft 365 รายการ 117587 API จะพร้อมใช้งานโดยทั่วไปในเดือนพฤษภาคม 2024

API กราฟแบบสอบถาม AuditLog

จนถึงขณะนี้ วิธีทางโปรแกรมเดียวในการสืบค้นบันทึกการตรวจสอบคือการเรียกใช้ cmdlet Search-UnifiedAuditLog วิธีนี้ใช้ได้ผลดี แม้ว่า Microsoft จะทำการเปลี่ยนแปลงวิธีการทำงานของ cmdlet โดยไม่คาดคิดในช่วงกลางปี 2023 จนถึงขณะนี้ยังไม่มีคำอธิบายสาธารณะที่แสดงให้เห็นถึงความชอบธรรมของการเปลี่ยนแปลง ฉันเดาว่าการค้นพบการเปลี่ยนแปลงที่ไม่ได้แจ้งให้ทราบล่วงหน้าซึ่งส่งผลกระทบต่อสคริปต์ของลูกค้านั้นเป็นส่วนหนึ่งของความสุขในการทำงานในระบบคลาวด์

Microsoft เปิดตัวฟีเจอร์การค้นหาใหม่ในพอร์ทัล Purview Compliance ในปี 2022 แทนที่จะดำเนินการค้นหาแบบโต้ตอบ พอร์ทัลจะสร้างคำค้นหาที่บริการประมวลผลในเบื้องหลัง AuditLog Query Graph API (หรือที่เรียกว่า Microsoft Purview Audit Search API) เป็นคุณลักษณะการแสดงตัวอย่างเพื่อสร้างและเรียกใช้คำค้นหาและดึงผลลัพธ์การค้นหาในลักษณะเดียวกับที่ Purview ใช้ จำเป็นต้องมีขั้นตอนหลายขั้นตอนในการดำเนินการค้นหา:

• สร้างคำค้นหาโดยการตั้งค่าของพารามิเตอร์การค้นหา
• ส่งข้อความค้นหา (งาน)
• เมื่อคำค้นหาเสร็จสิ้น ให้เรียกค้นผลการค้นหา (บันทึกการตรวจสอบ)

ทั้งหมดนี้ฟังดูง่ายมาก แต่ซับซ้อนกว่าการเรียกใช้การค้นหาการตรวจสอบด้วย cmdlet Search-UnifiedAuditLog มาตรวจสอบ AuditLog Query API โดยละเอียดเพิ่มเติมอีกหน่อย

การสร้างแบบสอบถามการค้นหาการตรวจสอบ

ฉันใช้ Microsoft Graph PowerShell SDK เพื่อทดสอบ AuditLog Query API สิ่งแรกที่ควรทราบคือ ฉันใช้สิทธิ์ AuditLogsQuery.Read.All เพื่อเข้าถึงบันทึกการตรวจสอบ การอนุญาตนี้อนุญาตให้เข้าถึงข้อมูลการตรวจสอบทั้งหมด สิทธิ์อื่นๆ มีไว้เพื่อให้สิทธิ์การเข้าถึงข้อมูลการตรวจสอบอย่างจำกัด เช่น อนุญาตการเข้าถึงกิจกรรมการตรวจสอบ Exchange Online เท่านั้น คุณจะต้องลงชื่อเข้าใช้ด้วยบัญชีผู้ดูแลระบบเพื่อใช้สิทธิ์ที่ได้รับมอบหมาย งานที่รันเป็นกระบวนการเบื้องหลัง เช่น Azure Automation runbook ใช้สิทธิ์ของแอปพลิเคชันและไม่จำเป็นต้องลงชื่อเข้าใช้ในฐานะผู้ดูแลระบบ

โค้ดสนิปเปอร์นี้แสดงวิธีสร้างตารางแฮชพร้อมพารามิเตอร์สำหรับคำค้นหาใหม่ และวิธีการโพสต์คำค้นหาไปยังจุดสิ้นสุดคำค้นหาบันทึกการตรวจสอบเพื่อสร้างงานใหม่

$Uri = "https://graph.microsoft.com/beta/security/auditLog/queries"
$SearchName = ("Audit Search {0}" -f (Get-Date -format 'dd-MMM-yyyy HH:mm'))

$SearchParameters = @{
    "displayName"           = $SearchName
    "filterStartDateTime"   = $StartDateSearch
    "filterEndDateTime"     = $EndDateSearch
    "operationFilters"      = $Operations
}

$SearchQuery = Invoke-MgGraphRequest -Method POST -Uri $Uri -Body $SearchParameters
$SearchId = $SearchQuery.Id

ตัวแปร $Operations มีรายการเหตุการณ์การตรวจสอบที่คั่นด้วยเครื่องหมายจุลภาคเพื่อค้นหา วันที่เริ่มต้นและสิ้นสุดสำหรับการค้นหาจะถูกส่งผ่านในรูปแบบวันที่ที่จัดเรียงได้โดยมีส่วนต่อท้าย Z ต่อไปนี้เป็นตัวอย่างลักษณะของตารางแฮชสำหรับคิวรีที่ค้นหาการดำเนินการ SharePoint Online สองรายการตั้งแต่เที่ยงคืนของวันที่ 29 กุมภาพันธ์ 2024 จนถึงเที่ยงคืนของวันที่ 2 มีนาคม 2024:

Name                           Value
----                           -----
filterEndDateTime              2024-03-02T00:00:00Z
displayname                    Audit Search 04-Mar-2024 05:29
filterStartarDateTime          2024-02-29T00:00:00Z
operationsFilters              {fileuploaded, filemodified}

บางคนชอบดึงบันทึกการตรวจสอบทั้งหมดเป็นระยะเวลาหนึ่ง เนื่องจากต้องการโหลดข้อมูลการตรวจสอบลงใน SIEM เพื่อวัตถุประสงค์ในการเก็บรักษาและสืบค้นในระยะยาว ด้วย Search-UnifiedAuditLog cmdlet วิธีการดึงบันทึกการตรวจสอบที่มีอยู่ทั้งหมดคือการไม่ต้องระบุการดำเนินการใดๆ

หากต้องการดึงบันทึกการตรวจสอบทั้งหมดในช่วงเวลาใดเวลาหนึ่ง อย่ารวม operationsFilter ในพารามิเตอร์ที่ใช้สำหรับการสืบค้นบันทึกการตรวจสอบ พารามิเตอร์จะเป็นเพียงแค่ชื่อที่แสดง วันที่และเวลาเริ่มต้น และวันที่และเวลาสิ้นสุด หรือคุณสามารถรวมตัวกรอง recordTypeFilters เพื่อกำหนดชุดประเภทบันทึกการตรวจสอบที่คุณสนใจ

การเรียกใช้แบบสอบถามการค้นหาการตรวจสอบ

คำค้นหาอาจใช้เวลาถึงสิบนาทีจึงจะเสร็จสมบูรณ์ ในที่สุด การค้นหาก็เสร็จสิ้น และคุณสามารถดึงบันทึกการตรวจสอบใดๆ ก็ตามที่แบบสอบถามพบได้ ตัวอย่างนี้แสดงวิธีดึงข้อมูลบันทึกการตรวจสอบหน้าแรก

$Uri = ("https://graph.microsoft.com/beta/security/auditLog/queries/{0}/records" -f $SearchId)
[array]$SearchRecords = Invoke-MgGraphRequest -Uri $Uri -Method GET

API ส่งคืน 150 รายการในหนึ่งหน้า หากมีบันทึกน้อยกว่า 150 รายการที่จะดึงข้อมูล คุณสามารถดำเนินการวิเคราะห์บันทึกที่ส่งคืนได้ อย่างไรก็ตาม หากมีข้อมูลเพิ่มเติม โค้ดของคุณต้องใช้ URI ของลิงก์ถัดไปที่ส่งคืนเมื่อมีข้อมูลเพิ่มเติมเพื่อดึงหน้าถัดไปจนกว่าจะไม่มีอีกต่อไป การบังคับให้โค้ดดึงข้อมูลเป็นชิ้นที่จำกัดเป็นกระบวนการทั่วไปที่เรียกว่าการแบ่งหน้าซึ่ง Graph API ใช้เพื่อจำกัดจำนวนข้อมูลที่ดึงมาในคราวเดียว นี่คือโค้ดสำหรับแบ่งหน้าและดึงบันทึกการตรวจสอบที่มีอยู่สำหรับการสืบค้น:

# Paginate to fetch all available audit records
$NextLink = $SearchRecords.'@Odata.NextLink'
While ($null -ne $NextLink) {
    $SearchRecords = $null
    [array]$SearchRecords = Invoke-MgGraphRequest -Uri $NextLink -Method GET 
    $AuditRecords += $SearchRecords.value
    Write-Host ("{0} audit records fetched so far..." -f $AuditRecords.count)
    $NextLink = $SearchRecords.'@odata.NextLink' 
}

การแบ่งหน้าทำงานได้ดีกับ Graph API เวอร์ชันตัวอย่างของ AuditLog Query API ดูเหมือนจะค่อนข้างละเอียดอ่อน และความพยายามบางอย่างของฉันในการใช้พอยน์เตอร์ลิงก์ถัดไปส่งผลให้เกิด “500 Internal Server Error” ซึ่งบล็อกความพยายามในการดึงบันทึกการตรวจสอบ

Microsoft Graph PowerShell SDK ช่วยให้นักพัฒนาง่ายขึ้นโดยรวมพารามิเตอร์ ทั้งหมด สำหรับ cmdlets จำนวนมากเพื่อดึงข้อมูลที่มีอยู่ทั้งหมด Cmdlets เพื่อจัดการแบบสอบถามบันทึกการตรวจสอบมีอยู่ใน Microsoft Graph PowerShell SDK (V2.15) ตัวอย่างเช่น หากต้องการดึงข้อมูลบันทึกการตรวจสอบที่พบในแบบสอบถาม คุณสามารถเรียกใช้ cmdlet Get-MgBetaSecurityAuditLogQueryRecord และระบุพารามิเตอร์ ทั้งหมด:

[array]$AuditRecords = Get-MgBetaSecurityAuditLogQueryRecord -AuditLogQueryId $SearchId -All

เมื่อมองแวบแรก cmdlet ดูเหมือนจะเป็นวิธีที่ดีในการดึงบันทึกการตรวจสอบทั้งหมดที่ส่งคืนโดยการค้นหาบันทึกการตรวจสอบ cmdlet ส่งคืนบันทึกทั้งหมด แต่ไม่ว่าฉันจะทำอะไร เนื้อหาของคุณสมบัติ AuditData จะเป็น Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphSecurityAuditData เสมอ หากไม่มีเนื้อหาของคุณสมบัติ AuditData ที่จะวิเคราะห์ ค่าของบันทึกการตรวจสอบที่ดึงข้อมูลก็จะลดลงอย่างมาก ผลที่สุดคือฉันยังคงทำงานกับคิวรี่กราฟต่อไป ปัญหานี้เป็นสิ่งที่น่าจะได้รับการแก้ไขเมื่อ Microsoft นำ API ไปสู่ความพร้อมใช้งานทั่วไป

การวิเคราะห์ข้อมูลการตรวจสอบ

บันทึกการตรวจสอบมีสองส่วน รายการแรกจะคงที่ในทุกปริมาณงานและมีข้อมูล เช่น การประทับเวลา ชื่อการดำเนินการ และบัญชีผู้ใช้หรือระบบที่รับผิดชอบในการดำเนินการ ส่วนที่สองซึ่งจัดเก็บไว้ในคุณสมบัติ AuditData คือตำแหน่งที่ข้อมูลเกี่ยวกับสิ่งที่เกิดขึ้น ปริมาณงานแต่ละรายการจะควบคุมข้อมูลที่จัดเก็บไว้ใน AuditData และมีความแตกต่างอย่างมากระหว่างปริมาณงาน ด้วยเหตุนี้ การแยกวิเคราะห์เนื้อหาของบันทึกการตรวจสอบจึงต้องใช้ความพยายามและการเขียนโค้ดตามความต้องการมากกว่าที่จำเป็น

ข่าวดีก็คือ AuditLog Query API ส่งคืนคุณสมบัติ AuditData เป็นตารางแฮชที่เข้าถึงได้ง่าย ข่าวร้ายก็คือ มีความแปรปรวนในเนื้อหาเหมือนกันกับปริมาณงาน (ฉันไม่ได้คาดหวังสิ่งอื่นใด) กล่าวอีกนัยหนึ่ง สำหรับเหตุการณ์การตรวจสอบแต่ละประเภท คุณต้องทราบว่าคุณสมบัติ AuditData เก็บข้อมูลอะไรไว้และข้อมูลมีความหมายอย่างไรในลักษณะเดียวกันกับผลลัพธ์ที่สร้างโดย Search-UnifiedAuditLog cmdlet.

รูปที่ 1 แสดงข้อมูลบางส่วนจากบันทึกการตรวจสอบที่ดึงมาจากแบบสอบถาม ฉันไม่รู้ว่าวัตถุใดมีตัวระบุ eba15bfd-c28e-4433-a20e-0278888c5825 ฉันไม่พบบัญชีผู้ใช้หรือบริการหลักที่มีค่านี้ มันเป็นเรื่องลึกลับที่น่ายินดี

คุณสามารถดาวน์โหลดสคริปต์ที่ฉันใช้ในการทดสอบได้จาก GitHub

มุ่งเน้นไปที่ความง่ายในการตรวจสอบการแยกเหตุการณ์

สิ่งสำคัญคือต้องจำไว้เสมอเมื่อซอฟต์แวร์อยู่ในขั้นตอนการดูตัวอย่าง โค้ดมีไว้สำหรับให้ผู้คนทดสอบ และจะมีการปรับปรุงก่อนที่จะเผยแพร่สู่สาธารณะ เมื่อพิจารณาจากจำนวนข้อมูลการตรวจสอบที่สร้างโดยการดำเนินงานของ Microsoft 365 เป็นที่เข้าใจได้ว่า Microsoft ต้องการย้ายออกจากการดำเนินการค้นหาการตรวจสอบเชิงโต้ตอบแบบซิงโครนัสประเภทที่ดำเนินการโดย cmdlet Search-UnifiedAuditLog ไปเป็นบางสิ่งที่ปรับให้เข้ากับบริการมากขึ้น การดำเนินการที่สามารถทำงานในเบื้องหลังได้ นั่นคือวิธีที่พอร์ทัลปฏิบัติตามข้อกำหนดของ Purview ทำงานอยู่ในขณะนี้ และการมีอยู่ของ AuditLog Query API ก็เป็นอีกสัญญาณหนึ่งที่ Microsoft ต้องการให้ผู้ดูแลระบบซักถามเหตุการณ์การตรวจสอบในโหมดนี้

ปัญหาของ Microsoft ก็คือความง่ายในการทำงานกับ PowerShell cmdlet เดียว เมื่อเทียบกับความซับซ้อนของการตั้งค่าการค้นหาการตรวจสอบแบบอะซิงโครนัสเพื่อให้ทำงานในเบื้องหลัง แล้วดึงผลลัพธ์ออกมา ทำให้ผู้ดูแลระบบมีแนวโน้มที่จะหลีกเลี่ยงแนวทาง Graph API ใครๆ ก็ชอบชีวิตที่เรียบง่าย และ Search-UnifiedAuditLog ยังคงเป็นวิธีที่ง่ายที่สุดในการดึงข้อมูลจากบันทึกการตรวจสอบของ Microsoft 365