Şirket içi yönetim konsolları için uyarı yönetimi API'si başvurusu

Makale
06/01/2023

Bu makalede, IoT şirket içi yönetim konsolları için Microsoft Defender için desteklenen uyarı yönetimi REST API'leri listelenir.

uyarılar (Uyarı bilgilerini alma)

Ş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ı

Not

Site ve bölge kimliğiniz olmayabilir. Bu durumda, önce site ve bölge kimliğini almak için tüm cihazları sorgula. Daha fazla bilgi için bkz . Şirket içi yönetim konsolları için Tümleştirme API'si başvurusu (Genel önizleme).

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 `handlehandleAndLearn`	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ış.

Şirket içi yönetim konsolları için uyarı yönetimi API'si başvurusu

uyarılar (Uyarı bilgilerini alma)

GET

UUID (Uyarıları UUID'ye göre yönetme)

PUT

maintenanceWindow (Uyarı dışlamaları oluşturma)

POST

DELETE

GET

PUT

pcap (Uyarı iste PCAP)

GET

Sonraki adımlar

Ek kaynaklar