デバイスごとにハードウェアとファームウェアの評価インベントリをエクスポートする

適用対象:

• Microsoft Defender for Endpoint Plan 1
• Microsoft Defender for Endpoint Plan 2
• Microsoft Defender 脆弱性の管理
• Microsoft Defender XDR

Microsoft Defender 脆弱性の管理を体験するには Microsoft Defender 脆弱性の管理パブリック プレビュー試用版にサインアップする方法について説明します。

さまざまな種類のデータを取得するためのさまざまな API 呼び出しがあります。 一般に、各 API 呼び出しには、organization内のデバイスに必要なデータが含まれています。

• JSON 応答API は、organization内のすべてのデータを JSON 応答としてプルします。 この方法は、 100 K 未満のデバイスを持つ小規模な組織に最適です。 応答はページ分割されるため、応答の@odata.nextLink フィールドを使用して、次の結果をフェッチできます。

• ファイル経由 この API ソリューションを使用すると、大量のデータをより迅速かつ確実にプルできます。 そのため、100 K を超えるデバイスを持つ大規模な組織におすすめです。 この API は、組織内のすべてのデータをダウンロード ファイルとしてプルします。 応答には、Azure Storage からすべてのデータをダウンロードするための URL が含まれています。 Azure Storage から次のようにデータをダウンロードできます。

  • すべての組織データを含むダウンロード URL の一覧を取得するには、API を呼び出します。
  • ダウンロード URL を使用してすべてのファイルをダウンロードし、データを好きなように処理します。

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

注:

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

1. ハードウェアとファームウェアの評価をエクスポートする (JSON 応答)

1.1 API メソッドの説明

デバイスごとに、すべてのデバイスのすべてのハードウェアとファームウェアの評価を返します。 deviceId と componentType の一意の組み合わせごとに、個別のエントリを持つテーブルが返されます。

1.1.1 制限事項

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

1.2 アクセス許可

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

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

1.3 URL

GET api/machines/HardwareFirmwareInventoryByMachine

1.4 パラメーター

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

1.5 プロパティ (JSON 応答)

注:

各レコードは約 1 KB のデータです。 正しい pageSize パラメーターを選択するときは、これを考慮する必要があります。

応答で追加の列が返される場合があります。 これらの列は一時的なもので、削除される可能性があります。 ドキュメント化された列のみを使用します。

次の表で定義されているプロパティは、プロパティ ID でアルファベット順に一覧表示されます。 この API を実行する場合、結果の出力は必ずしもこのテーブルにリストされているのと同じ順序で返されるとは限りません。

プロパティ (ID)	データ型	説明
deviceId	String	サービス内のデバイスの一意の識別子。
rbacGroupId	Int	ロールベースのアクセス制御 (RBAC) グループ ID。デバイスが RBAC グループに割り当てられていない場合、値は "未割り当て" になります。organizationに RBAC グループが含まれていない場合、値は "None" になります。
rbacGroupName	String	ロールベースのアクセス制御 (RBAC) グループ。 デバイスが RBAC グループに割り当てられていない場合、値は "未割り当て" になります。organizationに RBAC グループが含まれていない場合、値は "None" になります。
deviceName	String	デバイスの完全修飾ドメイン名 (FQDN)。
componentType	String	ハードウェアまたはファームウェア コンポーネントの種類。
manufacturer	String	特定のハードウェアまたはファームウェア コンポーネントの製造元。
componentName	String	特定のハードウェアまたはファームウェア コンポーネントの名前。
componentVersion	String	特定のハードウェアまたはファームウェア コンポーネントのバージョン。
additionalFields	String	JSON 配列形式のコンポーネントに関する追加情報。

1.6 例

1.6.1 要求の例

GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryByMachine

1.6.2 応答の例

      {
        "@odata.context": "https://api-df.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.AssetHardwareFirmware)",
        "value":[
        {
            "deviceId": "49126b9e4a5473b5229c73799e9e55c48668101b",
            "rbacGroupId": 39,
            "rbacGroupName": "testO6343398Gq31",
            "deviceName": "testmachine5",
            "componentType": "Hardware",
            "manufacturer": "razer",
            "componentName": "blade_15_advanced_model_(mid_2021)_-_rz09-0409",
            "componentVersion": "7.04",
            "additionalFields": "{\"SystemSKU\":\"RZ09-0409CE53\",\"BaseBoardManufacturer\":\"Razer\",\"BaseBoardProduct\":\"CH570\",\"BaseBoardVersion\":\"4\",\"DeviceFamily\":\"Workstation\"}"
          }  
        ]  
      },
    

2. ハードウェアとファームウェアの評価をエクスポートする (ファイル経由)

2.1 API メソッドの説明

デバイスごとに、すべてのデバイスのすべてのハードウェアとファームウェアの評価を返します。 DeviceId、ComponentType、ComponentName の一意の組み合わせごとに、個別のエントリを持つテーブルが返されます。

2.1.1 制限事項

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

2.2 権限

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

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

2.3 URL

GET /api/machines/HardwareFirmwareInventoryExport

2.4 パラメーター

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

2.5 プロパティ (JSON 応答)

注:

ファイルは、複数行の JSON 形式の gzip 圧縮されています。

ダウンロード URL は 3 時間のみ有効です。それ以外の場合は、 パラメーターを使用できます。

ダウンロード速度を最大化するには、データが存在するのと同じ Azure リージョンからデータをダウンロードしていることを確認します。

各レコードは約 1 KB のデータです。 これは、自分に合った pageSize パラメーターを選択するときに考慮する必要があります。

応答で追加の列が返される場合があります。 これらの列は一時的なもので、削除される可能性があります。 ドキュメント化された列のみを使用します。

プロパティ (ID)	データ型	説明
ファイルをエクスポートする	String[array]	組織の現在のスナップショットを保持しているファイルのダウンロード URL のリスト。
GeneratedTime	DateTime	エクスポートが生成された時刻。

2.6 例

2.6.1 要求の例

GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryExport

2.6.2 応答の例

    {
        "@odata.context":"https://api-df.securitycenter.microsoft.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=39/part-00999-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=muN8Sq6rVN6bFMtR0u3S5Wzh3D9qNPgN5vpU7lWvULg%3D",
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00968-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=%2BA0%2B4qOOBCS5E4UenJPbMdLM%2FkbXHnz%2F1pvfSOCq%2F2s%3D",
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00969-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=sZUgYMwSr5zk6BZvS%2BoYIWlHJWk2oJ7YjiC8R26S1X4%3D"
    ],
    "generatedTime": "2022-07-11T11:01:00Z"

   }