Referensi API manajemen inventori untuk sensor pemantauan OT

Artikel
12/18/2023

Artikel ini mencantumkan API manajemen inventarisasi perangkat yang didukung untuk sensor Defender for IoT OT.

koneksi (Mengambil informasi koneksi perangkat)

Gunakan API ini untuk meminta daftar semua koneksi perangkat.

URI: /api/v1/devices/connections

GET

Parameter kueri

Tentukan salah satu parameter kueri berikut untuk memfilter hasil yang dikembalikan. Jika Anda tidak mengatur parameter kueri, semua koneksi perangkat akan dikembalikan.

Nama	Deskripsi	Contoh	Diperlukan / Opsional
discoveredBefore	Numerik. Filter hasil yang terdeteksi sebelum waktu tertentu, di mana waktu yang diberikan ditentukan dalam milidetik dari waktu Epoch, dan dalam zona waktu UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opsional
discoveredAfter	Numerik. Memfilter hasil yang terdeteksi setelah waktu tertentu, di mana waktu yang diberikan ditentukan dalam milidetik dari waktu Epoch, dan dalam zona waktu UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opsional
lastActiveInMinutes	Numerik. Memfilter hasil menurut jangka waktu tertentu di mana koneksi aktif. Ditentukan mundur, dalam hitungan menit, dari waktu saat ini.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opsional

Jenis respons: JSON

Array objek JSON yang mewakili koneksi perangkat, atau pesan kegagalan berikut:

Pesan	Deskripsi
Kegagalan – kesalahan	Operasi gagal

Bidang respons keberhasilan

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
IdPerangkatPertama	Numerik	Tidak dapat diubah ke null	-
IdPerangkatKedua	Numerik	Tidak dapat diubah ke null	-
TerakhirDilihat	Numerik	Tidak dapat diubah ke null	Zaman (UTC)
ditemukan	Numerik	Tidak dapat diubah ke null	Zaman (UTC)
port	Array angka	Dapat diubah ke null	-
protokol	Array JSON	Dapat diubah ke null	Bidang protokol

Bidang protokol

Nama	Jenis	Nullable / Tidak dapat diubah ke null
nama	String	Tidak dapat diubah ke null
perintah	Array string	Dapat diubah ke null

Contoh tanggapan

[
    {
        "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"
                ]
            }
        ]
    }
]

Jenis: GET

API:

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

Contoh:

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

koneksi per perangkat (Ambil informasi koneksi perangkat tertentu )

Gunakan API ini untuk meminta daftar semua sambungan per perangkat.

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

GET

Parameter jalur

Nama	Deskripsi	Contoh	Diperlukan / Opsional
deviceId	Dapatkan koneksi untuk perangkat yang diberikan.	`/api/v1/devices/<deviceId>/connections`	Wajib

Parameter kueri

Nama	Deskripsi	Contoh	Diperlukan / Opsional
discoveredBefore	Numerik. Filter hasil yang terdeteksi sebelum waktu tertentu, di mana waktu yang diberikan ditentukan dalam milidetik dari waktu Epoch, dan dalam zona waktu UTC.	`/api/v1/devices/2/connections?discoveredBefore=<epoch>`	Opsional
discoveredAfter	Numerik. Memfilter hasil yang terdeteksi setelah waktu tertentu, di mana waktu yang diberikan ditentukan dalam milidetik dari waktu Epoch, dan dalam zona waktu UTC.	`/api/v1/devices/2/connections?discoveredAfter=<epoch>`	Opsional
lastActiveInMinutes	Numerik. Memfilter hasil menurut jangka waktu tertentu di mana koneksi aktif. Ditentukan mundur, dalam hitungan menit, dari waktu saat ini.	`/api/v1/devices/2/connections?lastActiveInMinutes=20`	Opsional

Jenis respons: JSON

Array objek JSON yang mewakili koneksi perangkat, atau pesan kegagalan berikut:

Pesan	Deskripsi
Kegagalan – kesalahan	Operasi gagal

Bidang respons keberhasilan

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
IdPerangkatPertama	Numerik	Tidak dapat diubah ke null	-
IdPerangkatKedua	Numerik	Tidak dapat diubah ke null	-
TerakhirDilihat	Numerik	Tidak dapat diubah ke null	Zaman (UTC)
ditemukan	Numerik	Tidak dapat diubah ke null	Zaman (UTC)
port	Array angka	Dapat diubah ke null	-
protokol	Array JSON	Dapat diubah ke null	Bidang protokol

Bidang protokol

Nama	Jenis	Nullable / Tidak dapat diubah ke null
nama	String	Tidak dapat diubah ke null
perintah	Array string	Dapat diubah ke null

Contoh tanggapan

