다음을 통해 공유

검사 정의 추가, 업데이트 또는 삭제

  • 아티클

적용 대상:

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

Microsoft Defender 취약성 관리 경험하고 싶으신가요? Microsoft Defender 취약성 관리 공개 미리 보기 평가판에 등록하는 방법에 대해 자세히 알아보세요.

중요

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

참고

미국 정부 고객인 경우 미국 정부 고객을 위해 엔드포인트용 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
  • ina.api.security.microsoft.com

API 설명

인증된 검사를 추가, 업데이트 또는 삭제하는 API입니다.

제한 사항

이 API의 속도 제한은 분당 100개의 호출과 시간당 1,500건의 호출입니다.

구성된 보존 기간에 따라 마지막으로 본 컴퓨터에 게시할 수 있습니다.

권한

이 API를 호출하려면 다음 권한 중 하나가 필요합니다. 사용 권한을 선택하는 방법을 포함하여 자세한 내용은 엔드포인트용 Defender API 사용을 참조하세요.

사용 권한 유형 사용 권한 사용 권한 표시 이름
응용 프로그램 Machine.ReadWrite.All 모든 검사 정보를 읽고 씁니다.
위임됨(회사 또는 학교 계정) Machine.Read.Write 모든 검사 정보를 읽고 씁니다.

사용자 자격 증명을 사용하여 토큰을 가져오는 경우:

  • 데이터를 보려면 사용자에게 최소한 다음 역할 권한이 ViewData 있어야 합니다. 또는 TvmViewData ( 역할 만들기 및 관리 참조)
  • 데이터를 편집하려면 사용자에게 적어도 다음 역할 권한이 ManageSecurity 있어야 합니다. ( 역할 만들기 및 관리 참조)

HTTP 요청

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

요청 헤더

이름 유형 설명
권한 부여 String 전달자 {token}. 필수입니다.
Content-Type 문자열 application/json. 필수입니다.

요청 본문

요청 본문에서 JSON 개체에 다음 매개 변수를 제공합니다.

매개 변수 형식 설명
scanType 열거형 검사 유형입니다. 가능한 값은 "Windows", "Network"입니다. 필수입니다.
scanName String 검사의 이름입니다. 필수입니다.
isActive 부울 검사가 능동적으로 실행되는지 여부의 상태입니다. 필수입니다.
target String 검사할 대상의 쉼표로 구분된 목록(IP 주소 또는 호스트 이름)입니다. 필수입니다.
intervalInHours 임계값 검사가 실행되는 간격입니다. 필수입니다.
targetType String 대상 필드의 대상 형식입니다. 가능한 형식은 "IP 주소" 또는 "호스트 이름"입니다. 기본값은 IP 주소입니다. 필수입니다.
scannerAgent 개체 컴퓨터 ID. 필수입니다.
scanAuthenticationParams 개체 인증 매개 변수를 나타내는 개체는 예상 필드에 대한 인증 매개 변수 개체 속성을 참조하세요. 이 속성은 새 검사를 만들 때 필수이며 검사를 업데이트할 때 선택 사항입니다.

응답

성공하면 이 메서드는 응답 본문에 200 - Ok 응답 코드 및 새 검사 또는 업데이트된 검사 정의를 반환합니다.

새 검사를 추가하기 위한 요청 예제

다음은 새 검사를 추가하는 요청의 예입니다.

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

 {
"scanType": "Windows", 
"scanName": "Test Windows scan", 
"isActive": true, 
"target": "127.0.0.1", 
"intervalInHours": 1, 
"targetType": "Ip",
"scannerAgent": {
    "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
},
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
}

응답 예제

다음은 응답의 예입니다.

 {
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Windows scan",
    "isActive": true,
    "target": "127.0.0.1",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "username@test.com",
    "targetType": "Ip",
    "scanAuthenticationParams": null,
    "scannerAgent": {
        "id": "0335a792-18d2-424b-aeed-559567054570_ eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineName": "DESKTOP-TEST",
        "lastSeen": "2023-01-04T09:40:03.2787058Z",
        "assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
        "scannerSoftwareVersion": "7.6.0.0",
        "lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
        "mdeClientVersion": "10.8295.22621.1010"
    },
    "latestScan": {
        "status": null,
        "failureReason": null,
        "executionDateTime": null
    }

}

검사 업데이트 요청 예제

다음은 검사를 업데이트하는 요청의 예입니다.

PATCH  https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/289224fb-1686-472c-9751-5555960854ca 

{
"scanName": "Test Update Windows scan", 
"isActive": false, 
"target": "127.0.0.2,127.0.0.3", 
"intervalInHours": 1, 
"targetType": "Ip",
"scanAuthenticationParams": { 
    "@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams", 
    "type": "Kerberos", 
    "username": "username", 
    "domain": "password",
    "isGmsaUser": true
    }
 }

응답 예제

다음은 응답의 예입니다.

{
    "@odata.context": "https://localhost:1059/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
    "id": "289224fb-1686-472c-9751-5555960854ca",
    "scanType": "Windows",
    "scanName": "Test Update Windows scan",
    "isActive": false,
    "target": "127.0.0.2,127.0.0.3",
    "orgId": "0335a792-18d2-424b-aeed-559567054570",
    "intervalInHours": 1,
    "createdBy": "userName@microsoft.com",
    "targetType": "Ip",
    "scanAuthenticationParams": null,
    "scannerAgent": {
        "id": "0335a792-18d2-424b-aeed-559567054570_eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
        "machineName": "DESKTOP-TEST",
        "lastSeen": "2023-01-04T09:40:03.2787058Z",
        "assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
        "scannerSoftwareVersion": "7.6.0.0",
        "lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
        "mdeClientVersion": "10.8295.22621.1010"
    },
    "latestScan": {
        "status": null,
        "failureReason": null,
        "executionDateTime": null
    }
}

검사 삭제 요청 예제

다음은 검사를 삭제하는 요청의 예입니다.

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/BatchDelete

{
  "ScanDefinitionIds": ["td32f17af-5cc2-4e4e-964a-4c4ef7d216e2", "ab32g20af-5dd2-4a5e-954a-4c4ef7d216e2"],
}

팁

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