OT 監視センサーのインベントリ管理 API リファレンス

この記事では、Defender for IoT OT センサーでサポートされているデバイス インベントリ管理 API の一覧を示します。

connections (デバイスの接続情報を取得する)

デバイスのすべての接続の一覧を要求するには、この API を使います。

URI: /api/v1/devices/connections

GET

Request

クエリ パラメーター

返された結果をフィルター処理するには、次のいずれかのクエリ パラメーターを定義します。 クエリ パラメーターを設定しない場合は、すべてのデバイス接続が返されます。

名前	Description	例	必須/省略可能
discoveredBefore	数値。 特定の時刻より前に検出された結果にフィルター処理します。特定の時刻は、エポック時間からのミリ秒数で定義し、UTC タイムゾーンです。	/api/v1/devices/2/connections?discoveredBefore=<epoch>	省略可能
discoveredAfter	数値。 特定の時刻より後に検出された結果にフィルター処理します。特定の時刻は、エポック時間からのミリ秒数で定義し、UTC タイムゾーンです。	/api/v1/devices/2/connections?discoveredAfter=<epoch>	オプション
lastActiveInMinutes	数値。 接続がアクティブだった特定の期間で、結果をフィルター処理します。 現在時刻から過去に遡って定義します (分単位)。	/api/v1/devices/2/connections?lastActiveInMinutes=20	省略可能

Response

応答の種類: JSON

デバイスの接続を表す JSON オブジェクトの配列、または次のエラー メッセージ。

Message	説明
Failure – error	操作に失敗しました

成功した応答のフィールド

名前	Type	Null 許容 / Null 非許容	［値の一覧］
firstDeviceId	数値	NULL 値は許可されません	-
secondDeviceId	数値	NULL 値は許可されません	-
lastSeen	数値	NULL 値は許可されません	エポック (UTC)
discovered	数値	NULL 値は許可されません	エポック (UTC)
ports	数値の配列	Nullable	-
protocols	JSON 配列	Nullable	プロトコル フィールド

プロトコル フィールド

名前	Type	Null 許容 / Null 非許容
name	String	NULL 値は許可されません
commands	文字列配列	Nullable

応答の例

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

cURL コマンド

型: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/connections

例:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/connections

デバイスごとの connections (特定のデバイスの接続情報を取得する)

デバイスごとのすべての接続の一覧を要求するには、この API を使用します。

URI: /api/v1/devices/<deviceID>/connections

GET

Request

パス パラメーター

名前	Description	例	必須/省略可能
deviceId	特定のデバイスの接続を取得します。	/api/v1/devices/<deviceId>/connections	必須

クエリ パラメーター

名前	Description	例	必須/省略可能
discoveredBefore	数値。 特定の時刻より前に検出された結果にフィルター処理します。特定の時刻は、エポック時間からのミリ秒数で定義し、UTC タイムゾーンです。	/api/v1/devices/2/connections?discoveredBefore=<epoch>	省略可能
discoveredAfter	数値。 特定の時刻より後に検出された結果にフィルター処理します。特定の時刻は、エポック時間からのミリ秒数で定義し、UTC タイムゾーンです。	/api/v1/devices/2/connections?discoveredAfter=<epoch>	オプション
lastActiveInMinutes	数値。 接続がアクティブだった特定の期間で、結果をフィルター処理します。 現在時刻から過去に遡って定義します (分単位)。	/api/v1/devices/2/connections?lastActiveInMinutes=20	省略可能

Response

応答の種類: JSON

デバイスの接続を表す JSON オブジェクトの配列、または次のエラー メッセージ。

Message	説明
Failure – error	操作に失敗しました

成功した応答のフィールド

名前	Type	Null 許容 / Null 非許容	［値の一覧］
firstDeviceId	数値	NULL 値は許可されません	-
secondDeviceId	数値	NULL 値は許可されません	-
lastSeen	数値	NULL 値は許可されません	エポック (UTC)
discovered	数値	NULL 値は許可されません	エポック (UTC)
ports	数値の配列	Nullable	-
protocols	JSON 配列	Nullable	プロトコル フィールド

プロトコル フィールド

名前	Type	Null 許容 / Null 非許容
name	String	NULL 値は許可されません
commands	文字列配列	Nullable

応答の例

