OT 모니터링 센서에 대한 인벤토리 관리 API 참조

아티클
12/18/2023

이 문서에서는 Defender for IoT OT 센서를 지원하는 디바이스 인벤토리 관리 API를 나열합니다.

connections(디바이스 연결 정보 검색)

이 API를 사용하여 모든 디바이스 연결 목록을 요청합니다.

URI: /api/v1/devices/connections

GET

쿼리 매개 변수

다음 쿼리 매개 변수를 정의하여 반환된 결과를 필터링합니다. 쿼리 매개 변수를 설정하지 않으면 모든 디바이스 연결이 반환됩니다.

이름	설명	예시	필수/선택 사항
discoveredBefore	숫자. 지정된 시간 이전에 검색된 결과를 필터링합니다. 여기서 지정된 시간은 Epoch 시간 및 UTC 표준 시간대에서 밀리초 단위로 정의됩니다.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	선택 사항
discoveredAfter	숫자. 지정된 시간 이후에 검색된 결과를 필터링합니다. 여기서 지정된 시간은 Epoch 시간 및 UTC 표준 시간대에서 밀리초 단위로 정의됩니다.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	선택 사항
lastActiveInMinutes	숫자. 연결이 활성화된 동안 지정된 시간 프레임을 기준으로 결과를 필터링합니다. 현재 시간에서 역방향(분)으로 정의됩니다.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	선택 사항

응답 형식: JSON

디바이스 연결을 나타내는 JSON 개체의 배열 또는 다음 오류 메시지:

메시지	설명
실패 – 오류	작업 실패

성공 응답 필드

이름	Type	null 허용/null 허용 안 함	값 목록
firstDeviceId	숫자	nullable이 아님	-
secondDeviceId	숫자	nullable이 아님	-
lastSeen	숫자	nullable이 아님	Epoch (UTC)
발견	숫자	nullable이 아님	Epoch (UTC)
포트	숫자 배열	Nullable	-
프로토콜	JSON 배열	Nullable	프로토콜 필드

프로토콜 필드

이름	Type	null 허용/null 허용 안 함
이름	문자열	nullable이 아님
명령	문자열 ARRAY	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"
                ]
            }
        ]
    }
]

형식: GET

APIs:

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

디바이스당 연결(특정 디바이스 연결 정보 검색)

이 API를 사용하여 디바이스당 모든 연결 목록을 요청합니다.

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

GET

경로 매개 변수

이름	설명	예시	필수/선택 사항
deviceId	지정된 디바이스에 대한 연결을 가져옵니다.	`/api/v1/devices/<deviceId>/connections`	Required

쿼리 매개 변수

이름	설명	예시	필수/선택 사항
discoveredBefore	숫자. 지정된 시간 이전에 검색된 결과를 필터링합니다. 여기서 지정된 시간은 Epoch 시간 및 UTC 표준 시간대에서 밀리초 단위로 정의됩니다.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	선택 사항
discoveredAfter	숫자. 지정된 시간 이후에 검색된 결과를 필터링합니다. 여기서 지정된 시간은 Epoch 시간 및 UTC 표준 시간대에서 밀리초 단위로 정의됩니다.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	선택 사항
lastActiveInMinutes	숫자. 연결이 활성화된 동안 지정된 시간 프레임을 기준으로 결과를 필터링합니다. 현재 시간에서 역방향(분)으로 정의됩니다.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	선택 사항

응답 형식: JSON

디바이스 연결을 나타내는 JSON 개체의 배열 또는 다음 오류 메시지:

메시지	설명
실패 – 오류	작업 실패

성공 응답 필드

이름	Type	null 허용/null 허용 안 함	값 목록
firstDeviceId	숫자	nullable이 아님	-
secondDeviceId	숫자	nullable이 아님	-
lastSeen	숫자	nullable이 아님	Epoch (UTC)
발견	숫자	nullable이 아님	Epoch (UTC)
포트	숫자 배열	Nullable	-
프로토콜	JSON 배열	Nullable	프로토콜 필드

프로토콜 필드

이름	Type	null 허용/null 허용 안 함
이름	문자열	nullable이 아님
명령	문자열 ARRAY	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"
                ]
            }
        ]
    }
]

형식: GET

APIs:

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에 대한 정보 검색)

