匯出每個裝置的安全設定評估

  • 發行項

適用於：

想要體驗適用於端點的 Microsoft Defender 嗎？ 注册免費試用版。

根據每個裝置傳回所有組態及其狀態。

有不同的 API 呼叫可取得不同類型的數據。 因為數據量可能很大，所以有兩種方式可以擷取：

  • 匯出安全設定評估 JSON 回應：API 會將組織中的所有數據提取為 JSON 回應。 此方法最適合 裝置少於 100 K 的小型組織。 回應會進行分頁，因此您可以使用回應中的 @odata.nextLink 欄位來擷取下一個結果。

  • 透過檔案匯出安全的組態評估：此 API 解決方案可讓您更快速且更可靠地提取大量數據。 因此，建議大型組織使用超過100 K的裝置。 此 API 會將組織中的所有資料提取為下載檔。 回應包含可從 Azure 記憶體下載所有數據的 URL。 此 API 可讓您從 Azure 記憶體下載所有資料，如下所示：

    • 呼叫 API 以取得包含您所有組織資料的下載 URL 清單。

    • 使用下載 URL 下載所有檔案，並視需要處理數據。

使用 JSON 回應 或 透過檔案 收集 (的數據) 是目前狀態的目前快照集，不包含歷史數據。 若要收集歷史數據，客戶必須將數據儲存在自己的數據記憶體中。

注意事項

除非另有指示，否則列出的所有導出評估方法都是 完整匯 出，而 裝置 (也稱為 每個裝置) 。

1.導出安全設定評估 (JSON 回應)

1.1 API 方法描述

此 API 回應包含公開裝置上的安全組態評估，並傳回 DeviceId、 ConfigurationId 之每個唯一組合的專案。

1.1.1 限制

  • 頁面大小上限為 200,000。

  • 此 API 的速率限制為每分鐘 30 次呼叫，每小時 1000 次呼叫。

1.2 許可權

呼叫此 API 需要下列其中一個許可權。 若要深入瞭解，包括如何選擇許可權，請參閱使用 適用於端點的 Microsoft Defender API 以取得詳細數據。

許可權類型 權限 許可權顯示名稱
應用程式 Vulnerability.Read.All 「讀取威脅和弱點管理弱點資訊」
委派 (公司或學校帳戶) Vulnerability.Read 「讀取威脅和弱點管理弱點資訊」

1.3 URL

GET /api/machines/SecureConfigurationsAssessmentByMachine

1.4 參數

  • pageSize (預設值 = 50,000) ：回應中的結果數目。
  • $top：傳回 (的結果數目不會傳回 @odata.nextLink，因此不會將所有數據提取) 。

1.5 屬性

注意事項

  • 下表中定義的屬性會依字母順序依屬性標識碼列出。 執行此 API 時，產生的輸出不一定會以此數據表所列的相同順序傳回。
  • 回應中可能會傳回一些額外的數據行。 這些數據行是暫時性的，而且可能會被移除，請只使用記載的數據行。