[
    {
        "firstDeviceId": 171,
        "secondDeviceId": 22,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
        {
            name: "modbus",
            commands: [
                "Read Coils"
            ]
        },
        {
            name: "ams",
            commands: [
                "AMS Write"
            ]
        },
        {
            name: "http",
            commands: [
            ]
        }
    ]
    },
    {
        "firstDeviceId": 171,
        "secondDeviceId": 23,
        "lastSeen": 1511281457933,
        "discovered": 1511872830000,
        "ports": [
            502
        ],
        "protocols": [
            {
                name: "s7comm",
                commands: [
                    "Download block",
                    "Upload"
                ]
            }
        ]
    }
]

cURL コマンド

型: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/<deviceId>/connections?lastActiveInMinutes=&discoveredBefore=&discoveredAfter=

例:

特定のクエリ パラメーターを使用:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/devices/2/connections?lastActiveInMinutes=20&discoveredBefore=1594550986000&discoveredAfter=1594550986000

cves (CVE に関する情報を取得する)

ネットワーク内のデバイスで検出されたすべての既知の CVE の、CVE スコアの降順の一覧を要求するには、この API を使用します。

URI: /api/v1/devices/cves

GET

Request

例: /api/v1/devices/cves

返された結果をフィルター処理するには、次のいずれかのクエリ パラメーターを定義します。

名前	Description	例	必須/省略可能
top	数値。 デバイスの IP アドレスごとに取得する、スコア上位の CVE の数を決定します。	/api/v1/devices/cves?top=50 /api/v1/devices/<ipAddress>/cves?top=50	省略可能。 既定値 = 100

Response

型: JSON

デバイスの CVE オブジェクトの JSON 配列、または次のエラー メッセージ:

Message	説明
Failure – error	操作に失敗しました

成功した応答のフィールド

名前	Type	Null 許容 / Null 非許容	［値の一覧］
cveId	String	NULL 値は許可されません	指定された CVE の正規の業界標準 ID。
ipAddress	String	NULL 値は許可されません	IP アドレス
スコア	String	NULL 値は許可されません	CVE スコア (0.0 - 10.0)
attackVector	String	NULL 値は許可されません	Network、Adjacent Network、Local、または Physical
description	String	NULL 値は許可されません	-

応答の例

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

cURL コマンド

型: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/cves

例:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/cves

IP アドレスごとの cves (CVE に関する特定の情報を取得する)

特定の IP アドレスについて、ネットワーク内のデバイスで検出されたすべての既知の CVE の一覧を要求するには、この API を使います。

URI: /api/v1/devices/cves

GET

Request

例: /api/v1/devices/cves

パス パラメーター

名前	Description	例	必須/省略可能
ipAddress	指定された IP アドレスの CVE を取得します。	/api/v1/devices/<ipAddress>/cves	必須

返された結果をフィルター処理するには、次のクエリ パラメーターを定義します。

名前	Description	例	必須/省略可能
top	数値。 デバイスの IP アドレスごとに取得する、スコア上位の CVE の数を決定します。	/api/v1/devices/cves?top=50 /api/v1/devices/<ipAddress>/cves?top=50	省略可能。 既定値 = 100

Response

型: JSON

デバイスの CVE オブジェクトの JSON 配列、または次のエラー メッセージ:

Message	説明
Failure – error	操作に失敗しました

成功した応答のフィールド

名前	Type	Null 許容 / Null 非許容	［値の一覧］
cveId	String	NULL 値は許可されません	指定された CVE の正規の業界標準 ID。
ipAddress	String	NULL 値は許可されません	IP アドレス
スコア	String	NULL 値は許可されません	CVE スコア (0.0 - 10.0)
attackVector	String	NULL 値は許可されません	Network、Adjacent Network、Local、または Physical
description	String	NULL 値は許可されません	-

応答の例

[
    {

        "cveId": "CVE-2007-0099",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Race condition in the msxml3 module in Microsoft XML Core
        Services 3.0, as used in Internet Explorer 6 and other
        applications, allows remote attackers to execute arbitrary
        code or cause a denial of service (application crash) via many
        nested tags in an XML document in an IFRAME, when synchronous
        document rendering is frequently disrupted with asynchronous
        events, as demonstrated using a JavaScript timer, which can
        trigger NULL pointer dereferences or memory corruption, aka
        \"MSXML Memory Corruption Vulnerability.\""
    },
    {
        "cveId": "CVE-2009-1547",
        "score": "9.3",
        "ipAddress": "10.35.1.51",
        "attackVector": "NETWORK",
        "description": "Unspecified vulnerability in Microsoft Internet Explorer 5.01
        SP4, 6, 6 SP1, and 7 allows remote attackers to execute
        arbitrary code via a crafted data stream header that triggers
        memory corruption, aka \"Data Stream Header Corruption
        Vulnerability.\""
    }
]

