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

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.

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

Karşıya yükleme göstergeleri API'sinin iki sürümü vardır. Uç noktaya bağlı olarak, istek gövdesinde farklı bir dizi adı gerekir. Bu, mantıksal uygulama bağlayıcısı eyleminin iki sürümüyle de temsil edilir.

• Bağlayıcı eylem adı: Tehdit Bilgileri - Güvenliği Aşma Göstergelerini Karşıya Yükleme (Kullanım Dışı)

  • Uç nokta: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
  • Gösterge dizisi adı: value

    {
       "sourcesystem":"TIsource-example",
       "value":[]
    }
    

• Bağlayıcı eylem adı: Tehdit Bilgileri - Karşıya Yükleme Risk Göstergeleri (V2) (Önizleme)

  • Uç nokta: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Gösterge dizisi adı: indicators

    {
       "sourcesystem":"TIsource-example",
       "indicators":[]
    }
    

İstek URI'si

API sürümü oluşturma: api-version=2022-07-01
Uç nokta: 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

Request body

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

Ö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.

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.

Yanıt gövdesi, JSON biçiminde bir hata iletileri dizisidir:

Hata nesnesi

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ö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:

• Tehdit bilgilerini anlama
• Tehdit göstergeleriyle çalışma
• Tehditleri algılamak için eşleşen analiz kullanma
• Microsoft'un zeka akışını kullanma ve MDTI veri bağlayıcısını etkinleştirme