[
    {
        "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"
                ]
            }
        ]
    }
]

Jenis: GET

API:

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

Contoh:

Dengan parameter kueri yang diberikan:

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

cves (Ambil informasi tentang CVE)

Gunakan API ini untuk meminta daftar semua CVE yang diketahui yang ditemukan pada perangkat di jaringan, diurutkan dengan skor CVE turun.

URI: /api/v1/devices/cves

GET

Contoh: /api/v1/devices/cves

Tentukan salah satu parameter kueri berikut untuk memfilter hasil yang dikembalikan.

Nama	Deskripsi	Contoh	Diperlukan / Opsional
top	Numerik. Tentukan berapa banyak CVE dengan skor teratas yang akan didapatkan untuk setiap alamat IP perangkat.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opsional. Default = `100`

Jenis: JSON

Array JSON objek CVE perangkat, atau pesan kegagalan berikut:

Pesan	Deskripsi
Kegagalan – kesalahan	Operasi gagal

Bidang respons keberhasilan

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
cveId	String	Tidak dapat diubah ke null	ID standar industri kanonis untuk CVE yang diberikan.
alamatIp	String	Tidak dapat diubah ke null	Alamat IP
skor	String	Tidak dapat diubah ke null	Skor CVE, antara 0,0 - 10,0
vektorSerangan	String	Tidak dapat diubah ke null	`Network`, `Adjacent Network`, `Local`, atau `Physical`
description	String	Tidak dapat diubah ke null	-

Contoh tanggapan

