Microsoft Sentinel에 위협 인텔리전스를 가져오려면 업로드 표시기 API(미리 보기)를 참조하세요.
Microsoft Sentinel 업로드 표시기 API를 사용하면 위협 인텔리전스 플랫폼 또는 사용자 지정 애플리케이션이 STIX 형식의 손상 지표를 Microsoft Sentinel 작업 영역으로 가져올 수 있습니다. Microsoft Sentinel 업로드 표시기 API 데이터 커넥터와 함께 API를 사용하든 사용자 지정 솔루션의 일부로 사용하든 이 문서는 참조로 사용됩니다.
Important
이 API는 현재 미리 보기로 제공됩니다. Azure Preview 추가 약관에는 베타, 미리 보기 또는 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 추가 법률 용어가 포함되어 있습니다.
업로드 표시기 API 호출에는 다음과 같은 5가지 구성 요소가 있습니다.
- 요청 URI…
- HTTP 요청 메시지 헤더
- HTTP 요청 메시지 본문
- 필요에 따라 HTTP 응답 메시지 헤더 처리
- 필요에 따라 HTTP 응답 메시지 본문 처리
Microsoft Entra ID를 사용하여 클라이언트 애플리케이션 등록
Microsoft Sentinel에 인증하려면 업로드 표시기 API에 대한 요청에 유효한 Microsoft Entra 액세스 토큰이 필요합니다. 애플리케이션 등록에 대한 자세한 내용은 Microsoft ID 플랫폼 애플리케이션 등록을 참조하거나 업로드 표시기 API 데이터 커넥터 설정의 일부로 기본 단계를 참조하세요.
사용 권한
이 API를 사용하려면 호출하는 Microsoft Entra 애플리케이션에 작업 영역 수준에서 Microsoft Sentinel 기여자 역할이 부여되어야 합니다.
요청 만들기
이 섹션에서는 앞에서 설명한 5개 구성 요소 중 처음 3개에 대해 설명합니다. 먼저 요청 메시지 헤더를 어셈블하는 데 사용하는 Microsoft Entra ID에서 액세스 토큰을 획득해야 합니다.
액세스 토큰 획득
OAuth 2.0 인증을 사용하여 Microsoft Entra 액세스 토큰을 획득합니다. V1.0 및 V2.0 은 API에서 허용하는 유효한 토큰입니다.
애플리케이션이 수신하는 토큰 버전(v1.0 또는 v2.0)은 애플리케이션이 호출하는 API의 앱 매니페스트에 있는 속성에 의해 accessTokenAcceptedVersion 결정됩니다. 1로 설정된 경우 accessTokenAcceptedVersion 애플리케이션은 v1.0 토큰을 받습니다.
Microsoft 인증 라이브러리 MSAL 을 사용하여 v1.0 또는 v2.0 액세스 토큰을 획득합니다. 또는 REST API에 다음 형식으로 요청을 보냅니다.
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Microsoft Entra 앱을 사용하기 위한 헤더:
- grant_type: "client_credentials"
- client_id: {Microsoft Entra App의 클라이언트 ID}
- client_secret: {Microsoft Entra App의 비밀}
- 범위:
"https://management.azure.com/.default"
앱 매니페스트에서 1로 설정된 경우 accessTokenAcceptedVersion 애플리케이션은 v2 토큰 엔드포인트를 호출하더라도 v1.0 액세스 토큰을 받습니다.
리소스/범위 값은 토큰의 대상입니다. 이 API는 다음 대상 그룹만 허용합니다.
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
요청 메시지 어셈블
업로드 표시기 API에는 두 가지 버전이 있습니다. 엔드포인트에 따라 요청 본문에 다른 배열 이름이 필요합니다. 이는 두 버전의 논리 앱 커넥터 작업으로도 표시됩니다.
커넥터 작업 이름: 위협 인텔리전스 - 손상 지표 업로드(사용되지 않음)
- 엔드포인트:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - 표시기 이름 배열:
value{ "sourcesystem":"TIsource-example", "value":[] }
- 엔드포인트:
커넥터 작업 이름: 위협 인텔리전스 - 손상 지표 업로드(V2)(미리 보기)
- 엔드포인트:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - 표시기 이름 배열:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- 엔드포인트:
요청 URI
API 버전 관리: api-version=2022-07-01
엔드포인트: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
메서드: POST
요청 헤더
Authorization: OAuth2 전달자 토큰을 포함합니다.
Content-Type: application/json
요청 본문
본문의 JSON 개체에는 다음 필드가 포함됩니다.
| 필드 이름 | 데이터 형식 | 설명 |
|---|---|---|
| SourceSystem(필수) | string | 원본 시스템 이름을 식별합니다. 값 Microsoft Sentinel 이 제한됩니다. |
| 표시기(필수) | 배열 | STIX 2.0 또는 2.1 형식의 표시기 배열 |
STIX 2.1 표시기 형식 사양을 사용하여 표시기 배열을 만듭니다. 이 사양은 중요한 섹션에 대한 링크와 함께 편의를 위해 여기에 압축되었습니다. 또한 일부 속성은 STIX 2.1에 유효하지만 Microsoft Sentinel에는 해당 표시기 속성이 없습니다.
| 속성 이름 | Type | 설명 |
|---|---|---|
id (필수) |
string | 표시기를 식별하는 데 사용되는 ID입니다. 만드는 방법에 대한 사양은 2.9 섹션을 참조하세요id. 형식은 다음과 같습니다. indicator--<UUID> |
spec_version(선택 사항) |
string | STIX 표시기 버전입니다. 이 값은 STIX 사양에 필요하지만 이 API는 STIX 2.0 및 2.1만 지원하므로 이 필드가 설정되지 않은 경우 API는 기본값으로 설정됩니다. 2.1 |
type (필수) |
string | 이 속성의 값은 이어야 indicator합니다. |
created (필수) |
timestamp | 이 공통 속성의 사양은 섹션 3.2 를 참조하세요. |
modified (필수) |
timestamp | 이 공통 속성의 사양은 섹션 3.2 를 참조하세요. |
name(선택 사항) |
string | 표시기를 식별하는 데 사용되는 이름입니다. 생산자는 제품 및 분석가가 이 지표가 실제로 수행하는 작업을 이해할 수 있도록 이 속성을 제공해야 합니다 . |
description(선택 사항) |
string | 표시기 용도 및 주요 특징을 비롯하여 지표에 대한 자세한 내용과 컨텍스트를 제공하는 설명입니다. 생산자는 제품 및 분석가가 이 지표가 실제로 수행하는 작업을 이해할 수 있도록 이 속성을 제공해야 합니다 . |
indicator_types(선택 사항) |
문자열 목록 | 이 표시기의 분류 집합입니다. 이 속성 의 값은 indicator-type-ov에서 가져옵니다. |
pattern (필수) |
string | 이 지표의 검색 패턴은 STIX 패턴 또는 다른 적절한 언어(예: SNORT, YARA 등)로 표현될 수 있습니다. |
pattern_type (필수) |
string | 이 표시기에서 사용되는 패턴 언어입니다. 이 속성의 값은 패턴 형식에서 가져옵니다. 이 속성의 값은 패턴 속성 에 포함된 패턴 데이터의 형식과 일치해야 합니다 . |
pattern_version(선택 사항) |
string | 패턴 속성의 데이터에 사용되는 패턴 언어의 버전으로 , 패턴 속성에 포함된 패턴 데이터의 형식과 일치해야 합니다 . 공식 사양이 없는 패턴의 경우 패턴이 작동하는 것으로 알려진 빌드 또는 코드 버전을 사용해야 합니다 . STIX 패턴 언어의 경우 개체의 사양 버전에 따라 기본값이 결정됩니다. 다른 언어의 경우 기본값 은 이 개체를 만들 때 패턴 언어의 최신 버전이어야 합니다 . |
valid_from (필수) |
timestamp | 이 표시기가 관련되거나 나타내는 동작의 유효한 지표로 간주되는 시간입니다. |
valid_until(선택 사항) |
timestamp | 이 표시기가 관련되거나 나타내는 동작의 유효한 지표로 더 이상 간주되지 않아야 하는 시간입니다. valid_until 속성을 생략하면 표시기가 유효한 최신 시간에 대한 제약 조건이 없습니다. 이 타임스탬프는 valid_from 타임스탬프보다 커야 합니다 . |
kill_chain_phases(선택 사항) |
문자열 목록 | 이 표시기가 해당하는 킬 체인 단계입니다. 이 속성 의 값은 Kill Chain 단계에서 가져옵니다. |
created_by_ref(선택 사항) |
string | created_by_ref 속성은 이 개체를 만든 엔터티의 ID 속성을 지정합니다. 이 특성을 생략하면 이 정보의 원본이 정의되지 않습니다. 익명으로 유지하려는 개체 작성자의 경우 이 값을 정의되지 않은 상태로 유지합니다. |
revoked(선택 사항) |
부울 값 | 취소된 개체는 더 이상 개체 작성자가 유효하지 않은 것으로 간주합니다. 개체를 취소하는 것은 영구적입니다. 이 id 개체의 이후 버전을 만들 수 없습니다 .이 속성의 기본값은 false입니다. |
labels(선택 사항) |
문자열 목록 | 이 속성은 이 labels 개체를 설명하는 데 사용되는 용어 집합을 지정합니다. 용어는 사용자 정의 또는 트러스트 그룹 정의입니다. 이러한 레이블은 Microsoft Sentinel에서 태그로 표시됩니다. |
confidence(선택 사항) |
정수 | 이 속성은 confidence 작성자가 데이터의 정확성을 가지고 있다는 확신을 식별합니다. 신뢰도 값 은 0-100 범위의 숫자여야 합니다 .부록 A에는 해당 눈금 중 하나에 신뢰도 값을 표시할 때 사용해야 하는 다른 신뢰도 배율에 대한 표준 매핑 테이블이 포함되어 있습니다. 신뢰도 속성이 없으면 콘텐츠의 신뢰도가 지정되지 않습니다. |
lang(선택 사항) |
string | 이 속성은 이 lang 개체의 텍스트 콘텐츠 언어를 식별합니다. 있는 경우 RFC5646 준수하는 언어 코드여야 합니다. 속성이 없는 경우 콘텐츠의 언어는 (영어)입니다 en .개체 형식에 번역 가능한 텍스트 속성(예: 이름, 설명)이 포함된 경우 이 속성 이 있어야 합니다 . 이 개체의 개별 필드 언어는 세분화된 표시로 속성을 재정 lang 의할 수 있습니다(섹션 7.2.3 참조). |
object_marking_refs (선택 사항( TLP 포함) |
문자열 목록 | 이 속성은 이 object_marking_refs 개체에 적용되는 마킹 정의 개체의 ID 속성 목록을 지정합니다. 예를 들어 TLP(신호등 프로토콜) 표시 정의 ID를 사용하여 표시기 원본의 민감도를 지정합니다. TLP 콘텐츠에 사용할 마킹 정의 ID에 대한 자세한 내용은 섹션 7.2.1.4를 참조하세요.드물긴 하지만 정의 자체를 표시하는 것은 공유 또는 처리 지침으로 표시될 수 있습니다. 이 경우 이 속성 은 동일한 표시 정의 개체에 대한 참조를 포함해서는 안 됩니다(즉, 순환 참조를 포함할 수 없음). 데이터 표시에 대한 추가 정의는 섹션 7.2.2 를 참조하세요. |
external_references(선택 사항) |
개체 목록 | 이 속성은 external_references 비 STIX 정보를 참조하는 외부 참조 목록을 지정합니다. 이 속성은 하나 이상의 URL, 설명 또는 ID를 다른 시스템의 레코드에 제공하는 데 사용됩니다. |
granular_markings(선택 사항) |
세분화된 표시 목록 | 이 속성은 granular_markings 표시기의 일부를 다르게 정의하는 데 도움이 됩니다. 예를 들어 표시기 언어는 영어 en 이지만 설명은 독일어 de입니다.드물긴 하지만 정의 자체를 표시하는 것은 공유 또는 처리 지침으로 표시될 수 있습니다. 이 경우 이 속성 은 동일한 표시 정의 개체에 대한 참조를 포함해서는 안 됩니다(예: 순환 참조를 포함할 수 없음). 데이터 표시에 대한 추가 정의는 섹션 7.2.3 을 참조하세요. |
응답 메시지 처리
응답 헤더에는 HTTP 상태 코드가 포함되어 있습니다. API 호출 결과를 해석하는 방법에 대한 자세한 내용은 이 표를 참조하세요.
| 상태 코드 | Description |
|---|---|
| 200 | 성공. 하나 이상의 지표가 성공적으로 유효성을 검사하고 게시되면 API는 200을 반환합니다. |
| 400 | 잘못된 형식입니다. 요청의 형식이 올바르게 지정되지 않았습니다. |
| 401 | 권한이 없습니다. |
| 404 | 파일을 찾을 수 없습니다. 일반적으로 이 오류는 작업 영역 ID를 찾을 수 없을 때 발생합니다. |
| 429 | 1분의 요청 수가 초과되었습니다. |
| 500 | 서버 오류입니다. 일반적으로 API 또는 Microsoft Sentinel 서비스의 오류입니다. |
응답 본문은 JSON 형식의 오류 메시지 배열입니다.
| 필드 이름 | 데이터 형식 | 설명 |
|---|---|---|
| 오류 | 오류 개체의 배열 | 유효성 검사 오류 목록 |
Error 개체
| 필드 이름 | 데이터 형식 | 설명 |
|---|---|---|
| recordIndex | int | 요청의 지표 인덱스 |
| errorMessages | 문자열 배열 | 오류 메시지 |
API에 대한 제한 제한
모든 제한은 사용자별로 적용됩니다.
- 요청당 100개의 지표.
- 분당 100개 요청.
한도 429 보다 많은 요청이 있는 경우 응답 헤더의 http 상태 코드가 다음 응답 본문과 함께 반환됩니다.
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
제한 오류가 수신되기 전의 최대 처리량은 분당 약 10,000개의 표시기입니다.
샘플 요청 본문
{
"sourcesystem": "test",
"indicators":[
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--10000003-71a2-445c-ab86-927291df48f8",
"name": "Test Indicator 1",
"created": "2010-02-26T18:29:07.778Z",
"modified": "2011-02-26T18:29:07.778Z",
"pattern": "[ipv4-addr:value = '172.29.6.7']",
"pattern_type": "stix",
"valid_from": "2015-02-26T18:29:07.778Z"
},
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52",
"created": "2023-01-01T18:29:07.778Z",
"modified": "2025-02-26T18:29:07.778Z",
"created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7",
"revoked": false,
"labels": [
"label 1",
"label 2"
],
"confidence": 55,
"lang": "en",
"external_references": [
{
"source_name": "External Test Source",
"description": "Test Report",
"external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f",
"url": "https://fabrikam.com//testreport.json",
"hashes": {
"SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
}
}
],
"object_marking_refs": [
"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
],
"granular_markings": [
{
"marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80",
"selectors": [ "description", "labels" ],
"lang": "en"
}
],
"name": "Test Indicator 2",
"description": "This is a test indicator to demo valid fields",
"indicator_types": [
"threatstream-severity-low", "threatstream-confidence-80"
],
"pattern": "[ipv4-addr:value = '192.168.1.1']",
"pattern_type": "stix",
"pattern_version": "2.1",
"valid_from": "2023-01-01T18:29:07.778Z",
"valid_until": "2025-02-26T18:29:07.778Z",
"kill_chain_phases": [
{
"kill_chain_name": "lockheed-martin-cyber-kill-chain",
"phase_name": "reconnaissance"
}
]
}
]
}
유효성 검사 오류가 있는 샘플 응답 본문
모든 표시기가 성공적으로 유효성을 검사하면 HTTP 200 상태가 빈 응답 본문과 함께 반환됩니다.
하나 이상의 지표에 대한 유효성 검사가 실패하면 응답 본문이 추가 정보와 함께 반환됩니다. 예를 들어 네 개의 표시기가 있는 배열을 보내고 처음 3개는 양호하지만 네 번째 표시기는 필수 필드가 없는 id 경우 다음 본문과 함께 HTTP 상태 코드 200 응답이 생성됩니다.
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
표시기가 배열로 전송되므로 recordIndex .에서 0시작됩니다.
다음 단계
Microsoft Sentinel에서 위협 인텔리전스를 사용하는 방법에 대한 자세한 내용은 다음 문서를 참조하세요.
- 위협 인텔리전스 이해
- 위협 지표 작업
- 일치 분석을 사용하여 위협 감지
- Microsoft의 인텔리전스 피드를 활용하고 MDTI 데이터 커넥터를 사용하도록 설정