cURL コマンド

型: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/api/v1/devices/<deviceIpAddress>/cves?top=

例:

特定のクエリ パラメーターを使用:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/api/v1/devices/10.10.10.15/cves?top=50

devices (デバイスの情報を取得する)

このセンサーによって検出されたすべてのデバイスの一覧を要求するには、この API を使います。

URI: api/v1/devices/

GET

Request

Query parameter (クエリ パラメーター)

返された結果をフィルター処理するには、次のクエリ パラメーターを定義します。 クエリ パラメーターを設定しない場合は、すべてのデバイス接続が返されます。

名前	Description	例	必須/省略可能
承認済み	ブール値: - true: 認可されたデバイスについてのデータのみにフィルター処理します。 - false: 認可されていないデバイスについてのデータのみにフィルター処理します。	/api/v1/devices/	省略可能

Response

応答の種類: JSON

デバイス オブジェクトを表す JSON オブジェクトの配列、または次のエラー メッセージ。

Message	説明
Failure – error	操作に失敗しました

成功した応答のフィールド

名前	Type	Null 許容 / Null 非許容	［値の一覧］
id	数値。 デバイス ID を定義します。	NULL 値は許可されません	-
ipAddresses	文字列の JSON 配列。	Nullable	-
name	文字列 をオンにします。 デバイス名を定義します。	NULL 値は許可されません	-
vendor	文字列 をオンにします。 デバイスのベンダーを定義します。	Nullable	-
operatingSystem	列挙型。 デバイスのオペレーティング システムを定義します。	Nullable	詳しくは、「サポートされている operatingSystem の値」をご覧ください。
macAddresses	文字列の JSON 配列。	Nullable	-
type	文字列 をオンにします。 デバイスの種類を定義します。	NULL 値は許可されません	Unknown の可能性があります。 詳しくは、「サポートされている type の値」をご覧ください。
engineeringStation	Boolean です。 デバイスがエンジニアリング ステーションとして定義されているかどうかを定義します。	NULL 値は許可されません	- true:デバイスはエンジニアリングステーションです - false: デバイスはエンジニアリング ステーションではありません。
承認済み	Boolean です。 デバイスがエンジニアリング ステーションとして定義されているかどうかを定義します。	NULL 値は許可されません	- true:デバイスはエンジニアリングステーションです - false: デバイスはエンジニアリング ステーションではありません
scanner	Boolean です。 デバイスが認可されているかどうかを定義します。	NULL 値は許可されません	- true: デバイスが承認されている - false: デバイスは認可されていません
protocols	デバイスのプロトコルの詳細を含むオブジェクト。	Nullable	詳細については、「Microsoft Defender for IoT - サポート対象 IoT、OT、ICS、SCADA プロトコル」を参照してください。
firmware	デバイスのファームウェアを定義する firmware オブジェクトの JSON 配列。	NULL 値は許可されません	詳しくは、「サポートされている firmware のフィールド」をご覧ください。
hasDynamicAddress	Boolean です。 デバイスに動的アドレスがあるかどうかを定義します。	NULL 値は許可されません	- true: デバイスに動的アドレスがある - false: デバイスには動的アドレスがありません

サポートされている operatingSystem の値

このセクションでは、operatingSystem 応答フィールドでサポートされている値の一覧を示します。

• Windows 10
• Windows 10 32
• Windows 10 64
• Windows 2000
• Windows 7
• Windows 7 32
• Windows 7 64
• Windows 8
• Windows 8 32
• Windows 8 64
• Windows 8.1
• Windows 8.1 32

• Windows 8.1 64
• Windows NT
• Windows Server 2003
• Windows Server 2003 R2
• Windows Server 2008
• Windows Server 2008 32
• Windows Server 2008 64
• Windows Server 2008 R2
• Windows Server 2012
• Windows Server 2012 R2
• Windows Server 2016
• Windows Vista

• Windows Vista 32
• Windows Vista 64
• Windows XP
• Mac OS
• Mac OS X
• Linux
• Windows Server 2019
• HP UX
• Windows 11
• Windows 11 32
• Windows 11 64

サポートされている type の値

このセクションでは、type 応答フィールドでサポートされている値の一覧を示します。

