REST API용 Hello World Microsoft 365 Defender API

아티클
03/28/2022
읽는 데 4분 걸림

참고

Microsoft 365 Defender를 경험해 보고 싶으신가요? Microsoft 365 Defender 평가하고 파일럿하는 방법에 대해 자세히 알아보세요.

적용 대상:

Microsoft 365 Defender

중요

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

간단한 PowerShell 스크립트를 사용하여 인시던트 발생

이 프로젝트를 완료하는 데 5~10분 정도 걸립니다. 이 예상 기간에는 응용 프로그램을 등록하고 PowerShell 샘플 스크립트의 코드를 적용하는 것이 포함됩니다.

앱에서 앱을 Azure Active Directory

전역 관리자 역할을 사용하여 사용자로 Azure에 로그인 합니다.
Azure Active Directory App 등록 > 으로 이동합니다.

등록 양식에서 응용 프로그램의 이름을 선택한 다음 등록을 선택합니다. 리디렉션 URI는 선택 사항입니다. 이 예제를 완료하는 데는 이 예제가 필요하지 않습니다.
응용 프로그램 페이지에서 API 사용 > 권한 사 > 용 권한 APIS를 선택하고 > Microsoft Threat Protection 을 입력한 다음 Microsoft Threat Protection을 선택합니다. 이제 앱에서 앱에 액세스할 수 Microsoft 365 Defender.

팁

Microsoft Threat Protection 은 이전 이름인 Microsoft 365 Defender 목록에 나타나지 않습니다. 표시하려면 텍스트 상자에 이름을 쓰기 시작해야 합니다.
- 응용 프로그램 권한 > Incident.Read.All을 선택하고 사용 권한 추가를 선택합니다.
관리자 동의 부여를 선택합니다. 권한을 추가할 때마다 권한을 적용하려면 관리자 동의 부여를 선택해야 합니다.
응용 프로그램에 비밀을 추가합니다. 인증서 & 선택하고 비밀에 설명을 추가한 다음 추가를 선택합니다.

팁

추가를 선택한 후 생성된 비밀 값 복사를 선택합니다. 나가면 비밀 값을 검색할 수 없습니다.
안전한 곳에 응용 프로그램 ID와 테넌트 ID를 기록합니다. 응용 프로그램 페이지 개요 아래에 나열됩니다.

앱을 사용하여 토큰을 다운로드하고 토큰을 사용하여 API에 액세스

토큰에 대한 자세한 Azure Active Directory Azure AD 자습서를 참조하세요.

중요

이 데모 앱의 예제에서는 테스트를 위해 비밀 값에 붙여 넣는 것이 까다로우지만 프로덕션에서 실행되는 응용 프로그램에 암호를 하드코드하면 안 됩니다. 제3자에서 해당 비밀을 사용하여 리소스에 액세스할 수 있습니다. Azure Key Vault를 사용하여 앱의 비밀을 안전하게 유지할 수 있습니다. 앱을 보호하는 방법에 대한 실제 예제는 Azure Key Vault를 사용하여 서버 앱 의 암호 관리를 참조하세요.

아래 스크립트를 복사하여 즐겨 찾는 텍스트 편집기에 붙여 넣습니다. 을 로 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

토큰 유효성 검사

받은 토큰을 복사하여 JWT에 붙여넣어 디코딩합니다.
JWT 는 JSON 웹 토큰을 대용합니다. 디코딩된 토큰에는 다양한 JSON 형식의 항목 또는 클레임이 포함되어 있습니다. 디코딩된 토큰 내의 역할 클레임에 원하는 사용 권한이 포함되어 있는지 확인

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

최근 인시던트 목록 표시

아래 스크립트는 API에 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시간 동안 업데이트된 인시던트 반환