Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
Microsoft Sentinel yükleme göstergeleri API'si, tehdit bilgileri platformlarının veya özel uygulamaların STIX biçimindeki risk göstergelerini Microsoft Sentinel bir çalışma alanına aktarmasına izin verdi. Bu belge, eski API'ye başvuru görevi görür.
Önemli
Bu API ÖNİzLEME aşamasındadır ancak artık önerilmez. Tehdit bilgilerini karşıya yüklemek için önizlemede yeni STIX nesneleri API'sini kullanın. Daha fazla bilgi için bkz. STIX nesneleri API'si. Azure Önizleme Ek Koşulları beta, önizleme veya henüz genel kullanıma sunulmamış Azure özellikler için geçerli olan ek yasal koşulları içerir.
Karşıya yükleme göstergeleri API çağrısının beş bileşeni vardır:
- İstek URI'si
- HTTP isteği ileti üst bilgisi
- HTTP isteği ileti gövdesi
- İsteğe bağlı olarak HTTP yanıt iletisi üst bilgisini işleme
- İsteğe bağlı olarak HTTP yanıt iletisi gövdesini işleme
İstemci uygulamanızı Microsoft Entra ID kaydetme
Microsoft Sentinel kimlik doğrulaması yapmak için, karşıya yükleme göstergeleri API'sine yönelik istek geçerli bir Microsoft Entra erişim belirteci gerektirir. Uygulama kaydı hakkında daha fazla bilgi için bkz. Uygulamayı Microsoft kimlik platformu kaydetme veya yükleme göstergeleri API veri bağlayıcısı kurulumunun bir parçası olarak temel adımlara bakın.
İzinler
Bu API, çağıran Microsoft Entra uygulamasına çalışma alanı düzeyinde Microsoft Sentinel katkıda bulunan rolü verilmesini gerektirir.
İsteği oluşturma
Bu bölümde, daha önce ele alınan beş bileşenin ilk üçü ele alınıyor. İlk olarak, istek iletisi üst bilginizi derlemek için kullandığınız erişim belirtecini Microsoft Entra ID almanız gerekir.
Erişim belirteci alma
OAuth 2.0 kimlik doğrulaması ile bir Microsoft Entra erişim belirteci alın. V1.0 ve V2.0 , API tarafından kabul edilen geçerli belirteçlerdir.
Uygulamanızın aldığı belirtecin sürümü (v1.0 veya v2.0), uygulamanızın çağırdığı API'nin accessTokenAcceptedVersion özelliği tarafından belirlenir. 1 olarak ayarlanırsa accessTokenAcceptedVersion , uygulamanız bir v1.0 belirteci alır.
Bir v1.0 veya v2.0 erişim belirteci almak için Microsoft Kimlik Doğrulama Kitaplığı MSAL kullanın. Rest API'ye istekleri aşağıdaki biçimde de gönderebilirsiniz:
- YAYINLA
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Microsoft Entra Uygulamasını kullanmaya yönelik üst bilgiler:
- grant_type: "client_credentials"
- client_id: {Microsoft Entra Uygulamasının İstemci Kimliği}
- client_secret: {Microsoft Entra Uygulamasının gizli dizisi}
- Kapsam:
"https://management.azure.com/.default"
Uygulama bildiriminde 1 olarak ayarlanırsa accessTokenAcceptedVersion , uygulamanız v2 belirteç uç noktasını çağırsa bile bir v1.0 erişim belirteci alır.
Kaynak/kapsam değeri belirtecin hedef kitlesidir. Bu API yalnızca aşağıdaki hedef kitleleri kabul eder:
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
İstek iletisini derleme
Eski API'nin iki sürümü vardı. Uç noktaya bağlı olarak, istek gövdesinde farklı bir dizi adı gerekiyordu. Bu, mantıksal uygulama bağlayıcı eyleminin iki sürümüyle de temsil edildi.
- Bağlayıcı eylem adı: Tehdit Bilgileri - Risk Göstergelerini Karşıya Yükleme (Kullanım Dışı)
- Bitiş noktası:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Gösterge dizisi adı:
value
- Bitiş noktası:
- Bağlayıcı eylem adı: Tehdit Bilgileri - Güvenliğin Aşılmasına yönelik Göstergeleri Karşıya Yükleme (V2) (Önizleme)
- Bitiş noktası:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Gösterge dizisi adı:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Bitiş noktası:
İstek URI'si
API sürümü oluşturma: api-version=2022-07-01
Bitiş noktası: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Yöntem: POST
İstek üst bilgisi
Authorization: OAuth2 taşıyıcı belirtecini içerir
Content-Type: application/json
İstek gövdesi
Gövde için JSON nesnesi aşağıdaki alanları içerir:
| Alan adı | Veri Türü | Açıklama |
|---|---|---|
| SourceSystem (gerekli) | dize | Kaynak sistem adınızı tanımlayın. Değer Microsoft Sentinel kısıtlandı. |
| göstergeler (gerekli) | dizi | STIX 2.0 veya 2.1 biçimindeki gösterge dizisi |
StIX 2.1 gösterge biçimi belirtimini kullanarak gösterge dizisini oluşturun. Önemli bölümlerin bağlantıları sayesinde kolaylık sağlamak için burada daraltılmıştır. Ayrıca, STIX 2.1 için geçerli olan bazı özelliklerin Microsoft Sentinel karşılık gelen gösterge özelliklerine sahip olmadığını unutmayın.
| Özellik Adı | Tür | Açıklama |
|---|---|---|
id (gerekli) |
dize | Göstergeyi tanımlamak için kullanılan kimlik. Oluşturmayla ilgili belirtimler için bölüm id bakın. Biçim şuna benzer: indicator--<UUID> |
spec_version (isteğe bağlı) |
dize | STIX göstergesi sürümü. Bu değer STIX belirtiminde gereklidir, ancak bu API yalnızca STIX 2.0 ve 2.1'i desteklediğinden, bu alan ayarlanmadığında API varsayılan olarak 2.1 |
type (gerekli) |
dize | Bu özelliğin değeri olmalıdırindicator. |
created (gerekli) |
Zaman damgası | Bu ortak özelliğin belirtimleri için bölüm 3.2'ye bakın. |
modified (gerekli) |
Zaman damgası | Bu ortak özelliğin belirtimleri için bölüm 3.2'ye bakın. |
name (isteğe bağlı) |
dize | Göstergeyi tanımlamak için kullanılan ad. Üreticiler, ürünlerin ve analistlerin bu göstergenin gerçekte ne yaptığını anlamasına yardımcı olmak için bu özelliği sağlamalıdır . |
description (isteğe bağlı) |
dize | Gösterge hakkında daha fazla ayrıntı ve bağlam sağlayan bir açıklama, potansiyel olarak amacını ve temel özelliklerini içerir. Üreticiler, ürünlerin ve analistlerin bu göstergenin gerçekte ne yaptığını anlamasına yardımcı olmak için bu özelliği sağlamalıdır . |
indicator_types (isteğe bağlı) |
dize listesi | Bu gösterge için bir kategori kümesi. Bu özelliğin değerleri indicator-type-ov değerinden gelmelidir |
pattern (gerekli) |
dize | Bu göstergenin algılama deseni STIX Deseni veya SNORT, YARA gibi başka bir uygun dil olarak ifade edilebilir. |
pattern_type (gerekli) |
dize | Bu göstergede kullanılan desen dili. Bu özelliğin değeri desen türlerindengelmelidir. Bu özelliğin değeri, desen özelliğine dahil edilen desen verilerinin türüyle eşleşmelidir . |
pattern_version (isteğe bağlı) |
dize | Desen özelliğindeki veriler için kullanılan desen dilinin, desen özelliğine dahil edilen desen verilerinin türüyle eşleşmesi gereken sürümü. Resmi belirtimi olmayan desenler için, desenin çalıştığı bilinen derleme veya kod sürümü kullanılmalıdır. STIX desen dili için nesnenin belirtim sürümü varsayılan değeri belirler. Diğer diller için varsayılan değer, bu nesnenin oluşturulduğu sırada desen dilinin en son sürümü olmalıdır . |
valid_from (gerekli) |
Zaman damgası | Bu göstergenin ilişkili veya temsil ettiği davranışların geçerli bir göstergesi olarak kabul edildiği saat. |
valid_until (isteğe bağlı) |
Zaman damgası | Bu göstergenin artık ilişkili veya temsil ettiği davranışların geçerli bir göstergesi olarak kabul edilmemesi gereken zaman. valid_until özelliği atlanırsa göstergenin geçerli olduğu en son saatle ilgili bir kısıtlama yoktur. Bu zaman damgası, valid_from zaman damgasından büyük olmalıdır . |
kill_chain_phases (isteğe bağlı) |
dize listesi | Bu göstergenin karşılık gelen sonlandırma zinciri aşamaları. Bu özelliğin değeri Sonlandırma Zinciri Aşamasındangelmelidir. |
created_by_ref (isteğe bağlı) |
dize | created_by_ref özelliği, bu nesneyi oluşturan varlığın ID özelliğini belirtir. Bu öznitelik atlanırsa, bu bilgilerin kaynağı tanımlanmamış olur. Anonim kalmak isteyen nesne oluşturucuları için bu değeri tanımsız tutun. |
revoked (isteğe bağlı) |
Boolean | İptal edilen nesneler artık nesne oluşturucusu tarafından geçerli kabul edilmez. Bir nesneyi iptal etme kalıcıdır; bu nesnenin id gelecekteki sürümleri oluşturulmamalıdır.Bu özelliğin varsayılan değeri false'tur. |
labels (isteğe bağlı) |
dize listesi |
labels özelliği, bu nesneyi açıklamak için kullanılan bir terim kümesini belirtir. Terimler kullanıcı tanımlı veya güven grubu tanımlıdır. Bu etiketler Microsoft Sentinel'de Etiketler olarak görüntülenir. |
confidence (isteğe bağlı) |
tam sayı | özelliği, confidence oluşturucunun verilerinin doğruluğunda sahip olduğu güveni tanımlar. Güvenilirlik değeri 0-100 aralığındaki bir sayı olmalıdır .Ek A , bu ölçeklerden birinde güvenilirlik değeri sunarken kullanılması gereken diğer güvenilirlik ölçekleriyle normatif eşlemelerden oluşan bir tablo içerir. Güvenilirlik özelliği yoksa, içeriğin güvenilirliği belirtilmez. |
lang (isteğe bağlı) |
dize |
lang özelliği, bu nesnedeki metin içeriğinin dilini tanımlar. Mevcut olduğunda, RFC5646 uyumlu bir dil kodu olmalıdır. Özellik mevcut değilse içeriğin dili (İngilizce) olur en .Nesne türü çevrilebilir metin özellikleri (örneğin, ad, açıklama) içeriyorsa bu özellik mevcut olmalıdır . Bu nesnedeki tek tek alanların dili, ayrıntılı işaretlerde özelliğini geçersiz kabilir lang (bkz. bölüm 7.2.3). |
object_marking_refs (TLP dahil isteğe bağlı) |
dize listesi | özelliği, object_marking_refs bu nesne için geçerli olan işaretleme tanımı nesnelerinin kimlik özelliklerinin listesini belirtir. Örneğin, gösterge kaynağının duyarlılığını ayarlamak için Trafik Işığı Protokolü (TLP) işaretleme tanımı kimliğini kullanın. TLP içeriğinde hangi işaretleme tanımı kimliklerinin kullanılacağına ilişkin ayrıntılar için bkz . bölüm 7.2.1.4Bazı durumlarda, nadir olsa da tanımları işaretlemek paylaşım veya işleme yönergeleriyle işaretlenebilir. Bu durumda, bu özellik aynı İşaretleme Tanımı nesnesine başvuru içermemelidir (başka bir ifadeyle döngüsel başvuru içeremez). Veri işaretlerinin daha fazla tanımı için bölüm 7.2.2'ye bakın. |
external_references (isteğe bağlı) |
nesne listesi | özelliği, external_references STIX olmayan bilgilere başvuran dış başvuruların listesini belirtir. Bu özellik, diğer sistemlerdeki kayıtlara bir veya daha fazla URL, açıklama veya kimlik sağlamak için kullanılır. |
granular_markings (isteğe bağlı) |
ayrıntılı işaretleme listesi | özelliği, granular_markings göstergenin bölümlerini farklı şekilde tanımlamaya yardımcı olur. Örneğin, gösterge dili İngilizcedir, en ancak açıklama Almanca'dır de.Bazı durumlarda, nadir olsa da tanımları işaretlemek paylaşım veya işleme yönergeleriyle işaretlenebilir. Bu durumda, bu özellik aynı İşaretleme Tanımı nesnesine başvuru içermemelidir (başka bir deyişle, döngüsel başvuru içeremez). Veri işaretlerinin daha fazla tanımı için bölüm 7.2.3'e bakın. |
Yanıt iletisini işleme
Yanıt üst bilgisi bir HTTP durum kodu içerir. API çağrı sonucunu yorumlama hakkında daha fazla bilgi için bu tabloya başvurun.
| Durum kodu | Açıklama |
|---|---|
| 200 | Başarı. Bir veya daha fazla gösterge başarıyla doğrulandığında ve yayımlandığında API 200 döndürür. |
| 400 | Hatalı biçim. İstekteki bir şey doğru biçimlendirilmemiş. |
| 401 | Yetki -siz. |
| 404 | Dosya bulunamadı. Bu hata genellikle çalışma alanı kimliği bulunamadığında oluşur. |
| 429 | Bir dakika içindeki istek sayısı aşıldı. |
| 500 | Sunucu hatası. Genellikle API veya Microsoft Sentinel hizmetlerinde bir hata. |
Yanıt gövdesi, JSON biçiminde bir hata iletileri dizisidir:
| Alan adı | Veri Türü | Açıklama |
|---|---|---|
| Hata | Hata nesneleri dizisi | Doğrulama hatalarının listesi |
Hata nesnesi
| Alan adı | Veri Türü | Açıklama |
|---|---|---|
| recordIndex | Int | İstekteki göstergelerin dizini |
| errorMessages | Dize dizisi | Yaygın hata iletileri |
API için azaltma sınırları
Tüm sınırlar kullanıcı başına uygulanır:
- İstek başına 100 gösterge.
- Dakikada 100 istek.
Sınırdan daha fazla istek varsa, yanıt üst bilgisinde aşağıdaki yanıt gövdesine sahip bir 429 http durum kodu döndürülür:
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
Azaltma hatası alınmadan önce dakikada yaklaşık 10.000 gösterge en yüksek aktarım hızıdır.
Örnek istek gövdesi
{
"sourcesystem": "test",
"indicators":[
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--10000003-71a2-445c-ab86-927291df48f8",
"name": "Test Indicator 1",
"created": "2010-02-26T18:29:07.778Z",
"modified": "2011-02-26T18:29:07.778Z",
"pattern": "[ipv4-addr:value = '172.29.6.7']",
"pattern_type": "stix",
"valid_from": "2015-02-26T18:29:07.778Z"
},
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52",
"created": "2023-01-01T18:29:07.778Z",
"modified": "2025-02-26T18:29:07.778Z",
"created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7",
"revoked": false,
"labels": [
"label 1",
"label 2"
],
"confidence": 55,
"lang": "en",
"external_references": [
{
"source_name": "External Test Source",
"description": "Test Report",
"external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f",
"url": "https://fabrikam.com//testreport.json",
"hashes": {
"SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
}
}
],
"object_marking_refs": [
"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
],
"granular_markings": [
{
"marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80",
"selectors": [ "description", "labels" ],
"lang": "en"
}
],
"name": "Test Indicator 2",
"description": "This is a test indicator to demo valid fields",
"indicator_types": [
"threatstream-severity-low", "threatstream-confidence-80"
],
"pattern": "[ipv4-addr:value = '192.168.1.1']",
"pattern_type": "stix",
"pattern_version": "2.1",
"valid_from": "2023-01-01T18:29:07.778Z",
"valid_until": "2025-02-26T18:29:07.778Z",
"kill_chain_phases": [
{
"kill_chain_name": "lockheed-martin-cyber-kill-chain",
"phase_name": "reconnaissance"
}
]
}
]
}
Doğrulama hatası içeren örnek yanıt gövdesi
Tüm göstergeler başarıyla doğrulanırsa, boş yanıt gövdesine sahip bir HTTP 200 durumu döndürülür.
Doğrulama bir veya daha fazla gösterge için başarısız olursa, yanıt gövdesi daha fazla bilgiyle döndürülür. Örneğin, dört göstergeli bir dizi gönderirseniz ve ilk üçü iyiyse ancak dördüncünün bir id alanı yoksa (gerekli bir alan), aşağıdaki gövdeyle birlikte bir HTTP durum kodu 200 yanıtı oluşturulur:
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
Göstergeler bir dizi olarak gönderilir, bu nedenle recordIndex konumunda 0başlar.
Sonraki adım
Bu API eskidir. Lütfen tehdit bilgilerini karşıya yüklemek için STIX nesneleri API'sini kullanmak üzere geçiş yapın. Daha fazla bilgi için bkz. STIX nesneleri API'si.