Tehdit bilgilerini Microsoft Sentinel'e aktarmak için karşıya yükleme göstergeleri API'sine (Önizleme) başvurma

  • Makale

Microsoft Sentinel karşıya yükleme göstergeleri API'si, tehdit bilgileri platformlarının veya özel uygulamaların STIX biçimindeki risk göstergelerini Bir Microsoft Sentinel çalışma alanına aktarmasına olanak tanır. API'yi Microsoft Sentinel karşıya yükleme göstergeleri API veri bağlayıcısıyla veya özel bir çözümün parçası olarak kullanmanız fark etmeksizin, bu belge bir başvuru görevi görür.

Önemli

Bu API şu anda ÖNİzLEME aşamasındadır. Azure Önizleme Ek Koşulları, beta, önizleme aşamasında olan veya henüz genel kullanıma sunulmamış Azure özellikleri 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:

  1. İstek URI'si
  2. HTTP isteği ileti üst bilgisi
  3. HTTP isteği ileti gövdesi
  4. İsteğe bağlı olarak HTTP yanıt iletisi üst bilgisini işleme
  5. İsteğe bağlı olarak HTTP yanıt iletisi gövdesini işleme

İstemci uygulamanızı Microsoft Entra ID ile kaydetme

Microsoft Sentinel'de kimlik doğrulaması yapmak için, karşıya yükleme göstergeleri API'sine yönelik istek için geçerli bir Microsoft Entra erişim belirteci gerekir. 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 Microsoft Entra Id'den erişim belirtecini 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 (v1.0 veya v2.0) sürümü, uygulamanızın çağırdığı API'nin uygulama bildirimindeki özelliği tarafından accessTokenAcceptedVersion 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'yi kullanın. Alternatif olarak, 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 App'in İstemci Kimliği}
  • client_secret: {Microsoft Entra App'in 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.net
  • https://management.azure.com/
  • https://management.azure.com

İstek iletisini derleme

İstek URI'si

API sürümü oluşturma: api-version=2022-07-01
Bitiş noktası: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?api-version=2022-07-01
Yöntem: POST

İstek üst bilgisi

Authorization: OAuth2 taşıyıcı belirtecini içerir
Content-Type: application/json

Request body

Gövde için JSON nesnesi aşağıdaki alanları içerir:

Alan adı Veri Türü Tanım
SourceSystem (gerekli) Dize Kaynak sistem adınızı tanımlayın. Değer Microsoft Sentinel kısıtlanmış.
Değer (gerekli) dizi STIX 2.0 veya 2.1 biçiminde bir gösterge dizisi

Önemli bölümlerin bağlantıları konusunda kolaylık sağlamak için burada daraltılmış olan STIX 2.1 gösterge biçimi belirtimini kullanarak gösterge dizisini oluşturun. StIX 2.1 için geçerli olan bazı özelliklerin Microsoft Sentinel'de ilgili gösterge özelliklerine sahip olmadığını da unutmayın.

Özellik Adı Tür Tanım
id (gerekli) Dize Göstergeyi tanımlamak için kullanılan kimlik. Oluşturma idhakkında belirtimler için bölüm 2.9'a bakın. Biçim şuna benzer indicator--<UUID>
spec_version (isteğe bağlı) Dize STIX gösterge 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) timestamp Bu ortak özelliğin belirtimleri için bölüm 3.2'ye bakın.
modified (gerekli) timestamp 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, potansiyel olarak amacını ve temel özelliklerini içeren bir açıklama.

Ü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ürlerinden gelmelidir.

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) timestamp Bu göstergenin ilgili veya temsil ettiği davranışların geçerli bir göstergesi olarak kabul edildiği saat.
valid_until (isteğe bağlı) timestamp Bu göstergenin 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ından gelmelidir.
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 idgelecekteki sürümleri oluşturulmamalıdır .

Bu özelliğin varsayılan değeri false'tur.
labels (isteğe bağlı) dize listesi özelliği, labels bu nesneyi tanımlamak 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ı) integer ö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çeklerine yönelik normatif eşlemeler tablosu 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 yoksa, 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 (isteğe bağlı, TLP dahil) dize listesi özelliği, object_marking_refs bu nesneye uygulanan işaretleme tanımı nesnelerinin kimlik özelliklerinin listesini belirtir. Örneğin, gösterge kaynağının duyarlılığını ayarlamak için Traffic Light Protocol (TLP) işaretleme tanımı kimliğini kullanın. TLP içeriği için hangi işaretleme tanımı kimliklerinin kullanılacağına ilişkin ayrıntılar için bkz. bölüm 7.2.1.4

Bazı durumlarda, yaygın olmasa 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 ayrıntılı 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, yaygın olmasa da tanımları işaretlemek paylaşım veya işleme yönergeleriyle işaretlenebilir. Bu durumda, bu özellik aynı İşaretleme Tanımı nesnesine herhangi bir başvuru içermemelidir (başka bir deyişle, döngüsel başvuru içeremez).

Veri işaretlerinin daha ayrıntılı 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ısı sonucunu yorumlama hakkında daha fazla bilgi için bu tabloya başvurun.

Durum kodu Tanım
200 Başarılı. 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 Yetkisiz.
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ü Tanım
hatalar Hata nesneleri dizisi Doğrulama hatalarının listesi

Hata nesnesi

Alan adı Veri Türü Tanım
recordIndex int İstekteki göstergelerin dizini
errorMessages Dize dizisi 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", 
    "value":[
        {
            "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övdesiyle 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 (gerekli alan) yoksa, 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 ile 0başlar.

Sonraki adımlar

Microsoft Sentinel'de tehdit bilgileriyle çalışma hakkında daha fazla bilgi edinmek için aşağıdaki makalelere bakın: