Referensi API manajemen pemberitahuan untuk konsol manajemen lokal

Artikel ini mencantumkan REST API manajemen pemberitahuan yang didukung untuk Microsoft Defender untuk konsol manajemen lokal IoT.

pemberitahuan (Ambil informasi pemberitahuan)

Gunakan API ini untuk mengambil semua atau pemberitahuan yang difilter dari konsol manajemen lokal.

URI: /external/v1/alerts atau /external/v2/alerts

GET

Minta

Parameter kueri:

Nama	Deskripsi	Contoh	Diperlukan/Opsional
state	Hanya dapatkan pemberitahuan yang ditangani atau tidak tertangani. Nilai yang didukung: - handled - unhandled Semua nilai lainnya diabaikan.	/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
idSitus	Situs tempat pemberitahuan ditemukan.	/api/v1/alerts?siteId=1	Opsional
idZona	Zona tempat pemberitahuan ditemukan.	/api/v1/alerts?zoneId=1	Opsional
idSensor	Sensor tempat pemberitahuan ditemukan.	/api/v1/alerts?sensorId=1	Opsional

Catatan

Anda mungkin tidak memiliki ID situs dan zona. Jika demikian, pertama-tama kueri semua perangkat untuk mengambil situs dan ID zona. Untuk informasi selengkapnya, lihat Referensi API integrasi untuk konsol manajemen lokal (Pratinjau publik).

Respons

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	-
idSensor	Numerik	Tidak dapat diubah ke null	-
idZona	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
RemediasiPerbaikan	String	Dapat diubah ke null	Remediasi perbaikan ditampilkan dalam pemberitahuan
Informasi tambahan	Objek informasi tambahan	Dapat diubah ke null	-
Ditangani	Boolean, status pemberitahuan	Tidak dapat diubah ke null	true atau false

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	Nullable / 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
namaSensor	String	Tidak dapat diubah ke null	Nama sensor yang ditentukan oleh pengguna
zoneName	String	Tidak dapat diubah ke null	Nama zona yang terkait dengan sensor
siteName	String	Tidak dapat diubah ke null	Nama situs yang terkait dengan sensor

Untuk informasi selengkapnya, lihat Referensi versi API Sensor.

Contoh respons

[
    {
        "engine": "Operational",
        "handled": false,
        "title": "Traffic Detected on sensor Interface",
        "additionalInformation": null,
        "sourceDevice": 0,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808245000,
        "sensorId": 1,
        "message": "The sensor resumed detecting network traffic on ens224.",
        "destinationDevice": 0,
        "id": 1,
        "severity": "Warning"
    },
    {
        "engine": "Anomaly",
        "handled": false,
        "title": "Address Scan Detected",
        "additionalInformation": null,
        "sourceDevice": 4,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808260000,
        "sensorId": 1,
        "message": "Address scan detected.\nScanning address: 10.10.10.22\nScanned subnet: 10.11.0.0/16\nScanned addresses: 10.11.1.1, 10.11.20.1, 10.11.20.10, 10.11.20.100, 10.11.20.2, 10.11.20.3, 10.11.20.4, 10.11.20.5, 10.11.20.6, 10.11.20.7...\nIt is recommended to notify the security officer of the incident.",
        "destinationDevice": 0,
        "id": 2,
        "severity": "Critical"
    },
    {
        "engine": "Operational",
        "handled": false,
        "title": "Suspicion of Unresponsive MODBUS Device",
        "additionalInformation": null,
        "sourceDevice": 194,
        "zoneId": 1,
        "siteId": 1,
        "time": 1594808285000,
        "sensorId": 1,
        "message": "Outstation device 10.13.10.1 (Protocol Address 53) seems to be unresponsive to MODBUS requests.",
        "destinationDevice": 0,
        "id": 3,
        "severity": "Minor"
    }
]

perintah cURL

Jenis: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='

Contoh:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/alerts?state=unhandled&zoneId=1&fromTime=0&toTime=1594551777000&siteId=1&sensor=1'

UUID (Mengelola pemberitahuan berdasarkan UUID)

Gunakan API ini untuk mengambil tindakan tertentu pada pemberitahuan tertentu yang terdeteksi oleh Defender for IoT.

Misalnya, Anda dapat menggunakan API ini untuk membuat aturan penerusan yang meneruskan data ke QRadar. Untuk informasi selengkapnya, lihat Mengintegrasikan Qradar dengan Microsoft Defender untuk IoT.

URI: /external/v1/alerts/<UUID>

PUT

Minta

Jenis: JSON

Parameter kueri:

Nama	Deskripsi	Contoh	Diperlukan/Opsional
UUID	Menentukan pengidentifikasi unik universal (UUID) untuk pemberitahuan yang ingin Anda tangani atau tangani dan pelajari.	/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0	Diperlukan

Isi Parameter

Nama	Deskripsi	Contoh	Diperlukan/Opsional
tindakan	String	Baik handle atau handleAndLearn	Diperlukan

Contoh permintaan

{
    "action": "handle"
}

Respons

Jenis: JSON

Array objek JSON yang mewakili perangkat.

Bidang respons:

Nama	Jenis	Diperlukan/Opsional	Deskripsi
konten / kesalahan	String	Diperlukan	Jika permintaan berhasil, properti konten muncul. Jika tidak, properti kesalahan akan muncul.

Nilai konten yang mungkin:

Kode status	Pesan	Deskripsi
200	Permintaan pembaruan pemberitahuan berhasil diselesaikan.	Permintaan pembaruan berhasil diselesaikan. Tidak ada komentar.
200	Pemberitahuan sudah dihandel (handel).	Pemberitahuan sudah dihandel saat permintaan penanganan untuk pemberitahuan diterima. Pemberitahuan tetap dihandel.
200	Pemberitahuan sudah dihandel dan dipelajari (menghandelDanMempelajari).	Pemberitahuan sudah dihandel dan dipelajari saat permintaan untuk handleAndLearn diterima. Pemberitahuan tetap dalam status menghandelDanMempelajari.
200	Pemberitahuan sudah dihandel (dihandel). Menghandel dan mempelajari (menghandelDanMempelajari) dilakukan pada pemberitahuan.	Pemberitahuan sudah dihandel saat permintaan untuk menghandelDanMempelajari diterima. Pemberitahuan menjadi menghandelDanMempelajari.
200	Pemberitahuan sudah dihandel dan dipelajari (menghandelDanMempelajari). Permintaan handel yang diabaikan.	Pemberitahuan sudah menghandelDanMempelajari saat permintaan untuk menghandel pemberitahuan diterima. Pemberitahuan tetap menghandelDanMempelajari.
500	Tindakan tidak valid.	Tindakan yang dikirim bukan tindakan yang valid untuk dilakukan pada pemberitahuan.
500	Terjadi kesalahan yang tidak terduga.	Terjadi kesalahan tak terduga. Untuk mengatasi masalah ini, hubungi Tim Dukungan.
500	Tidak dapat menjalankan permintaan karena tidak ada pemberitahuan yang ditemukan untuk UUID ini.	UUID pemberitahuan yang ditentukan tidak ditemukan di sistem.

Contoh respons: Berhasil

{
    "content": "Alert update request finished successfully"
}

Contoh respons: Tidak berhasil

{
    "error": "Invalid action"
}

perintah cURL

Jenis: PUT

API:

curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>

Contoh:

curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000

maintenanceWindow (Membuat pengecualian pemberitahuan)

Mengelola jendela pemeliharaan, di mana pemberitahuan tidak akan dikirim. Gunakan API ini untuk menentukan dan memperbarui waktu berhenti dan mulai, perangkat, atau subnet yang harus dikecualikan saat memicu pemberitahuan, atau menentukan dan memperbarui Defender untuk mesin IoT yang harus dikecualikan.

Misalnya, selama masa pemeliharaan, Anda mungkin ingin menghentikan pengiriman semua pemberitahuan, kecuali untuk pemberitahuan malware pada perangkat penting.

