엔드포인트용 Microsoft Defender API - 헬로 월드

  • 아티클

적용 대상:

엔드포인트용 Microsoft Defender를 경험하고 싶으신가요? 무료 평가판을 신청하세요.

참고

미국 정부 고객인 경우 미국 정부 고객을 위해 엔드포인트용 Microsoft Defender 나열된 URI를 사용하세요.

팁

성능을 향상시키려면 서버를 지리적 위치에 더 가깝게 사용할 수 있습니다.

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com

간단한 PowerShell 스크립트를 사용하여 경고 가져오기

이 예제를 진행하는 데 얼마나 걸리나요?

다음 두 단계로 완료하는 데 5분밖에 걸리지 않습니다.

  • 애플리케이션 등록
  • 예제 사용: 짧은 PowerShell 스크립트의 복사/붙여넣기만 필요

연결할 수 있는 권한이 필요한가요?

애플리케이션 등록 단계의 경우 Microsoft Entra 테넌트에서 전역 관리자 역할이 있어야 합니다.

1단계 - Microsoft Entra ID 앱 Create

  1. 전역 관리자 사용자로 Azure에 로그온합니다.

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

    Microsoft Entra 관리 센터 관리 창 아래의 앱 등록 옵션

  3. 등록 양식에서 애플리케이션의 이름을 선택한 다음 등록을 클릭합니다.

  4. 애플리케이션이 엔드포인트용 Defender에 액세스하고 '모든 경고 읽기' 권한을 할당하도록 허용합니다.

    • 애플리케이션 페이지에서 API 권한> 내organization 사용하는>권한> API 추가 WindowsDefenderATP를 클릭하고 WindowsDefenderATP를 클릭합니다.

      참고

      WindowsDefenderATP는 원래 목록에 표시되지 않습니다. 표시되는 것을 보려면 텍스트 상자에 이름을 쓰기 시작해야 합니다.

      Microsoft Entra 관리 센터 관리 창 아래의 API 권한 옵션

    • 애플리케이션 권한>Alert.Read.All> 클릭 권한 추가를 선택합니다.

      API 권한 요청 페이지의 사용 권한 유형 및 설정 창

      중요

      관련 권한을 선택해야 합니다. '모든 경고 읽기'는 예제일 뿐입니다.

      예시:

      • 고급 쿼리를 실행하려면 '고급 쿼리 실행' 권한을 선택합니다.
      • 컴퓨터를 격리하려면 '컴퓨터 격리' 권한을 선택합니다.
      • 필요한 권한을 확인하려면 호출하려는 API의 사용 권한 섹션을 참조하세요.

  5. 동의 부여를 클릭합니다.

    참고

    권한을 추가할 때마다 새 권한이 적용되려면 동의 부여 를 클릭해야 합니다.

    Microsoft Entra 관리 센터 권한 부여 동의 옵션

  6. 애플리케이션에 비밀을 추가합니다.

    비밀을 & 인증서를 클릭하고 비밀에 설명을 추가하고 추가를 클릭합니다.

    중요

    추가를 클릭한 후 생성된 비밀 값을 복사합니다. 당신은 당신이 떠난 후 검색 할 수 없습니다!

    Microsoft Entra 관리 센터 관리 창의 인증서 & 비밀 메뉴 항목

  7. 애플리케이션 ID 및 테넌트 ID를 적어 씁니다.

    애플리케이션 페이지에서 개요 로 이동하여 다음을 복사합니다.

    Microsoft Entra 관리 센터 개요 메뉴 항목 아래의 애플리케이션 세부 정보 창

완료되었습니다! 애플리케이션을 성공적으로 등록했습니다!

2단계 - 앱을 사용하여 토큰을 가져와서 이 토큰을 사용하여 API에 액세스합니다.

  • 아래 스크립트를 PowerShell ISE 또는 텍스트 편집기로 복사하고 Get-Token.ps1로 저장합니다.

  • 이 스크립트를 실행하면 토큰이 생성되고 Latest-token.txt이름 아래 의 작업 폴더에 저장됩니다.

    # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application secret here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
     resource = "$resourceAppIdUri"
     client_id = "$appId"
     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

  • 정신 검사:

    • 스크립트를 실행합니다.
    • 브라우저에서 로 https://jwt.ms/이동합니다.
    • 토큰(Latest-token.txt 파일의 콘텐츠)을 복사합니다.
    • 위쪽 상자에 붙여넣습니다.
    • "역할" 섹션을 찾습니다. Alert.Read.All 역할을 찾습니다.

    jwt.ms 대한 디코딩된 토큰 창

경고를 확인해 보겠습니다.

  • 아래 스크립트는 Get-Token.ps1 사용하여 API에 액세스하고 지난 48시간 경고를 받습니다.

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

  • 스크립트는 스크립트와 동일한 폴더에 데이터가 있는 두 개의 파일(json 및 csv)을 만듭니다.

    # Returns Alerts created in the past 48 hours.

$token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1

# Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# The URL contains the type of query and the time filter we create above
# Read more about [other query options and filters](get-alerts.md).
$url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"

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

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

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

# Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json and as csv
$outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
$outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"

Out-File -FilePath $outputJsonPath -InputObject $alerts
($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation

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

  • 생성 및 등록 및 애플리케이션
  • 해당 애플리케이션에서 경고를 읽을 수 있는 권한이 부여됨
  • API 연결
  • PowerShell 스크립트를 사용하여 지난 48시간 동안 생성된 경고 반환

팁

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