Şirket içi yönetim konsolları için uyarı yönetimi API'si başvurusu
Makale
06/01/2023
3 katılımcı
Geri Bildirim
Bu makalede
Bu makalede, IoT şirket içi yönetim konsolları için Microsoft Defender için desteklenen uyarı yönetimi REST API'leri listelenir.
Şirket içi yönetim konsolundan tüm veya filtrelenmiş uyarıları almak için bu API'yi kullanın.
URI : /external/v1/alerts
veya /external/v2/alerts
GET
Sorgu parametreleri :
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
Durum
Yalnızca işlenen veya işlenmeyen uyarıları alın. Desteklenen değerler: - handled
- unhandled
Diğer tüm değerler yoksayılır.
/api/v1/alerts?state=handled
İsteğe Bağlı
fromTime
Belirli bir zamanda, Dönem saatinden ve UTC saat diliminden milisaniye olarak başlayarak oluşturulan uyarıları alın.
/api/v1/alerts?fromTime=<epoch>
İsteğe Bağlı
toTime
Yalnızca belirli bir zamanda, Dönem zamanından ve UTC saat diliminden milisaniye cinsinden oluşturulan uyarıları alın.
/api/v1/alerts?toTime=<epoch>
İsteğe Bağlı
Siteıd
Uyarının bulunduğu site.
/api/v1/alerts?siteId=1
İsteğe Bağlı
zoneId
Uyarının bulunduğu bölge.
/api/v1/alerts?zoneId=1
İsteğe Bağlı
sensorId
Uyarının bulunduğu algılayıcı.
/api/v1/alerts?sensorId=1
İsteğe Bağlı
Tür : JSON
Aşağıdaki alanlara sahip uyarıların listesi:
Ad
Tür
Null atanabilir / Boş değer atanamaz
Değer listesi
Kimliği
Sayısal
Null atanamaz
-
sensorId
Sayısal
Null atanamaz
-
zoneId
Sayısal
Null atanamaz
-
Zaman
Sayısal
Null atanamaz
Utc saat diliminde Dönem zamanından milisaniye
başlık
Dize
Null atanamaz
-
ileti
Dize
Null atanamaz
-
Önem
Dize
Null atanamaz
Warning
, Minor
, Major
veya Critical
Motoru
Dize
Null atanamaz
Protocol Violation
, Policy Violation
, Malware
, Anomaly
veya Operational
sourceDevice
Sayısal
Null Atanabilir
Cihaz Kimliği
destinationDevice
Sayısal
Null Atanabilir
Cihaz Kimliği
remediationSteps
Dize
Null Atanabilir
Uyarıda gösterilen düzeltme adımları
additionalInformation
Ek bilgi nesnesi
Null Atanabilir
-
Işlenen
Boole, uyarının durumu
Null atanamaz
true
veya false
Ek bilgi alanları :
Ad
Tür
Null atanabilir / Boş değer atanamaz
Değer listesi
açıklama
Dize
Null atanamaz
-
Bilgi
JSON dizisi
Boş değer atanamaz
Dize
V2 için eklendi :
Ad
Tür
Null atanabilir / Boş değer atanamaz
Değer listesi
sourceDeviceAddress
Dize
Null Atanabilir
IP veya MAC adresi
destinationDeviceAddress
Dize
Null Atanabilir
IP veya MAC adresi
remediationSteps
JSON dizisi
Boş değer atanamaz
Dizeler, uyarıda açıklanan düzeltme adımları
sensorName
Dize
Boş değer atanamaz
Kullanıcı tarafından tanımlanan algılayıcının adı
Bölgeadı
Dize
Boş değer atanamaz
Algılayıcıyla ilişkilendirilmiş bölgenin adı
Sitename
Dize
Boş değer atanamaz
Algılayıcıyla ilişkilendirilmiş sitenin adı
Daha fazla bilgi için bkz . Algılayıcı API'si sürüm başvurusu .
Yanıt örneği
[
{
"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"
}
]
Tür : GET
API :
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/alerts?state=&zoneId=&fromTime=&toTime=&siteId=&sensor='
Örnek :
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 (Uyarıları UUID'ye göre yönetme)
IoT için Defender tarafından algılanan belirli bir uyarıda belirtilen eylemi yapmak için bu API'yi kullanın.
Örneğin, verileri QRadar'a iletme kuralı oluşturmak için bu API'yi kullanabilirsiniz. Daha fazla bilgi için bkz. Qradar'ı IoT için Microsoft Defender ile tümleştirme .
URI : /external/v1/alerts/<UUID>
PUT
Tür : JSON
Sorgu parametreleri :
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
UUID
İşlemek veya işlemek ve öğrenmek istediğiniz uyarının evrensel benzersiz tanımlayıcısını (UUID) tanımlar.
/api/v1/alerts/7903F632-H7EJ-4N69-F40F-4B1E689G00Q0
Gerekli
Gövde parametreleri
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
Eylem
Dize
veya handle
handleAndLearn
Gerekli
İstek örneği
{
"action": "handle"
}
Tür : JSON
Cihazları temsil eden JSON nesneleri dizisi.
Yanıt alanları :
Ad
Tür
Gerekli / İsteğe Bağlı
Açıklama
içerik / hata
Dize
Gerekli
İstek başarılı olursa içerik özelliği görüntülenir. Aksi takdirde hata özelliği görüntülenir.
Olası içerik değerleri :
Durum kodu
İleti
Açıklama
200
Uyarı güncelleştirme isteği başarıyla tamamlandı.
Güncelleştirme isteği başarıyla tamamlandı. Yorum yok.
200
Uyarı zaten işlendi (tanıtıcı ).
Uyarı için bir tanıtıcı isteği alındığında uyarı zaten işlendi. Uyarı işlenmeye devam eder .
200
Uyarı zaten işlendi ve öğrenildi (handleAndLearn ).
Uyarı zaten işlendi ve handleAndLearn isteği alındığında öğrenildi. Uyarı , handledAndLearn durumunda kalır.
200
Uyarı zaten işlendi (işlendi ). Uyarı üzerinde handle and learn (handleAndLearn ) gerçekleştirildi.
Bir handleAndLearn isteği alındığında uyarı zaten işlendi. Uyarı handleAndLearn olur.
200
Uyarı zaten işlendi ve öğrenildi (handleAndLearn ). Yoksayılan tanıtıcı isteği.
Uyarıyı işleme isteği alındığında uyarı zaten handleAndLearn olarak belirlenmişti. Uyarı handleAndLearn olarak kalır.
500
Geçersiz eylem.
Gönderilen eylem, uyarı üzerinde gerçekleştirilecek geçerli bir eylem değil.
500
Beklenmeyen bir hata oluştu.
Beklenmeyen bir hata oluştu. Sorunu çözmek için Teknik Destek'e başvurun.
500
Bu UUID için uyarı bulunamadığından istek yürütülemedi.
Belirtilen uyarı UUID sistemde bulunamadı.
Yanıt örneği: Başarılı
{
"content": "Alert update request finished successfully"
}
Yanıt örneği: Başarısız
{
"error": "Invalid action"
}
Tür : PUT
API'ler :
curl -k -X PUT -d '{"action": "<ACTION>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP_ADDRESS>/external/v1/alerts/<UUID>
Örnek :
curl -k -X PUT -d '{"action": "handle"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/alerts/1-1594550943000
maintenanceWindow (Uyarı dışlamaları oluşturma)
Uyarıların gönderilmeyacağı bakım pencerelerini yönetir. Uyarıları tetiklerken dışlanması gereken durdurma ve başlangıç zamanlarını, cihazları veya alt ağları tanımlamak ve güncelleştirmek ya da dışlanması gereken IoT altyapıları için Defender'ı tanımlamak ve güncelleştirmek için bu API'yi kullanın.
Örneğin, bakım penceresi sırasında kritik cihazlardaki kötü amaçlı yazılım uyarıları dışında tüm uyarıların uyarı teslimini durdurmak isteyebilirsiniz.
API ile maintenanceWindow
tanımlanan bakım pencereleri, şirket içi yönetim konsolunun Uyarı Dışlamaları penceresinde, aşağıdaki söz dizimine sahip adlı salt okunur bir dışlama kuralı olarak görünür: Maintenance-{token name}-{ticket ID}
.
Önemli
Bu API yalnızca bakım amacıyla ve sınırlı bir süre için desteklenir ve uyarı dışlama kuralları yerine kullanılması amaçlanmamıştır. Bu API'yi yalnızca bir kerelik, geçici bakım işlemleri için kullanın.
URI : /external/v1/maintenanceWindow
POST
Yeni bir bakım penceresi oluşturur.
Gövde parametreleri :
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
ticketId
Dize. Kullanıcının sistemlerindeki bakım bileti kimliğini tanımlar. Bilet kimliğinin var olan bir açık pencereye bağlı olmadığından emin olun.
2987345p98234
Gerekli
Ttl
Pozitif tamsayı. Bakım penceresinin süresi olan TTL'yi (yaşam süresi) dakika cinsinden tanımlar. Tanımlanan süre tamamlandıktan sonra bakım penceresi sona erer ve sistem yeniden normal davranır.
180
Gerekli
Motor
Dizelerin JSON dizisi. Bakım penceresi sırasında uyarıların engellendiği altyapıyı tanımlar. Olası değerler: - ANOMALY
- MALWARE
- OPERATIONAL
- POLICY_VIOLATION
- PROTOCOL_VIOLATION
ANOMALY,OPERATIONAL
İsteğe Bağlı
sensorId'ler
Dizelerin JSON dizisi. Bakım penceresi sırasında uyarıların gizlenmesi gereken algılayıcıları tanımlar. Bu algılayıcı kimliklerini gereçler (OT algılayıcı gereçlerini yönetme) API'sinden alabilirsiniz.
1,35,63
İsteğe Bağlı
Alt ağ
Dizelerin JSON dizisi. Bakım penceresi sırasında gelen uyarıların gizlenmesi için alt ağları tanımlar. Her alt ağı bir CIDR gösteriminde tanımlayın.
192.168.0.0/16,138.136.80.0/14,112.138.10.0/8
İsteğe Bağlı
Durum kodu
İleti
Açıklama
201 (Oluşturuldu)
-
Eylem başarıyla tamamlandı.
400 (Hatalı İstek)
Bilet Kimliği Yok
API isteğinde bir ticketId
değer eksikti.
400 (Hatalı İstek)
Geçersiz TTL
API isteği pozitif olmayan veya sayısal olmayan bir TTL değeri içeriyor.
400 (Hatalı İstek)
İstek ayrıştırılamıyor.
Yanlış parametreler veya geçersiz değerler gibi gövdeyi ayrıştırma sorunu.
400 (Hatalı İstek)
Aynı parametrelere sahip bakım penceresi zaten var.
Aynı ayrıntılara sahip mevcut bir bakım penceresi zaten mevcut olduğunda görüntülenir.
404 (Bulunamadı)
Bilinmeyen algılayıcı kimliği
İstekte listelenen algılayıcılardan biri yok.
409 (Çakışma)
Bilet kimliği zaten açık bir pencereye sahip.
Bilet kimliği başka bir açık bakım penceresine bağlanır.
500 (İç Sunucu Hatası)
-
Diğer beklenmeyen hatalar.
Tür : 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
Örnek :
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
Var olan bir bakım penceresini kapatır.
Sorgu parametreleri :
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
ticketId
Kullanıcının sistemlerindeki bakım bileti kimliğini tanımlar. Bilet kimliğinin var olan bir açık pencereye bağlı olduğundan emin olun.
2987345p98234
Gerekli
Hata kodları :
Kod
İleti
Açıklama
200 (Tamam)
-
Eylem başarıyla tamamlandı.
400 (Hatalı İstek)
Bilet Kimliği Yok
İstekte ticketId parametresi eksik.
404 (Bulunamadı) :
Bakım penceresi bulunamadı.
Bilet kimliği açık bir bakım penceresine bağlı değil.
500 (İç Sunucu Hatası)
-
Diğer beklenmeyen hatalar.
Tür : DELETE
API :
curl -k -X DELETE -d '{"ticketId": "<TICKET_ID>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
Örnek :
curl -k -X DELETE -d '{"ticketId": "a5fe99c-d914-4bda-9332-307384fe40bf"}' -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" https://127.0.0.1/external/v1/maintenanceWindow
GET
Bakım pencerelerini işlemek için bu API kullanılarak gerçekleştirilen tüm açık (POST ), kapatma (DELETE ) ve güncelleştirme (PUT ) eylemlerinin günlüğünü alın. T
Sorgu parametreleri :
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
fromDate
Günlükleri önceden tanımlanmış tarih ve sonraki tarihlerden filtreler. Biçimi şeklindedir YYYY-MM-DD
.
2022-08-10
İsteğe Bağlı
toDate
Günlükleri önceden tanımlanmış tarihe kadar filtreler. Biçimi şeklindedir YYYY-MM-DD
.
2022-08-10
İsteğe Bağlı
ticketId
Belirli bir bilet kimliğiyle ilgili günlükleri filtreler.
9a5fe99c-d914-4bda-9332-307384fe40bf
İsteğe Bağlı
tokenName
Belirli bir belirteç adıyla ilgili günlükleri filtreler.
üç aylık akıl sağlığı penceresi
İsteğe Bağlı
Hata kodları :
Kod
İleti
Açıklama
200
Tamam
Eylem başarıyla tamamlandı.
204:
İçerik Yok
Gösterilecek veri yok.
400
Hatalı İstek
Tarih biçimi yanlış.
500
İç Sunucu Hatası
Diğer beklenmeyen hatalar.
Tür : JSON
Bakım penceresi işlemlerini temsil eden JSON nesneleri dizisi.
Yanıt yapısı :
Ad
Tür
Null atanabilir / Boş değer atanamaz
Değer listesi
id
Uzun tamsayı
Null atanamaz
Geçerli günlük için iç kimlik
Datetime
Dize
Null atanamaz
Etkinliğin gerçekleştiği saat, örneğin: 2022-04-23T18:25:43.511Z
ticketId
Dize
Null atanamaz
Bakım penceresi kimliği. Örnek: 9a5fe99c-d914-4bda-9332-307384fe40bf
tokenName
Dize
Null atanamaz
Bakım penceresi belirteç adı. Örnek: quarterly-sanity-window
Motor
Dize dizisi
Null Atanabilir
Bakım penceresi oluşturma sırasında sağlanan bakım penceresinin uygulandığı altyapılar: Protocol Violation
, Policy Violation
, Malware
, Anomaly
veya Operational
sensorId'ler
Dize dizisi
Null Atanabilir
Bakım penceresi oluşturma sırasında sağlanan bakım penceresinin uygulandığı algılayıcılar.
Alt ağ
Dize dizisi
Null Atanabilir
Bakım penceresi oluşturma sırasında sağlanan bakım penceresinin uygulandığı alt ağlar.
Ttl
Sayısal
Null Atanabilir
Bakım penceresi oluşturma veya güncelleştirme sırasında sağlanan Bakım penceresinin Yaşam Süresi (TTL).
Operationtype
Dize
Boş değer atanamaz
Aşağıdaki değerlerden biri: OPEN
, UPDATE
ve CLOSE
Tür : GET
API :
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v1/maintenanceWindow?fromDate=&toDate=&ticketId=&tokenName='
Örnek :
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
parametresini değiştirerek ttl
bakım işlemini başlattıktan sonra bakım penceresi süresini güncelleştirmenizi sağlar. Yeni süre tanımı öncekini geçersiz kılar.
Bu yöntem, şu anda yapılandırılmış olan süreden daha uzun bir süre ayarlamak istediğinizde kullanışlıdır. Örneğin, başlangıçta 180 dakika tanımladıysanız, 90 dakika geçtiyse ve 30 dakika daha eklemek istiyorsanız, süre sayısını sıfırlamak için 120
dakika olarak güncelleştirinttl
.
Sorgu parametreleri :
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
ticketId
Dize. Kullanıcının sistemlerindeki bakım bileti kimliğini tanımlar.
2987345p98234
Gerekli
Ttl
Pozitif tamsayı. Pencerenin süresini dakika cinsinden tanımlar.
210
Gerekli
Hata kodları :
Kod
İleti
Açıklama
200 (Tamam)
-
Eylem başarıyla tamamlandı.
400 (Hatalı İstek)
Bilet Kimliği Yok
İstekte bir ticketId
değer eksik.
400 (Hatalı İstek)
Geçersiz TTL
Tanımlanan TTL sayısal değil veya pozitif bir tamsayı değil.
400 (Hatalı İstek)
İstek ayrıştırılamıyor
İstekte bir ttl
parametre değeri eksik.
404 (Bulunamadı)
Bakım penceresi bulunamadı
Bilet kimliği açık bir bakım penceresine bağlı değil.
500 (İç Sunucu Hatası)
-
Diğer beklenmeyen hatalar.
Tür : PUT
API :
curl -k -X PUT -d '{"ticketId": "<TICKET_ID>",ttl": "<TIME_TO_LIVE>"}' -H "Authorization: <AUTH_TOKEN>" https://<IP address>/external/v1/maintenanceWindow
Örnek :
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 (Uyarı iste PCAP)
Uyarıyla ilgili bir PCAP dosyası istemek için bu API'yi kullanın.
URI : /external/v2/alerts/
GET
Sorgu parametreleri :
Ad
Açıklama
Örnek
Gerekli / İsteğe Bağlı
id
Şirket içi yönetim konsolundan uyarı kimliği
/external/v2/alerts/pcap/<id>
Gerekli
Tür : JSON
İşlem durumu ayrıntılarını içeren ileti dizesi:
Durum kodu
İleti
Açıklama
200 (Tamam)
-
İstenen PCAP dosyası hakkındaki verileri içeren JSON nesnesi. Daha fazla bilgi için bkz . Veri alanları .
500 (İç Sunucu Hatası)
Uyarı bulunamadı
Sağlanan uyarı kimliği şirket içi yönetim konsolunda bulunamadı.
500 (İç Sunucu Hatası)
xsense kimliği için belirteç alınırken hata oluştu <number>
Belirtilen algılayıcı kimliği için algılayıcının belirteci alırken bir hata oluştu
500 (İç Sunucu Hatası)
-
Diğer beklenmeyen hatalar.
Veri alanları
Ad
Tür
Null atanabilir / Boş değer atanamaz
Değer listesi
id
Sayısal
Boş değer atanamaz
Şirket içi yönetim konsolu uyarı kimliği
xsenseId
Sayısal
Boş değer atanamaz
Algılayıcı kimliği
xsenseAlertId
Sayısal
Boş değer atanamaz
Algılayıcı konsolu uyarı kimliği
downloadUrl
Dize
Boş değer atanamaz
PCAP dosyasını indirmek için kullanılan URL
token
Dize
Boş değer atanamaz
PCAP dosyası indirilirken kullanılacak algılayıcının belirteci
Yanıt örneği: Başarılı
{
"downloadUrl": "https://10.1.0.2/api/v2/alerts/pcap/1",
"xsenseId": 1,
"token": "d2791f58-2a88-34fd-ae5c-2651fe30a63c",
"id": 1,
"xsenseAlertId": 1
}
Yanıt örneği: Hata
{
"error": "alert not found"
}
Tür : GET
API'ler
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<IP_ADDRESS>/external/v2/alerts/pcap/<ID>'
*
Örnek :
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://10.1.0.1/external/v2/alerts/pcap/1'
Sonraki adımlar
Daha fazla bilgi için bkz. IoT için Defender API başvurusuna genel bakış .