屬性 (識別碼) 資料類型 描述 傳回值的範例
ConfigurationCategory 字串 設定所屬的類別或群組：應用程式、作業系統、網路、帳戶、安全性控制 安全性控制項
ConfigurationId 字串 特定設定的唯一識別碼 scid-10000
ConfigurationImpact 字串 設定對整個設定分數 (1-10) 的評分影響 9
ConfigurationName 字串 組態的顯示名稱 將裝置上線至適用於端點的 Microsoft Defender
ConfigurationSubcategory 字串 設定所屬的子類別或子群組。 在許多情況下，這會描述特定性能或功能。 將裝置上線
DeviceId 字串 服務中裝置的唯一標識符。 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName 字串 裝置的 FQDN) (完整功能變數名稱。 johnlaptop.europe.contoso.com
IsApplicable bool 指出組態或原則是否適用 真
IsCompliant bool 指出設定或原則是否已正確設定 假
IsExpectedUserImpact bool 指出如果套用設定，是否會影響使用者 真
OSPlatform 字串 在裝置上執行之作業系統的平臺。 這表示特定的操作系統，包括相同系列內的變化，例如 Windows 10 和 Windows 11。 如需詳細資訊，請參閱 Microsoft Defender 弱點管理 (MDVM) 支援的操作系統和平臺。 Windows 10 和 Windows 11
RbacGroupName 字串 角色型訪問控制 (RBAC) 群組。 如果未將此裝置指派給任何 RBAC 群組，則值會是 “Unassigned”。如果組織不包含任何 RBAC 群組，則值會是 「None」。 伺服器
RecommendationReference 字串 與此軟體相關的建議標識碼參考。 sca-_-scid-20000
時間戳記 字串 上次在裝置上看到設定的時間 2020-11-03 10:13:34.8476880

1.6 範例

1.6.1 要求範例

GET https://api.securitycenter.microsoft.com/api/machines/SecureConfigurationsAssessmentByMachine?pageSize=5

1.6.2 回應範例

{
    "@odata.context": "api.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.AssetConfiguration)",
    "value": [
        {
            "deviceId": "00013ee62c6b12345b10214e1801b217b50ab455c293d",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_5d96860d69c73fdd06fc8d1679e1eb73eceb8330",
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "NT kernel 6.x",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-10000",
            "configurationCategory": "Network",
            "configurationSubcategory": "",
            "configurationImpact": 5,
            "isCompliant": true,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Disable insecure administration protocol - Telnet",
            "recommendationReference": "sca-_-scid-10000"
        },
        {
            "deviceId": "0002a1be533813b9a8c6de739785365bce7910",
            "rbacGroupName": "hhh",
            "deviceName": null,
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-20000",
            "configurationCategory": "Security controls",
            "configurationSubcategory": "Onboard Devices",
            "configurationImpact": 9,
            "isCompliant": false,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Onboard devices to Microsoft Defender for Endpoint",
            "recommendationReference": "sca-_-scid-20000"
        },
        {
            "deviceId": "0002a1de123456a8c06de736785395d4ce7610",
            "rbacGroupName": "hhh",
            "deviceName": null,
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-10000",
            "configurationCategory": "Network",
            "configurationSubcategory": "",
            "configurationImpact": 5,
            "isCompliant": true,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Disable insecure administration protocol - Telnet",
            "recommendationReference": "sca-_-scid-10000"
        },
        {
            "deviceId": "00044f912345bdaf756492dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18663d45912eed224b2be2f5ea3142726e63f16a.DomainPII_21eeb80b086e76bdfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0.17763.1637",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-39",
            "configurationCategory": "OS",
            "configurationSubcategory": "",
            "configurationImpact": 5,
            "isCompliant": true,
            "isApplicable": true,
            "isExpectedUserImpact": false,
            "configurationName": "Enable 'Domain member: Digitally sign secure channel data (when possible)'",
            "recommendationReference": "sca-_-scid-39"
        },
        {
            "deviceId": "00044f912345daf759462bde6bd733d6a9c56ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18663b45612eeb224d2de2f5ea3142726e63f16a.DomainPII_21eed80d086e76dbfa178eadfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "osVersion": "10.0.17763.1637",
            "timestamp": "2021-01-11 09:47:58.854",
            "configurationId": "scid-6093",
            "configurationCategory": "Security controls",
            "configurationSubcategory": "Antivirus",
            "configurationImpact": 5,
            "isCompliant": false,
            "isApplicable": false,
            "isExpectedUserImpact": false,
            "configurationName": "Enable Microsoft Defender Antivirus real-time behavior monitoring for Linux",
            "recommendationReference": "sca-_-scid-6093"
        }
    ],
    "@odata.nextLink": "https://api.securitycenter.microsoft.com/api/machines/SecureConfigurationsAssessmentByMachine?pagesize=5&$skiptoken=eyJFeHBvcnREZWZpbml0aW9uIjp7IlRpbWVQYXRoIjoiMjAyMS0wMS0xMS8xMTAxLyJ9LCJFeHBvcnRGaWxlSW5kZXgiOjAsIkxpbmVTdG9wcGVkQXQiOjV9"
}

2.透過檔案導出安全組態評估 ()

2.1 API 方法描述

此 API 回應包含公開裝置上的安全組態評估，並傳回 DeviceId、 ConfigurationId 之每個唯一組合的專案。

2.1.1 限制

此 API 的速率限制為每分鐘 5 次呼叫，每小時 20 次呼叫。

2.2 許可權

呼叫此 API 需要下列其中一個許可權。 若要深入瞭解，包括如何選擇許可權，請參閱使用 適用於端點的 Microsoft Defender API 以取得詳細數據。

許可權類型 權限 許可權顯示名稱
應用程式 Vulnerability.Read.All 「讀取威脅和弱點管理弱點資訊」
委派 (公司或學校帳戶) Vulnerability.Read 「讀取威脅和弱點管理弱點資訊」

2.3 URL

GET /api/machines/SecureConfigurationsAssessmentExport

參數

  • sasValidHours：下載 URL 的有效時數 () 最多 24 小時。

2.5 屬性

注意事項

  • 檔案是以多行 JSON 格式壓縮 &。
  • 下載 URL 的有效期只有 3 小時;否則，您可以使用 參數。
  • 如需數據的最大下載速度，您可以確定您是從數據所在的相同 Azure 區域下載。

屬性 (識別碼) 資料類型 描述 傳回值的範例
匯出檔案 array[string] 保存組織目前快照集之檔案的下載 URL 清單 ["Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime 字串 產生匯出的時間。 2021-05-20T08：00：00Z

2.6 範例

2.6.1 要求範例

GET https://api.securitycenter.microsoft.com/api/machines/SecureConfigurationsAssessmentExport

2.6.2 回應範例

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#contoso.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/ScaExport/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00393-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/ScaExport/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/ScaExport/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c001.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=..."
    ],
    "generatedTime": "2021-01-11T11:01:00Z"
}

另請參閱

其他相關

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：適用於端點的 Microsoft Defender 技術社群。