클라우드용 Defender 앱 REST API

아티클
01/23/2024

이 문서에서는 HTTPS를 통해 클라우드용 Defender 앱과 상호 작용하는 방법을 설명합니다.

클라우드용 Microsoft Defender Apps API는 REST API 엔드포인트를 통해 클라우드용 Defender 앱에 프로그래밍 방식으로 액세스할 수 있도록 합니다. 애플리케이션은 API를 사용하여 클라우드용 Defender Apps 데이터 및 개체에 대한 읽기 및 업데이트 작업을 수행할 수 있습니다. 예를 들어 클라우드용 Defender Apps API는 사용자 개체에 대해 다음과 같은 일반적인 작업을 지원합니다.

Cloud Discovery에 대한 로그 파일 업로드
차단 스크립트 생성
활동 및 경고 나열
경고 해제 및 해결

API URL 구조체

클라우드용 Defender Apps API를 사용하려면 먼저 테넌트에서 API URL을 가져와야 합니다. API URL은 다음 형식 https://<portal_url>/api/<endpoint>을 사용합니다.

테넌트에 대한 클라우드용 Defender 앱 API URL을 가져오려면 다음 단계를 수행합니다.

Microsoft Defender 포털에서 설정 선택합니다. 그런 다음, Cloud Apps를 선택합니다. 시스템 아래에서 [정보]를 선택합니다.
화면에 대한 클라우드용 Defender 앱에서 API URL을 볼 수 있습니다.

API URL이 있으면 접미사를 추가하여 /api API URL을 가져옵니다. 예를 들어 포털의 URL이 https://mytenant.us2.contoso.com면 API URL은 다음과 같습니다 https://mytenant.us2.portal.cloudappsecurity.com/api.

API 토큰

클라우드용 Defender 앱에는 다음과 같이 서버에 대한 모든 API 요청의 헤더에 API 토큰이 필요합니다.

Authorization: Token <your_token_key>

개인 API 토큰은 어디에 <your_token_key> 있나요?

API 토큰에 대한 자세한 내용은 API 토큰 관리를 참조 하세요.

API 토큰 - 예제

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"

어떤 작업이 지원되나요?

다음 표에서는 지원되는 작업에 대해 설명합니다.

리소스	HTTP 동사	URI 경로
활동	GET 또는 POST	/api/v1/activities/
경고	GET 또는 POST	/api/v1/alerts/
데이터 보강	GET, POST 또는 DELETE	/api/subnet/
엔터티	GET 또는 POST	/api/v1/entities/
Files	GET 또는 POST	/api/v1/files/

여기서 리소스 는 관련 엔터티 그룹을 나타냅니다.

지원되는 필드 형식은 무엇인가요?

다음 표에서는 지원되는 필드 형식에 대해 설명합니다.

필드	설명
string	텍스트 문자열
부울 값	true/false를 나타내는 부울 값
정수	32비트 부호 있는 정수
timestamp	Epoch 이후 밀리초

타임스탬프

클라우드용 Defender Apps API의 타임스탬프에 대한 언급은 Unix 타임스탬프(밀리초)를 참조합니다. 이 타임스탬프는 1970-01-01 0:00:00 이후의 밀리초 수에 따라 결정됩니다. get-date PowerShell cmdlet을 사용하여 날짜를 타임스탬프로 변환할 수 있습니다.

제한

요청에 제한 매개 변수를 제공하여 요청을 제한하도록 선택할 수 있습니다.

다음 메서드는 limit 매개 변수를 제공하기 위해 지원됩니다.

URL 인코딩(헤더 포함 Content-Type: application/x-www-form-urlencoded )
양식 데이터
JSON 본문( Content-Type: multipart/form-data 적절한 경계 헤더 포함)

참고 항목

제한이 제공되지 않으면 기본값인 100이 설정됩니다.
API 토큰을 사용하여 수행한 모든 요청에 대한 응답은 최대 100개 항목으로 제한됩니다.
모든 API 요청에 대한 제한은 테넌트당 분당 30개 요청입니다.

필터

많은 수의 결과가 있는 경우 필터를 사용하여 요청을 미세 조정하는 것이 유용합니다. 이 섹션에서는 필터와 함께 사용할 수 있는 연산자의 구조와 연산자를 설명합니다.

구조체

일부 API 엔드포인트는 쿼리를 수행할 때 필터를 지원합니다. 관련 섹션에서는 사용 가능한 모든 필터링 가능한 필드와 해당 리소스에 대해 지원되는 연산자를 나열하는 참조를 찾을 수 있습니다.

대부분의 필터는 강력한 쿼리를 제공하기 위해 여러 값을 지원합니다. 필터와 연산자를 결합할 때는 AND를 필터 사이의 논리 연산자로 사용합니다.

필터 - 예제

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
  "filters": {
    "some.field": {
      "eq": ["value1", "value2"],
      "isset": true
    },
    "some.field2": {
      "gte": 5
    }
  },
  "skip": 5,
  "limit": 10
}'

연산자

참고 항목

모든 연산자가 모든 필터와 호환되는 것은 아닙니다.

다음 표에서는 지원되는 연산자를 설명합니다.

연산자	응답 형식	설명
contains	문자열 목록	제공된 문자열 중 하나를 포함하는 모든 관련 레코드를 반환합니다.
deq	값 목록	제공된 값과 같지 않은 값 하나가 포함된 모든 레코드를 반환합니다.
descendantof	값 목록	값 또는 해당 하위 항목과 일치하는 모든 관련 레코드를 반환합니다.
doesnotstartwith	문자열 목록	제공된 각 문자열로 시작되지 않는 모든 관련 레코드를 반환합니다.
endswith	문자열 목록	제공된 문자열 중 하나로 끝나는 모든 관련 레코드를 반환합니다.
eq	값 목록	제공된 값 중 하나를 포함하는 모든 관련 레코드를 반환합니다.
gt	단일 값	값이 제공된 값보다 큰 모든 레코드를 반환합니다.
gte	단일 값	값이 제공된 값보다 크거나 같은 모든 레코드를 반환합니다.
gte_ndays	번호	N일 이후 날짜가 있는 모든 레코드를 반환합니다.
isnotset	부울 값	"true"로 설정하면 지정된 필드에 값이 없는 모든 관련 레코드를 반환합니다.
isset	부울 값	"true"로 설정하면 지정된 필드에 값이 있는 모든 관련 레코드를 반환합니다.
lt	단일 값	값이 제공된 값보다 작은 모든 레코드를 반환합니다.
lte	단일 값	값이 제공된 값보다 작거나 같은 모든 레코드를 반환합니다.
lte_ndays	번호	N일 이전 날짜의 모든 레코드를 반환합니다.
ncontains	문자열 목록	제공된 문자열 중 하나를 포함하지 않는 모든 관련 레코드를 반환합니다.
ndescendantof	값 목록	값 또는 하위 항목과 일치하지 않는 모든 관련 레코드를 반환합니다.
neq	값 목록	제공된 모든 값을 포함하지 않는 모든 관련 레코드를 반환합니다.
range	"start" 및 "end" 필드가 포함된 개체 목록	제공된 범위 중 하나 내의 모든 레코드를 반환합니다.
startswith	문자열 목록	제공된 문자열 중 하나로 시작하는 모든 관련 레코드를 반환합니다.
startswithsingle	string	제공된 문자열로 시작하는 모든 관련 레코드를 반환합니다.
text	string	모든 레코드의 전체 텍스트 검색 수행

다음 단계

API 인증

문제가 발생하면 도움을 받으세요. 제품 문제에 대한 지원 또는 지원을 받으려면 지원 티켓을 여세요.