デバイスごとのセキュリティで保護された構成評価をエクスポートする

[アーティクル]
04/26/2024

適用対象:

Microsoft Defender ATP を試してみたいですか? 無料試用版にサインアップしてください。

デバイスごとに、すべての構成とその状態を返します。

さまざまな種類のデータを取得するためのさまざまな API 呼び出しがあります。データの量は大きくなる可能性があるため、取得する方法は 2 つあります。

セキュリティで保護された構成評価 JSON 応答をエクスポートする: API は、organization内のすべてのデータを Json 応答としてプルします。この方法は、 100 K 未満のデバイスを持つ小規模な組織に最適です。応答はページ分割されるため、応答の@odata.nextLink フィールドを使用して、次の結果をフェッチできます。
ファイルを使用してセキュリティで保護された構成評価をエクスポートする: この API ソリューションを使用すると、大量のデータをより迅速かつ確実にプルできます。そのため、100 K を超えるデバイスを持つ大規模な組織に推奨されます。この API は、組織内のすべてのデータをダウンロードファイルとしてプルします。応答には、Azure Storage からすべてのデータをダウンロードするための URL が含まれています。この API を使用すると、次のように Azure Storage からすべてのデータをダウンロードできます:
- すべての組織データを含むダウンロード URL の一覧を取得するには、API を呼び出します。
- ダウンロード URL を使用してすべてのファイルをダウンロードし、データを好きなように処理します。

収集されたデータ (JSON 応答またはファイル経由) は現在の状態の現在のスナップショットであり、履歴データは含まれません。履歴データを収集するには、データを独自のデータストレージに保存する必要があります。

注:

特に明記されていない限り、一覧表示されているすべてのエクスポート評価方法は 、完全なエクスポート と デバイス別 ( デバイス別とも呼ばれます) です。

1. セキュリティで保護された構成評価 (JSON 応答) をエクスポートする

1.1 API メソッドの説明

この API 応答には、公開されているデバイスのセキュリティで保護された構成評価が含まれており、DeviceId、ConfigurationId の一意の組み合わせごとにエントリが返されます。

1.1.1 制限事項

最大ページサイズは 200,000 です。
この API のレート制限は、1 分あたり 30 呼び出しと 1 時間あたり 1000 呼び出しです。

1.2 アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法など、詳細については、「エンドポイント API に Microsoft Defender を使用する」を参照してください。

アクセス許可の種類	アクセス許可	アクセス許可の表示名
アプリケーション	Vulnerability.Read.All	'脅威と脆弱性管理の脆弱性情報の読み取り'
委任 (職場または学校のアカウント)	Vulnerability.Read	'脅威と脆弱性管理の脆弱性情報の読み取り'

1.3 URL

GET /api/machines/SecureConfigurationsAssessmentByMachine

1.4 パラメーター

pageSize (既定値 = 50,000): 応答の結果の数。
$top: 返す結果の数 (@odata.nextLink は返されないため、すべてのデータをプルするわけではありません)。

1.5 プロパティ

注:

次のテーブルで定義されているプロパティは、プロパティ ID でアルファベット順にリスト表示されます。この API を実行する場合、結果の出力は必ずしもこのテーブルにリストされているのと同じ順序で返されるとは限りません。
応答で追加の列が返される場合があります。これらの列は一時的なものであり、削除される可能性があります。ドキュメント化された列のみを使用してください。

プロパティ (ID)	データ型	説明	戻り値の例
ConfigurationCategory	string	構成が属するカテゴリまたはグループ: アプリケーション、OS、ネットワーク、アカウント、セキュリティ制御	セキュリティコントロール
ConfigurationId	string	特定の構成の一意の識別子	scid-10000
ConfigurationImpact	string	構成が全体の構成スコアに与える影響の評価 (1-10)	9
ConfigurationName	string	構成の表示名	デバイスを Microsoft Defender for Endpoint にオンボードする
ConfigurationSubcategory	文字列	構成が属するサブカテゴリまたはサブグループ。多くの場合、これは特定の機能または機能を説明します。	デバイスのオンボード
DeviceId	文字列	サービス内のデバイスの一意の識別子。	9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName	string	デバイスの完全修飾ドメイン名 (FQDN)。	johnlaptop.europe.contoso.com
IsApplicable	bool	構成またはポリシーが適用されるかどうかを示します	true
IsCompliant	bool	構成やポリシーが正しく構成されているかどうかを示します	false
IsExpectedUserImpact	bool	構成が適用される場合にユーザーへの影響があるかどうかを示します	true
OSPlatform	string	デバイスで実行されているオペレーティングシステムのプラットフォーム。これは、Windows 10やWindows 11など、同じファミリ内のバリエーションを含む特定のオペレーティングシステムを示します。詳細については、「Microsoft Defender 脆弱性の管理 (MDVM) でサポートされているオペレーティングシステムとプラットフォーム」を参照してください。	Windows10 とWindows 11
RbacGroupName	string	ロールベースのアクセス制御 (RBAC) グループ。このデバイスが RBAC グループに割り当てられていない場合、値は "未割り当て" になります。organizationに RBAC グループが含まれていない場合、値は "None" になります。	サーバー
RecommendationReference	string	このソフトウェアに関連する推奨事項 ID への参照。	sca-_-scid-20000
Timestamp	string	デバイスで構成が最後に表示された時刻	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 メソッドの説明

2.1.1 制限事項

この API のレート制限は、1 分あたり 5 回の呼び出しと 1 時間あたり 20 回の呼び出しです。

2.2 権限

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法など、詳細については、「Microsoft Defender for Endpoint API を使用する」を参照してください。

アクセス許可の種類	アクセス許可	アクセス許可の表示名
アプリケーション	Vulnerability.Read.All	'脅威と脆弱性管理の脆弱性情報の読み取り'
委任 (職場または学校のアカウント)	Vulnerability.Read	'脅威と脆弱性管理の脆弱性情報の読み取り'

2.3 URL

GET /api/machines/SecureConfigurationsAssessmentExport

パラメーター

sasValidHours: ダウンロード URL が有効になる時間数 (最大 24 時間)。

2.5 プロパティ

注:

ファイルは、複数行の JSON 形式の gzip 圧縮されています。
ダウンロード URL は 3 時間だけ有効です。それ以外の場合は、パラメーターを使用できます。
データの最大ダウンロード速度を得るために、データが存在するのと同じ Azure リージョンからダウンロードしていることを確認できます。

プロパティ (ID)	データ型	説明	戻り値の例
ファイルをエクスポートする	array[string]	organizationの現在のスナップショットを保持しているファイルのダウンロード 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"
}

次の方法で共有