이 API를 사용하여 네트워크의 디바이스에서 발견된 모든 알려진 CVE 목록을 요청합니다.

URI: /api/v1/devices/cves

GET

예: /api/v1/devices/cves

다음 쿼리 매개 변수를 정의하여 반환된 결과를 필터링합니다.

이름	설명	예시	필수/선택 사항
top	숫자. 각 디바이스 IP 주소에 대해 가져올 상위 점수가 매겨진 CVE의 수를 정의합니다.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	선택 사항. 기본값 = `100`

형식: JSON

디바이스 CVE 개체의 JSON 배열 또는 다음 오류 메시지:

메시지	설명
실패 – 오류	작업 실패

성공 응답 필드

이름	Type	null 허용/null 허용 안 함	값 목록
cveId	문자열	nullable이 아님	지정된 CVE에 대한 정식 산업 표준 ID입니다.
Ipaddress	문자열	nullable이 아님	IP 주소
점수	문자열	nullable이 아님	0.0~10.0 사이의 CVE 점수
attackVector	문자열	nullable이 아님	`Network`, `Adjacent Network`, `Local` 또는 `Physical`
description	문자열	nullable이 아님	-

응답 예제

[
    {

        "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.\""
    }
]

형식: GET

APIs:

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 주소당 CVE(CVE에 대한 특정 정보 검색)

이 API를 사용하여 특정 IP 주소에 대해 네트워크의 디바이스에서 발견된 모든 알려진 CVE 목록을 요청합니다.

URI: /api/v1/devices/cves

GET

예: /api/v1/devices/cves

경로 매개 변수

이름	설명	예시	필수/선택 사항
Ipaddress	지정된 IP 주소에 대한 CVE를 가져옵니다.	`/api/v1/devices/<ipAddress>/cves`	Required

다음 쿼리 매개 변수를 정의하여 반환된 결과를 필터링합니다.

이름	설명	예시	필수/선택 사항
top	숫자. 각 디바이스 IP 주소에 대해 가져올 상위 점수가 매겨진 CVE의 수를 정의합니다.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	선택 사항. 기본값 = `100`

형식: JSON

디바이스 CVE 개체의 JSON 배열 또는 다음 오류 메시지:

메시지	설명
실패 – 오류	작업 실패

성공 응답 필드

이름	Type	null 허용/null 허용 안 함	값 목록
cveId	문자열	nullable이 아님	지정된 CVE에 대한 정식 산업 표준 ID입니다.
Ipaddress	문자열	nullable이 아님	IP 주소
점수	문자열	nullable이 아님	0.0~10.0 사이의 CVE 점수
attackVector	문자열	nullable이 아님	`Network`, `Adjacent Network`, `Local` 또는 `Physical`
description	문자열	nullable이 아님	-

응답 예제

[
    {

        "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.\""
    }
]

형식: GET

APIs:

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

쿼리 매개 변수

다음 쿼리 매개 변수를 정의하여 반환된 결과를 필터링합니다. 쿼리 매개 변수를 설정하지 않으면 모든 디바이스 연결이 반환됩니다.

이름	설명	예시	필수/선택 사항
권한이	부울: - `true`: 권한 있는 디바이스에서만 데이터를 필터링합니다. - `false`: 권한이 없는 디바이스에서만 데이터를 필터링합니다.	`/api/v1/devices/`	선택 사항

응답 형식: JSON

디바이스 개체를 나타내는 JSON 개체의 배열 또는 다음 오류 메시지:

메시지	설명
실패 – 오류	작업 실패

성공 응답 필드