Jendela pemeliharaan yang menentukan dengan maintenanceWindow API muncul di jendela Pengecualian Pemberitahuan konsol manajemen lokal sebagai aturan pengecualian baca-saja, dinamai dengan sintaks berikut: Maintenance-{token name}-{ticket ID}.

Penting

API ini hanya didukung untuk tujuan pemeliharaan dan untuk jangka waktu terbatas, dan tidak dimaksudkan untuk digunakan alih-alih aturan pengecualian pemberitahuan. Gunakan API ini hanya untuk operasi pemeliharaan sementara satu kali.

URI: /external/v1/maintenanceWindow

POST

Membuat jendela pemeliharaan baru.

Minta

Parameter isi:

Nama	Deskripsi	Contoh	Diperlukan/Opsional
idTiket	String. Menentukan ID tiket pemeliharaan dalam sistem pengguna. Pastikan ID tiket tidak ditautkan ke jendela terbuka yang ada.	2987345p98234	Diperlukan
ttl	Bilangan bulat positif. Mendefinisikan TTL (waktu hidup), yang merupakan durasi jendela pemeliharaan, dalam hitungan menit. Setelah periode waktu yang ditentukan selesai, jendela pemeliharaan berakhir dan sistem bersifat normal lagi.	180	Diperlukan
mesin	Array string JSON. Menentukan mesin mana yang akan menekan pemberitahuan selama jendela pemeliharaan. Nilai yang memungkinkan: - ANOMALY - MALWARE - OPERATIONAL - POLICY_VIOLATION - PROTOCOL_VIOLATION	ANOMALY,OPERATIONAL	Opsional
idSensor	Array string JSON. Menentukan sensor mana yang akan menekan pemberitahuan selama jendela pemeliharaan. Anda bisa mendapatkan ID sensor ini dari API appliance (Kelola appliance sensor OT ).	1,35,63	Opsional
subnet	Array string JSON. Menentukan subnet untuk menekan pemberitahuan selama jendela pemeliharaan. Tentukan setiap subnet dalam notasi CIDR.	192.168.0.0/16,138.136.80.0/14,112.138.10.0/8	Opsional

Respons

Kode status	Pesan	Deskripsi
201 (Dibuat)	-	Tindakan berhasil diselesaikan.
400 (Permintaan Buruk)	Tidak Ada TicketId	Permintaan API kehilangan ticketId nilai.
400 (Permintaan Buruk)	TTL Ilegal	Permintaan API menyertakan nilai TTL non-positif atau non-numerik.
400 (Permintaan Buruk)	Tidak dapat mengurai permintaan.	Masalah saat mengurai isi, seperti parameter yang salah atau nilai yang tidak valid.
400 (Permintaan Buruk)	Jendela pemeliharaan dengan parameter yang sama sudah ada.	Muncul ketika jendela pemeliharaan yang ada sudah ada dengan detail yang sama.
404 (Tidak Ditemukan)	ID sensor tidak diketahui	Salah satu sensor yang tercantum dalam permintaan tidak ada.
409 (Konflik)	ID tiket sudah memiliki jendela yang terbuka.	ID tiket ditautkan ke jendela pemeliharaan terbuka lainnya.
500 (Kesalahan Server Internal)	-	Kesalahan tak terduga lainnya.

perintah cURL

Jenis: POST

API:

curl -k -X POST -d '{"ticketId": "<TICKET_ID>",ttl": <TIME_TO_LIVE>,"engines": [<ENGINE1, ENGINE2...ENGINEn>],"sensorIds": [<SENSOR_ID1, SENSOR_ID2...SENSOR_IDn>],"subnets": [<SUBNET1, SUBNET2....SUBNETn>]}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Contoh:

curl -k -X POST -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20","engines": ["ANOMALY"],"sensorIds": ["5","3"],"subnets": ["10.0.0.0/16"]}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

DELETE

Menutup jendela pemeliharaan yang ada.

Minta

Parameter kueri:

Nama	Deskripsi	Contoh	Diperlukan/Opsional
idTiket	Menentukan ID tiket pemeliharaan dalam sistem pengguna. Pastikan ID tiket ditautkan ke jendela terbuka yang ada.	2987345p98234	Diperlukan

Respons

Kode kesalahan:

Kode	Pesan	Deskripsi
200 (OK)	-	Tindakan berhasil diselesaikan.
400 (Permintaan Buruk)	Tidak Ada TicketId	Parameter ticketId hilang dari permintaan.
404 (Tidak Ditemukan):	Jendela pemeliharaan tidak ditemukan.	ID tiket tidak ditautkan ke jendela pemeliharaan terbuka.
500 (Kesalahan Server Internal)	-	Kesalahan tak terduga lainnya.

perintah cURL

Jenis: HAPUS

API:

curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Contoh:

curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

GET

Ambil log semua tindakan buka (POST), tutup (HAPUS), dan perbarui (PUT) yang dilakukan menggunakan API ini untuk menangani jendela pemeliharaan. T

Minta

Parameter kueri:

Nama	Deskripsi	Contoh	Diperlukan/Opsional
fromDate	Memfilter log dari tanggal yang telah ditentukan sebelumnya dan yang lebih baru. Formatnya adalah YYYY-MM-DD.	2022-08-10	Opsional
toDate	Memfilter log hingga tanggal yang telah ditentukan sebelumnya. Formatnya adalah YYYY-MM-DD.	2022-08-10	Opsional
idTiket	Memfilter log yang terkait dengan ID tiket tertentu.	9a5fe99c-d914-4bda-9332-307384fe40bf	Opsional
namaToken	Memfilter log yang terkait dengan nama token tertentu.	quarterly-sanity-window	Opsional

Kode kesalahan:

Kode	Pesan	Deskripsi
200	OK	Tindakan berhasil diselesaikan.
204:	Tidak ada Konten	Tidak ada data untuk ditampilkan.
400	Permintaan Buruk	Format tanggal salah.
500	Kesalahan Server Internal	Kesalahan tak terduga lainnya.

Respons

Jenis: JSON

Array objek JSON yang mewakili operasi jendela pemeliharaan.

Struktur respons:

Nama	Jenis	Dapat diubah ke null / Tidak dapat diubah ke null	Daftar nilai
id	Bilangan bulat panjang	Tidak dapat diubah ke null	ID internal untuk log saat ini
tanggalWaktu	String	Tidak dapat diubah ke null	Waktu aktivitas terjadi, misalnya: 2022-04-23T18:25:43.511Z
idTiket	String	Tidak dapat diubah ke null	ID jendela pemeliharaan. Misalnya: 9a5fe99c-d914-4bda-9332-307384fe40bf
namaToken	String	Tidak dapat diubah ke null	Nama token jendela pemeliharaan. Misalnya: quarterly-sanity-window
mesin	Array string	Dapat diubah ke null	Mesin tempat jendela pemeliharaan berlaku, seperti yang disediakan selama pembuatan jendela pemeliharaan: Protocol Violation, , Policy Violation, MalwareAnomaly, atauOperational
idSensor	Array string	Dapat diubah ke null	Sensor tempat jendela pemeliharaan berlaku, seperti yang disediakan selama pembuatan jendela pemeliharaan.
subnet	Array string	Dapat diubah ke null	Subnet tempat jendela pemeliharaan berlaku, seperti yang disediakan selama pembuatan jendela pemeliharaan.
ttl	Numerik	Dapat diubah ke null	Time to Live (TTL) jendela pemeliharaan, sebagaimana disediakan selama pembuatan atau pembaruan jendela pemeliharaan.
jenisOperasi	String	Tidak dapat diubah ke null	Salah satu nilai berikut: OPEN, , UPDATEdan CLOSE

perintah cURL

Jenis: GET

API:

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='

Contoh:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/maintenanceWindow?fromDate=2020-01-01&toDate=2020-07-14&ticketId=a5fe99c-d914-4bda-9332-307384fe40bf&tokenName=a'

