Microsoft Defender XDR REST API에 대한 헬로 월드

  • 아티클

적용 대상:

  • Microsoft Defender XDR

중요

일부 정보는 상용으로 출시되기 전에 실질적으로 수정될 수 있는 사전 릴리스된 제품과 관련이 있습니다. Microsoft는 여기에서 제공하는 정보와 관련하여 명시적이거나 묵시적인 어떠한 보증도 제공하지 않습니다.

간단한 PowerShell 스크립트를 사용하여 인시던트 가져오기

이 프로젝트를 완료하는 데 5~10분이 걸립니다. 이 시간 예상에는 애플리케이션을 등록하고 PowerShell 샘플 스크립트에서 코드를 적용하는 것이 포함됩니다.

Microsoft Entra ID 앱 등록

  1. 전역 관리자 역할을 가진 사용자로 Azure에 로그인합니다.

  2. Microsoft Entra ID>앱 등록>새 등록으로 이동합니다.

    Microsoft Defender 포털의 새 등록 섹션

  3. 등록 양식에서 애플리케이션의 이름을 선택한 다음 등록을 선택합니다. 리디렉션 URI를 선택하는 것은 선택 사항입니다. 이 예제를 완료하는 데 필요하지 않습니다.

  4. 애플리케이션 페이지에서 API 권한> 내organization 사용하는>권한> API 추가를 선택하고 Microsoft Threat Protection을 입력한 다음 Microsoft Threat Protection을 선택합니다. 이제 앱이 Microsoft Defender XDR 액세스할 수 있습니다.

    팁

    Microsoft Threat Protection은 Microsoft Defender XDR 이전 이름이며 원래 목록에 표시되지 않습니다. 표시되는 것을 보려면 텍스트 상자에 이름을 쓰기 시작해야 합니다. Microsoft Defender 포털의 API 사용 섹션

    • 애플리케이션 권한Incident.Read.All>을 선택하고 권한 추가를 선택합니다.

      Microsoft Defender 포털의 애플리케이션 사용 권한 창

  5. 관리자 동의 부여를 선택합니다. 권한을 추가할 때마다 적용하려면 관리자 동의 부여 를 선택해야 합니다.

    Microsoft Defender 포털의 관리자 동의 부여 섹션

  6. 애플리케이션에 비밀을 추가합니다. 비밀을 & 인증서를 선택하고, 비밀에 설명을 추가한 다음, 추가를 선택합니다.

    팁

    추가를 선택한 후 생성된 비밀 값 복사를 선택합니다. 떠난 후에는 비밀 값을 검색할 수 없습니다.

    Microsoft Defender 포털의 비밀 추가 섹션

  7. 안전한 곳에 애플리케이션 ID와 테넌트 ID를 기록합니다. 애플리케이션 페이지의 개요 아래에 나열됩니다.

    Microsoft Defender 포털의 개요 섹션

앱을 사용하여 토큰을 가져와 토큰을 사용하여 API에 액세스

Microsoft Entra 토큰에 대한 자세한 내용은 Microsoft Entra 자습서를 참조하세요.

중요

이 데모 앱의 예제에서는 테스트 목적으로 비밀 값을 붙여넣는 것이 권장되지만 프로덕션에서 실행되는 애플리케이션에 비밀을 하드 코딩해서는 안 됩니다. 타사에서 비밀을 사용하여 리소스에 액세스할 수 있습니다. Azure Key Vault 사용하여 앱의 비밀을 안전하게 유지할 수 있습니다. 앱을 보호하는 방법에 대한 실용적인 예제는 Azure Key Vault 사용하여 서버 앱에서 비밀 관리를 참조하세요.

  1. 아래 스크립트를 복사하여 즐겨 찾는 텍스트 편집기에 붙여넣습니다. 를Get-Token.ps1로 저장합니다. PowerShell ISE에서 코드를 있는 그대로 실행할 수도 있지만 다음 섹션에서 인시던트 가져오기 스크립트를 사용할 때 다시 실행해야 하므로 코드를 저장해야 합니다.

    이 스크립트는 토큰을 생성하고Latest-token.txt이름 아래의 작업 폴더에 저장 합니다. 

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
# Paste in your tenant ID, client ID and app secret (App key).

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = $resourceAppIdUri
  client_id = $clientId
  client_secret = $appSecret
  grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

토큰 유효성 검사

  1. 받은 토큰을 복사하여 JWT 에 붙여넣어 디코딩합니다.

  2. JWT 는 JSON 웹 토큰을 의미합니다. 디코딩된 토큰에는 여러 JSON 형식의 항목 또는 클레임이 포함됩니다. 디코딩된 토큰 내의 역할 클레임에 원하는 권한이 포함되어 있는지 확인합니다.

    다음 이미지에서는 , Incidents.ReadWrite.All및 AdvancedHunting.Read.All 권한을 사용하여 앱Incidents.Read.All에서 획득한 디코딩된 토큰을 볼 수 있습니다.

    Microsoft Defender 포털의 디코딩된 토큰 섹션

최근 인시던트 목록 가져오기

아래 스크립트는 Get-Token.ps1 사용하여 API에 액세스합니다. 그런 다음 지난 48시간 이내에 마지막으로 업데이트된 인시던트 목록을 검색하고 목록을 JSON 파일로 저장합니다.

중요

Get-Token.ps1 저장한 것과 동일한 폴더에 이 스크립트를 저장합니다.

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

# Set the webrequest headers
$headers = @{
    'Content-Type' = 'application/json'
    'Accept' = 'application/json'
    'Authorization' = "Bearer $token"
}

# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the incidents from the results.
$incidents =  ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

모두 완료되었습니다! 성공적으로 다음을 수행했습니다.

  • 애플리케이션을 만들고 등록했습니다.
  • 해당 애플리케이션에서 경고를 읽을 수 있는 권한이 부여되었습니다.
  • API에 연결되었습니다.
  • PowerShell 스크립트를 사용하여 지난 48시간 동안 업데이트된 인시던트를 반환했습니다.

팁

더 자세히 알아보고 싶으신가요? 기술 커뮤니티: Microsoft Defender XDR Tech Community의 Microsoft 보안 커뮤니티와 Engage.