• Engineering Station
• PLC
• Historian
• HMI
• Domain Controller
• DB Server
• Wireless Access Point
• Router
• Switch
• Workstation
• Server
• IP Camera
• Printer
• Multicast/Broadcast
• Internet
• Firewall
• Terminal Station
• VPN Gateway
• Group

• IED
• DCS Controller
• RTU
• NTP Server
• Storage
• Industrial Packaging System
• Industrial Scale
• Industrial Robot
• Slot
• Punch Clock
• ATM
• Smart TV
• Game console
• DVR
• Door Control Panel
• HVAC
• Thermostat
• Fire Alarm
• Smart Light

• Smart Switch
• Fire Detector
• IP Telephone
• Alarm System
• Alarm Siren
• Smart Phone
• Tablet
• Wifi Pineapple
• Motion Detector
• Elevator
• Humidity Sensor
• Physical Location
• Backup Server
• Meter
• Barcode Scanner
• Uninterruptable Power Supply

• Variable Frequency Drive
• Robot Controller
• Servo Drive
• Pneumatic Device
• Marquee
• People Counter System
• Intercom
• Turnstile
• I/O Adapter
• Protocol Converter
• KVM
• Web Guiding System
• Turbine
• External Management
• Embedded Device
• Unknown

protocols オブジェクトとプロトコルの name の値でサポートされているフィールド

このセクションでは、protocols 応答フィールドの protocols オブジェクトでサポートされているフィールドの一覧を示します。

名前	Type	Null 許容 / Null 非許容	［値の一覧］
id	数値。 プロトコルの内部 ID を定義します。	NULL 値は許可されません	-
name	文字列 をオンにします。 デバイス名を定義します。	NULL 値は許可されません	詳細については、以下を参照してください。
ipAddresses	プロトコルの IP アドレスの文字列の JSON 配列。	NULL 値は許可されません	-

次の値は、すぐに使用できるプロトコル名としてサポートされています。

• Unknown
• DNP3
• MODBUS
• C37.118
• SSH
• HTTP
• SYSLOG
• GENERIC
• ICMP
• DNS
• GOOSE
• MMS
• MALFORMED
• IEC-60870
• OPC UA
• Siemens S7
• ARP
• Sampled Values
• EtherNet/IP

• Siemens S7 Plus
• Motorola MDLC
• Netbios Name Service
• Netbios Datagram Service
• Lightweight Access Point
• CAPWAP
• SNMP
• DTLS
• TNS
• Database
• SRTP
• RPC
• OPC
• DF-1
• DH-485
• TDS
• SMB
• Suitelink
• ControlNet

• FTP
• CDP
• Profinet DCP
• Profinet Real-Time
• LLDP
• Telnet
• DeltaV
• BACNet
• AMS
• TwinCAT
• Ovation ADMD
• Ovation SSRPC
• Ovation DPUSTAT
• Port Map
• STP
• Telvent OASyS Tags
• Mitsubishi MELSEC
• Honeywell Control Data Access

• ARP
• Yokogawa HIS Equalize
• Emerson OpenBSI
• Siemens SICAM
• Omron FINS
• Toshiba Computer Link
• Foxboro I/A
• Yokogawa VNet/IP
• Emerson ROC
• ABB Totalflow
• Siemens Process Historian Discovery
• Siemens WinCC Agent
• LonTalk
• Common ASCII Message
• CodeSys
• SAIA S-Bus
• MDNS
• Bently Nevada

サポートされている firmware のフィールド

このセクションでは、firmware 応答フィールドの firmware オブジェクトでサポートされているフィールドの一覧を示します。

名前	Type	Null 許容 / Null 非許容	［値の一覧］
address	文字列 をオンにします。 ファームウェアの IP アドレスを定義します。	NULL 値は許可されません	-
moduleAddress	文字列 をオンにします。 ファームウェアのモジュール アドレスを定義します。	NULL 値は許可されません。	-
serial	文字列 をオンにします。 ファームウェアのシリアル番号を定義します。	Nullable	-
model	文字列 をオンにします。 ファームウェアのモデルを定義します。	Nullable	-
firmwareVersion	文字列 をオンにします。 ファームウェアのバージョンを定義します。	Nullable	-
additionalData	文字列 をオンにします。 ファームウェアの追加データを定義します。	Nullable	-
rack	文字列 をオンにします。 ファームウェアのラックを定義します。	Nullable	-
slot	文字列 をオンにします。 ファームウェアのスロットを定義します。	Nullable	-

cURL コマンド

型: GET

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/devices/'

次のステップ

詳細については、Defender for IoT API リファレンスの概要に関するページを参照してください。