PUT

Memungkinkan Anda memperbarui durasi jendela pemeliharaan setelah Memulai proses pemeliharaan dengan mengubah ttl parameter . Definisi durasi baru ambil alih yang sebelumnya.

Metode ini berguna ketika Anda ingin mengatur durasi yang lebih lama dari durasi yang dikonfigurasi saat ini. Misalnya, jika Anda awalnya telah menentukan 180 menit, 90 menit telah berlalu, dan Anda ingin menambahkan 30 menit lagi, perbarui ttl ke 120 menit untuk mengatur ulang jumlah durasi.

Minta

Parameter kueri:

Nama	Deskripsi	Contoh	Diperlukan/Opsional
idTiket	String. Menentukan ID tiket pemeliharaan dalam sistem pengguna.	2987345p98234	Diperlukan
ttl	Bilangan bulat positif. Menentukan durasi jendela dalam hitungan menit.	210	Diperlukan

Respons

Kode kesalahan:

Kode	Pesan	Deskripsi
200 (OK)	-	Tindakan berhasil diselesaikan.
400 (Permintaan Buruk)	Tidak Ada TicketId	Permintaan kehilangan ticketId nilai.
400 (Permintaan Buruk)	TTL Ilegal	TTL yang didefinisikan bukan numerik atau bukan bilangan bulat positif.
400 (Permintaan Buruk)	Tidak dapat mengurai permintaan	Permintaan tidak memiliki ttl nilai parameter.
404 (Tidak Ditemukan)	Jendela pemeliharaan tidak ditemukan	ID tiket tidak ditautkan ke jendela pemeliharaan terbuka.
500 (Kesalahan Server Internal)	-	Kesalahan tak terduga lainnya.

perintah cURL

Jenis: PUT

API:

curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow

Contoh:

curl -k -X PUT -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf","ttl": "20"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow

pcap (Meminta pemberitahuan PCAP)

Gunakan API ini untuk mengambil file PCAP yang terkait dengan pemberitahuan.

URI: /external/v2/alerts/

GET

Minta

Parameter kueri:

Nama	Deskripsi	Contoh	Diperlukan/Opsional
id	ID pemberitahuan dari konsol manajemen lokal	/external/v2/alerts/pcap/<id>	Diperlukan

Respons

Jenis: JSON

String pesan dengan detail status operasi:

Kode status	Pesan	Deskripsi
200 (OK)	-	Objek JSON dengan data tentang file PCAP yang diminta. Untuk informasi selengkapnya, lihat Bidang data.
500 (Kesalahan Server Internal)	Pemberitahuan tidak ditemukan	ID pemberitahuan yang disediakan tidak ditemukan di konsol manajemen lokal.
500 (Kesalahan Server Internal)	Kesalahan saat mendapatkan token untuk id xsense <number>	Terjadi kesalahan saat mendapatkan token sensor untuk ID sensor yang ditentukan
500 (Kesalahan Server Internal)	-	Kesalahan tak terduga lainnya.

Bidang data

Nama	Jenis	Dapat diubah ke null / Tidak dapat diubah ke null	Daftar nilai
id	Numerik	Tidak dapat diubah ke null	ID pemberitahuan konsol manajemen lokal
xsenseId	Numerik	Tidak dapat diubah ke null	The sensor ID
xsenseAlertId	Numerik	Tidak dapat diubah ke null	ID pemberitahuan konsol sensor
downloadUrl	String	Tidak dapat diubah ke null	URL yang digunakan untuk mengunduh file PCAP
token	String	Tidak dapat diubah ke null	Token sensor, yang akan digunakan saat mengunduh file PCAP

Contoh respons: Berhasil

{
  "downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
  "xsenseId": 1,
  "token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
  "id": 1,
  "xsenseAlertId": 1
}

Contoh respons: Kesalahan

{
  "error": "alert not found"
}

perintah cURL

Jenis: GET

API

curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'

*Contoh:

curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'

Langkah berikutnya

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