이름	Type	null 허용/null 허용 안 함	값 목록
id	숫자. 디바이스 ID를 정의합니다.	nullable이 아님	-
ipAddresses	문자열의 JSON 배열입니다.	Nullable	-
이름	문자열입니다. 디바이스 이름을 정의합니다.	nullable이 아님	-
공급업체	문자열입니다. 디바이스의 공급업체를 정의합니다.	Nullable	-
operatingSystem	열거형. 디바이스의 운영 체제를 정의합니다.	Nullable	자세한 내용은 지원되는 operatingSystem 값을 참조하세요.
macAddresses	문자열의 JSON 배열입니다.	Nullable	-
type	문자열입니다. 디바이스 유형을 정의합니다.	nullable이 아님	`Unknown`일 수 있습니다. 자세한 내용은 지원되는 형식 값을 참조하세요.
engineeringStation	부울입니다. 디바이스가 엔지니어링 스테이션으로 정의되는지 여부를 정의합니다.	nullable이 아님	- `true`: 디바이스가 엔지니어링 스테이션입니다. - `false`: 디바이스가 엔지니어링 스테이션이 아닙니다.
권한이	부울입니다. 디바이스가 엔지니어링 스테이션으로 정의되는지 여부를 정의합니다.	nullable이 아님	- `true`: 디바이스가 엔지니어링 스테이션입니다. - `false`: 디바이스가 엔지니어링 스테이션이 아닙니다.
스캐너	부울입니다. 디바이스에 권한이 부여되었는지 여부를 정의합니다.	nullable이 아님	- `true`: 디바이스에 권한이 부여됨 - `false`: 디바이스에 권한이 부여되지 않았습니다.
프로토콜	디바이스의 프로토콜 세부 정보를 포함하는 개체입니다.	Nullable	자세한 내용은 Microsoft Defender for IoT - 지원되는 IoT, OT, ICS 및 SCADA 프로토콜을 참조하세요.
펌웨어	디바이스의 펌웨어를 무시하는 `firmware` 개체의 JSON 배열입니다.	nullable이 아님	자세한 내용은 지원되는 펌웨어 필드를 참조하세요.
hasDynamicAddress	부울입니다. 디바이스에 동적 주소가 있는지 여부를 정의합니다.	nullable이 아님	- `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` 값

이 섹션에서는 형식 응답 필드에 대해 지원되는 값을 나열합니다.

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 응답 필드의 프로토콜 개체에 대해 지원되는 필드를 나열합니다.

이름	Type	null 허용/null 허용 안 함	값 목록
id	숫자. 프로토콜의 내부 ID를 정의합니다.	nullable이 아님	-
이름	문자열입니다. 디바이스 이름을 정의합니다.	nullable이 아님	자세한 내용은 아래의 을 참조하십시오.
ipAddresses	프로토콜 IP 주소 문자열의 JSON 배열입니다.	nullable이 아님	-

다음 값은 프로토콜 이름 기본 제공으로 지원됩니다.

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 응답 필드의 펌웨어 개체에 대해 지원되는 필드를 나열합니다.

이름	Type	null 허용/null 허용 안 함	값 목록
address	문자열입니다. 펌웨어 IP 주소를 정의합니다.	nullable이 아님	-
moduleAddress	문자열입니다. 펌웨어의 모듈 주소를 정의합니다.	Null을 허용하지 않습니다.	-
직렬	문자열입니다. 펌웨어의 일련 번호를 정의합니다.	Nullable	-
model	문자열입니다. 펌웨어 모델을 정의합니다.	Nullable	-
firmwareVersion	문자열입니다. 펌웨어 버전을 정의합니다.	Nullable	-
additionalData	문자열입니다. 펌웨어에 대한 추가 데이터를 정의합니다.	Nullable	-
랙	문자열입니다. 펌웨어 랙을 정의합니다.	Nullable	-
슬롯	문자열입니다. 펌웨어 슬롯을 정의합니다.	Nullable	-

형식: GET

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

다음 단계

자세한 내용은 Defender for IoT API 참조 개요를 참조하세요.

다음을 통해 공유

OT 모니터링 센서에 대한 인벤토리 관리 API 참조

connections(디바이스 연결 정보 검색)

GET

쿼리 매개 변수

성공 응답 필드

프로토콜 필드

응답 예제

디바이스당 연결(특정 디바이스 연결 정보 검색)

GET

경로 매개 변수

쿼리 매개 변수

성공 응답 필드

프로토콜 필드

응답 예제

cves(CVE에 대한 정보 검색)

GET

성공 응답 필드

응답 예제

IP 주소당 CVE(CVE에 대한 특정 정보 검색)

GET

경로 매개 변수

성공 응답 필드

응답 예제

devices(디바이스 정보 검색)

GET

쿼리 매개 변수

성공 응답 필드

지원되는 `operatingSystem` 값

지원되는 `type` 값

`protocols` 개체 및 프로토콜 `name` 값에 지원되는 필드

지원되는 펌웨어 필드

다음 단계

피드백

추가 리소스