[
    {

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

Jenis: GET

API:

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

Contoh:

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

cves per alamat IP (Ambil informasi spesifik tentang CVE)

Gunakan API ini untuk meminta daftar semua CVE yang diketahui yang ditemukan pada perangkat di jaringan untuk alamat IP tertentu.

URI: /api/v1/devices/cves

GET

Contoh: /api/v1/devices/cves

Parameter jalur

Nama	Deskripsi	Contoh	Diperlukan / Opsional
alamatIp	Dapatkan CVE untuk alamat IP yang diberikan.	`/api/v1/devices/<ipAddress>/cves`	Wajib

Tentukan parameter kueri berikut untuk memfilter hasil yang dikembalikan.

Nama	Deskripsi	Contoh	Diperlukan / Opsional
top	Numerik. Tentukan berapa banyak CVE dengan skor teratas yang akan didapatkan untuk setiap alamat IP perangkat.	`/api/v1/devices/cves?top=50` `/api/v1/devices/<ipAddress>/cves?top=50`	Opsional. Default = `100`

Jenis: JSON

Array JSON objek CVE perangkat, atau pesan kegagalan berikut:

Pesan	Deskripsi
Kegagalan – kesalahan	Operasi gagal

Bidang respons keberhasilan

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
cveId	String	Tidak dapat diubah ke null	ID standar industri kanonis untuk CVE yang diberikan.
alamatIp	String	Tidak dapat diubah ke null	Alamat IP
skor	String	Tidak dapat diubah ke null	Skor CVE, antara 0,0 - 10,0
vektorSerangan	String	Tidak dapat diubah ke null	`Network`, `Adjacent Network`, `Local`, atau `Physical`
description	String	Tidak dapat diubah ke null	-

Contoh tanggapan

[
    {

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

Jenis: GET

API:

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

Contoh:

Dengan parameter kueri yang diberikan:

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

perangkat (Ambil informasi perangkat)

Gunakan API ini untuk meminta daftar semua perangkat yang terdeteksi oleh sensor ini.

URI: api/v1/devices/

GET

Parameter kueri

Tentukan parameter kueri berikut untuk memfilter hasil yang dikembalikan. Jika Anda tidak mengatur parameter kueri, semua koneksi perangkat akan dikembalikan.

Nama	Deskripsi	Contoh	Diperlukan / Opsional
diotorisasi	Boolean: - `true`: Filter untuk data hanya pada perangkat yang diotorisasi. - `false`: Filter untuk data hanya pada perangkat yang tidak sah.	`/api/v1/devices/`	Opsional

Jenis respons: JSON

Array objek JSON yang mewakili objek perangkat, atau pesan kegagalan berikut:

Pesan	Deskripsi
Kegagalan – kesalahan	Operasi gagal

Bidang respons keberhasilan

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
id	Numerik. Menentukan ID perangkat.	Tidak dapat diubah ke null	-
alamatIp	Array string JSON.	Dapat diubah ke null	-
nama	String. Menentukan nama perangkat.	Tidak dapat diubah ke null	-
penjual	String. Menentukan vendor perangkat.	Dapat diubah ke null	-
sistemOperasi	Enum. Menentukan sistem operasi perangkat.	Dapat diubah ke null	Untuk informasi selengkapnya, lihat Nilai operatingSystem yang didukung.
alamatMac	Array string JSON.	Dapat diubah ke null	-
jenis	String. Menentukan jenis perangkat.	Tidak dapat diubah ke null	Bisa jadi `Unknown`. Untuk informasi selengkapnya, lihat Nilai jenis yang didukung.
stasiunTeknik	Boolean. Menentukan apakah perangkat didefinisikan sebagai stasiun rekayasa atau tidak.	Tidak dapat diubah ke null	- `true`: Perangkat adalah stasiun rekayasa - `false`: Perangkat bukan stasiun rekayasa.
diotorisasi	Boolean. Menentukan apakah perangkat didefinisikan sebagai stasiun rekayasa atau tidak.	Tidak dapat diubah ke null	- `true`: Perangkat adalah stasiun rekayasa - `false`: Perangkat bukan stasiun rekayasa
pemindai	Boolean. Menentukan apakah perangkat diotorisasi atau tidak.	Tidak dapat diubah ke null	- `true`: Perangkat diotorisasi - `false`: Perangkat tidak diotorisasi
protokol	Objek yang berisi detail protokol perangkat.	Dapat diubah ke null	Untuk informasi selengkapnya, lihat Microsoft Defender untuk IoT - mendukung protokol IoT, OT, ICS, dan SCADA.
firmware	Array JSON objek `firmware` yang menentang firmware perangkat.	Tidak dapat diubah ke null	Untuk informasi selengkapnya, lihat Bidang firmware yang didukung.
hasDynamicAddress	Boolean. Menentukan apakah perangkat memiliki alamat dinamis atau tidak.	Tidak dapat diubah ke null	- `true`: Perangkat memiliki alamat dinamis - `false`: Perangkat tidak memiliki alamat dinamis

Nilai yang didukung `operatingSystem`

Bagian ini mencantumkan nilai yang didukung untuk bidang respons 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

Nilai yang didukung `type`

Bagian ini mencantumkan nilai yang didukung untuk bidang respons jenis .

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

Bidang yang didukung untuk `protocols` nilai objek dan protokol `name`

Bagian ini mencantumkan bidang yang didukung untuk objek protokol di protocols bidang respons.

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
id	Numerik. Menentukan ID internal protokol.	Tidak dapat diubah ke null	-
nama	String. Menentukan nama perangkat.	Tidak dapat diubah ke null	Untuk informasi selengkapnya, lihat di bawah ini.
alamatIp	Array JSON dari string alamat IP protokol.	Tidak dapat diubah ke null	-

Nilai berikut didukung sebagai nama protokol di luar kotak:

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

Bidang firmware yang didukung

Bagian ini mencantumkan bidang yang didukung untuk objek firmware di firmware bidang respons.

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
alamat	String. Menentukan alamat IP firmware.	Tidak dapat diubah ke null	-
modulAlamat	String. Menentukan alamat modul firmware.	Tidak dapat diubah ke null.	-
serial	String. Menentukan nomor seri firmware.	Dapat diubah ke null	-
model	String. Mendefinisikan model firmware.	Dapat diubah ke null	-
VersiFirmware	String. Menentukan versi firmware.	Dapat diubah ke null	-
DataTambahan	String. Menentukan data tambahan untuk firmware.	Dapat diubah ke null	-
rak	String. Mendefinisikan rak firmware.	Dapat diubah ke null	-
slot	String. Menentukan slot firmware.	Dapat diubah ke null	-

Jenis: GET

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

Langkah berikutnya

Untuk informasi selengkapnya, lihat ringkasan referensi Defender for IoT API.

Bagikan melalui

Referensi API manajemen inventori untuk sensor pemantauan OT

koneksi (Mengambil informasi koneksi perangkat)

GET

Parameter kueri

Bidang respons keberhasilan

Bidang protokol

Contoh tanggapan

koneksi per perangkat (Ambil informasi koneksi perangkat tertentu )

GET

Parameter jalur

Parameter kueri

Bidang respons keberhasilan

Bidang protokol

Contoh tanggapan

cves (Ambil informasi tentang CVE)

GET

Bidang respons keberhasilan

Contoh tanggapan

cves per alamat IP (Ambil informasi spesifik tentang CVE)

GET

Parameter jalur

Bidang respons keberhasilan

Contoh tanggapan

perangkat (Ambil informasi perangkat)

GET

Parameter kueri

Bidang respons keberhasilan

Nilai yang didukung `operatingSystem`

Nilai yang didukung `type`

Bidang yang didukung untuk `protocols` nilai objek dan protokol `name`

Bidang firmware yang didukung

Langkah berikutnya

Sumber Daya Tambahan: