Referensi API manajemen pemberitahuan untuk sensor pemantauan OT

Artikel
06/01/2023

Artikel ini mencantumkan REST API manajemen pemberitahuan yang didukung untuk Microsoft Defender untuk sensor pemantauan OT IoT.

pemberitahuan (Ambil informasi pemberitahuan)

Gunakan API ini untuk meminta daftar semua pemberitahuan yang telah dideteksi oleh sensor Defender for IoT.

URI: /api/v1/alerts

GET

Parameter kueri

Nama	Deskripsi	Contoh	Diperlukan/Opsional
state	Hanya dapatkan pemberitahuan yang ditangani atau tidak tertangani. Nilai yang didukung: - `handled` - `unhandled`	`/api/v1/alerts?state=handled`	Opsional
fromTime	Dapatkan pemberitahuan yang dibuat mulai pada waktu tertentu, dalam milidetik dari waktu Epoch dan di zona waktu UTC.	`/api/v1/alerts?fromTime=<epoch>`	Opsional
toTime	Dapatkan pemberitahuan yang dibuat hanya sebelum pada waktu tertentu, dalam milidetik dari waktu Epoch dan di zona waktu UTC.	`/api/v1/alerts?toTime=<epoch>`	Opsional
jenis	Dapatkan pemberitahuan dari jenis tertentu saja. Nilai yang didukung: - `unexpected new devices` - `disconnections` Semua nilai lainnya diabaikan.	`/api/v1/alerts?type=disconnections`	Opsional

Jenis: JSON

Daftar pemberitahuan dengan bidang berikut:

Nama	Jenis	Dapat diubah ke null / Tidak dapat diubah ke null	Daftar nilai
ID	Numerik	Tidak dapat diubah ke null	-
waktu	Numerik	Tidak dapat diubah ke null	Milidetik dari waktu Epoch, dalam zona waktu UTC
judul	String	Tidak dapat diubah ke null	-
message	String	Tidak dapat diubah ke null	-
keparahan	String	Tidak dapat diubah ke null	`Warning`, `Minor`, `Major`, atau `Critical`
mesin	String	Tidak dapat diubah ke null	`Protocol Violation`, `Policy Violation`, `Malware`, `Anomaly`, atau `Operational`
perangkatSumber	Numerik	Dapat diubah ke null	ID Perangkat
perangkatTujuan	Numerik	Dapat diubah ke null	ID Perangkat
Informasi tambahan	Objek informasi tambahan	Dapat diubah ke null	-

Bidang informasi tambahan

Nama	Jenis	Dapat diubah ke null / Tidak dapat diubah ke null	Daftar nilai
deskirpsi	String	Tidak dapat diubah ke null	-
informasi	Array JSON	Tidak dapat diubah ke null	String

Ditambahkan untuk V2:

Nama	Jenis	Dapat diubah ke null / Tidak dapat diubah ke null	Daftar nilai
sumberAlamatPerangkat	String	Dapat diubah ke null	Alamat IP atau MAC
tujuanAlamatPerangkat	String	Dapat diubah ke null	Alamat IP atau MAC
RemediasiPerbaikan	Array JSON	Tidak dapat diubah ke null	String, langkah-langkah remediasi yang dijelaskan dalam pemberitahuan

Untuk informasi selengkapnya, lihat Referensi versi SENSOR API.

Contoh respons

[
    {
        "engine": "Policy Violation",
        "severity": "Major",
        "title": "Internet Access Detected",
        "additionalinformation": {
            "information": [
                "170.60.50.201 over port BACnet (47808)"
            ],
            "description": "External Addresses"
        },
        "sourceDevice": null,
        "destinationDevice": null,
        "time": 1509881077000,
        "message": "Device 192.168.0.13 tried to access an external IP address which is an address in the Internet and is not allowed by policy. It is recommended to notify the security officer of the incident.",
        "id": 1
    },
    {
        "engine": "Protocol Violation",
        "severity": "Major",
        "title": "Illegal MODBUS Operation (Exception Raised by Master)",
        "sourceDevice": 3,
        "destinationDevice": 4,
        "time": 1505651605000,
        "message": "A MODBUS master 192.168.110.131 attempted to initiate an illegal operation.\nThe operation is considered to be illegal since it incorporated function code \#129 which should not be used by a master.\nIt is recommended to notify the security officer of the incident.",
        "id": 2,
        "additionalInformation": null,
    }
]

Jenis: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/alerts?state=<STATE>&fromTime=<FROM_TIME>&toTime=<TO_TIME>&type=<TYPE>'

Contoh:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/alerts?state=unhandled&fromTime=1594550986000&toTime=1594550986001&type=disconnections'

peristiwa (Mengambil peristiwa garis waktu)

Gunakan API ini untuk meminta daftar peristiwa yang dilaporkan ke timeline peristiwa.

Catatan

Menjalankan API yang identik dalam satu jam yang sama, dengan nilai parameter yang sama persis, mengembalikan nilai cache. Jika Anda menjalankan API ini dua kali dalam satu jam, kami sarankan Anda memodifikasi parameter kueri untuk mendapatkan respons yang diperbarui.

URI: /api/v1/events

GET

Parameter kueri

Nama	Deskripsi	Contoh	Diperlukan/Opsional
minutesTimeFrame	Memfilter hasil menurut jangka waktu tertentu di mana peristiwa dilaporkan. Ditentukan mundur dari waktu saat ini. Maksimum = `4320` (3 hari). Nilai yang lebih besar diperlakukan sebagai 4320, tanpa kesalahan	`/api/v1/events?minutesTimeFrame=20`	Opsional
jenis	Memfilter hasil untuk jenis tertentu saja. Nilai apa pun selain jenis yang didukung diabaikan. Untuk informasi selengkapnya, lihat Peristiwa `type` dan `title` referensi.	`/api/v1/events?type=DEVICE_CONNECTION_CREATED` `/api/v1/events?type=REMOTE_ACCESS&minutesTimeFrame`	Opsional

Jenis: JSON

Array objek JSON yang mewakili 100 peristiwa terbaru, diurutkan berdasarkan tanda waktu peristiwa, dengan peristiwa terbaru terlebih dahulu.

Bidang peristiwa meliputi:

Nama	Jenis	Nullable / Tidak dapat diubah ke null	Daftar nilai
timestamp	Numerik	Tidak dapat diubah ke null	Milidetik dari waktu Epoch, dalam zona waktu UTC
tipe	String	Tidak dapat diubah ke null	Salah satu jenis yang didukung
judul	String	Tidak dapat diubah ke null	Salah satu judul yang didukung
keparahan	String	Tidak dapat diubah ke null	`INFO`, `NOTICE`, atau `ALERT`
pemilik	String	Dapat diubah ke null	String. Jika peristiwa dibuat secara manual, bidang ini akan menyertakan nama pengguna yang membuat peristiwa.
konten	String	Tidak dapat diubah ke null	String yang menjelaskan peristiwa.

Contoh respons

[
    {
        "severity": "INFO",
        "title": "Back to Normal",
        "timestamp": 1504097077000,
        "content": "Device 10.2.1.15 was found responsive, after being suspected as disconnected",
        "owner": null,
        "type": "BACK_TO_NORMAL"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504096909000,
        "content": "Device 10.2.1.15 is suspected to be disconnected (unresponsive).",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "ALERT",
        "title": "Alert Detected",
        "timestamp": 1504094446000,
        "content": "A DNP3 Master 10.2.1.14 attempted to initiate a request which is not allowed by policy.\nThe policy indicates the allowed function codes, address ranges, point indexes and time intervals.\nIt is recommended to notify the security officer of the incident.",
        "owner": null,
        "type": "ALERT_REPORTED"
    },
    {
        "severity": "NOTICE",
        "title": "PLC Program Update",
        "timestamp": 1504094344000,
        "content": "Program update detected, sent from 10.2.1.25 to 10.2.1.14",
        "owner": null,
        "type": "PROGRAM_DEVICE"
    }
]

Jenis: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/api/v1/events?minutesTimeFrame=<TIME_FRAEM>&type=<TYPE>'

Contoh:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/api/v1/events?minutesTimeFrame=20&type=DEVICE_CONNECTION_CREATED'`

Peristiwa `type` dan `title` referensi

Bagian ini mencantumkan nilai yang didukung sebagai jenis peristiwa dan nilai judul untuk API peristiwa .

Jenis peristiwa	Judul acara
DEVICE_CREATE	Perangkat Terdeteksi
DEVICE_UPDATE	Perangkat Diperbarui
ALERT_REPORTED	Peringatan Terdeteksi
ALERT_UPDATED	Peringatan Diperbarui
SCAN	Perangkat Pemindaian Terdeteksi
PROGRAM_DEVICE	Pemrograman PLC
MMS_PROGRAM_DEVICE	Pembaruan Program PLC
SCL_UPLOADED	SCL Diunggah
EXCLUSION_RULE_CREATED	Aturan Pengecualian Dibuat
EXCLUSION_RULE_REMOVED	Aturan Pengecualian Dihapus
EXCLUSION_RULE_UPDATED	Aturan Pengecualian Diperbarui
DEVICE_CONNECTION_CREATED	Koneksi Perangkat Terdeteksi
USER_LOGIN	Upaya Masuk Pengguna
FILE_TRANSFER	Transfer File Terdeteksi
CUSTOM_EVENT	Peristiwa yang Ditentukan Pengguna
REMOTE_ACCESS	Sambungan Akses Jarak Jauh Dibuat
BACK_TO_NORMAL	Kembali ke Normal
MMS_MEMORY_BLOCK_OPERATION	Operasi Blok Memori MMS
MMS_PROGRAM_OPERATION	Operasi Program MMS
HTTP_BASIC_AUTHENTICATION	Autentikasi Dasar HTTP
SIEMENS_S_7_MEMORY_BLOCK_OPERATION	Operasi Blok Memori Siemens S7
SIEMENS_S_7_AUTHENTICATION	Autentikasi Siemens S7
REPORT_CREATED	Laporan Dibuat
SNMP_TRAP	Perangkap SNMP terdeteksi
DATABASE_ACTION	Manipulasi Struktur Database
PLC_MODULE_CHANGE	Perubahan Modul PLC
FIRMWARE_UPDATE	Pembaruan Firmware
PLC_START	Mulai PLC
SRTP_PLC_RESET	PLC Reset
SRTP_PLC_COPY_FIRMWARE	Pembaruan Firmware
SRTP_LOGIN_PROGRAMMING	Set Mode Pemrograman PLC
SRTP_PLC_CHANGE_PASSWORD	Perubahan Kata Sandi PLC
OPC_DATA_ACCESS_GROUP_MANAGEMENT_OPERATION	Operasi Manajemen Grup Akses Data OPC
OPC_DATA_ACCESS_ITEM_MANAGEMENT_OPERATION	Operasi Manajemen Item Akses Data OPC
OPC_DATA_ACCESS_IO_SUBSCRIPTION_MANAGEMENT_OPERATION	Operasi Manajemen Langganan IO Akses Data OPC
OPC_AE_EVENT_SUBSCRIPTION	Langganan Peristiwa OPC AE
OPC_AE_EVENT_CONDITION_MANAGEMENT_OPERATION	Operasi Manajemen Kondisi Peristiwa OPC AE
OPC_AE_EVENT	Peristiwa OPC AE
SRTP_CHANGE_PRIVILEGE	PLC Ubah tingkat akses
SRTP_CHANGE_LEVEL_FAILED	Gagal mengubah tingkat akses PLC
SUITELINK_INIT_CONNECTION	Sesi wonderware diinisialisasi
USER_OPERATION	Operasi Pengguna
DIP_UPLOADED	Paket Inteligensi Data Diunggah
FTP_AUTHENTICATION_FAILURE	Kegagalan Autentikasi FTP
PROFINET_DPC_VALUE_SET	Operasi SET profinet
S7PLUS_PLC_MODE_CHANGE	Perubahan Mode PLC
S7_PLC_MODE_CHANGE	Perubahan Mode PLC
DELETE_DEVICE	Perangkat Dihapus
S7PLUS_PROGRAMMING	Pemrograman PLC
FIRMWARE_CHANGED	Firmware PLC Berubah
DELTAV_PROGRAMMING	Skrip Penginstalan DeltaV
USER_DEFINED_RULE_CREATED	Aturan yang Ditentukan Pengguna Dibuat
USER_DEFINED_RULE_EDITED	Aturan yang Ditentukan Pengguna Diedit
USER_DEFINED_RULE_DELETED	Aturan yang Ditentukan Pengguna Dihapus
USER_DEFINED_RULE_OPERATION	Operasi Aturan yang Ditentukan Pengguna
REMOTE_PROCESS_EXECUTION	Eksekusi Proses Jarak Jauh
DEVICE_UNIFICATION	Perangkat Diperbarui
PEMBERITAHUAN	Pemberitahuan diselesaikan secara manual
ENIP_CONTROLLER_PROGRAM_DELETE	Penghapusan Program Pengontrol
ENIP_CONTROLLER_PROGRAM_RESET	Reset Program Pengontrol
ENIP_CONTROLLER_GENERIC_RESET	Pengaturan Ulang Pengontrol
ENIP_CONTROLLER_GENERIC_STOP	Pengontrol Berhenti
ENIP_CONTROLLER_GENERIC_START	Pengontrol Mulai
TELNET_AUTHENTICATION_FAILURE	Kegagalan Autentikasi Telnet
CONFIGURATION_OF_CLEARTEXT_PASSWORD	Konfigurasi Kata Sandi Cleartext
CLEARTEXT_AUTHENTICATION	Autentikasi Cleartext
PROGRAM_UPLOAD_DEVICE	Unggahan Program PLC
CONFIGURATION_CHANGE	Penulisan Konfigurasi PLC
CONFIGURATION_READ	Baca Konfigurasi PLC
SYSLOG_MSG	Pesan Syslog
INTERNET_ACCESS	Akses Internet
CAMP_MEMORY_WRITE_OPERATION	Operasi Penulisan Memori Protokol Pesan ASCII Umum
MUTED_ALERT	Peristiwa Terdeteksi dan Dimatikan Suaranya
DHCP_UPDATE	Pembaruan Alamat
DIP_FAILURE	Kegagalan Penginstalan Paket Inteligensi Data
DELETE_DEVICE_SCHEDULE	Perangkat Tidak Aktif Dijadwalkan untuk dihapus
PLC_OPERATING_MODE_CHANGED	Perubahan Mode Operasi PLC Terdeteksi
HARDWARE_UPDATE_BY_IDENTIFIER	Pembaruan Alamat

Langkah berikutnya

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

Bagikan melalui

Referensi API manajemen pemberitahuan untuk sensor pemantauan OT

pemberitahuan (Ambil informasi pemberitahuan)

GET

Parameter kueri

Bidang informasi tambahan

Contoh respons

peristiwa (Mengambil peristiwa garis waktu)

GET

Parameter kueri

Contoh respons

Peristiwa `type` dan `title` referensi

Langkah berikutnya

Sumber Daya Tambahan:

Bagikan melalui

Referensi API manajemen pemberitahuan untuk sensor pemantauan OT

pemberitahuan (Ambil informasi pemberitahuan)

GET

Parameter kueri

peristiwa (Mengambil peristiwa garis waktu)

GET

Parameter kueri

Peristiwa type dan title referensi

Langkah berikutnya

Sumber Daya Tambahan:

Peristiwa `type` dan `title` referensi