Karşıya yükleme API'siyle tehdit bilgilerini Microsoft Sentinel'e aktarma (Önizleme)

Microsoft Sentinel'de karşıya yükleme API'siyle kullanmak üzere tehdit bilgilerini içeri aktarın. İster tehdit bilgileri platformu ister özel bir uygulama kullanıyor olun, bu belgeyi İpucunuzu karşıya yükleme API'sine bağlama başlığı altındaki yönergelere ek başvuru olarak kullanın. API'ye bağlanmak için veri bağlayıcısını yüklemek gerekmez. İçeri aktarabileceğiniz tehdit bilgileri, güvenliğin aşılmasına ilişkin göstergeleri ve diğer STIX etki alanı nesnelerini içerir.

Yapılandırılmış Tehdit Bilgileri İfadesi (STIX), siber tehdidi ve gözlemlenebilir bilgileri ifade etmek için kullanılan bir dildir. Aşağıdaki etki alanı nesneleri için gelişmiş destek, karşıya yükleme API'sine eklenir:

• gösterge
• saldırı düzeni
• tehdit aktörü
• identity
• ilişki

Daha fazla bilgi için bkz . STIX'e giriş.

API'yi çağır

Karşıya yükleme API'sine yapılan çağrı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 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 Karşıya yükleme API'siyle tehdit bilgilerini bağlama kurulumunun bir parçası olarak temel adımları inceleyin.

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.

Alınan belirtecin (v1.0 veya v2.0) sürümü, uygulamanızın accessTokenAcceptedVersion çağırdığı API'nin uygulama bildirimindeki ö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. 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 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=2024-02-01-preview
Uç nokta: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
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:

STIX biçim belirtimini kullanarak STIX nesneleri dizisini oluşturun. STIX özellik belirtimlerinden bazıları, ilgili STIX belge bölümlerine bağlantılar ile kolaylık sağlamak için burada genişletilmiştir. Ayrıca, STIX için geçerli olan bazı özelliklerin Microsoft Sentinel'de karşılık gelen nesne şeması özelliklerine sahip olmadığını unutmayın.

Ortak özellikler

Karşıya yükleme API'siyle içeri aktardığınız tüm nesneler bu ortak özellikleri paylaşır.

Daha fazla bilgi için bkz . STIX ortak özellikleri.

Gösterge

Daha fazla bilgi için bkz . STIX göstergesi.

Saldırı düzeni

Daha fazla bilgi için bkz . STIX saldırı düzeni.

Kimlik

Daha fazla bilgi için bkz . STIX kimliği.

Tehdit aktörü

Daha fazla bilgi için bkz . STIX tehdit aktörü.

İlişki

Daha fazla bilgi için bkz . STIX ilişkisi.

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 nesne.
• 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 nesne en yüksek aktarım hızıdır.

Örnek gösterge isteği gövdesi

Aşağıdaki örnek, STIX belirtiminde iki göstergenin nasıl temsil yapılacağını gösterir. Test Indicator 2 Eşlenmiş nesne işaretlemesi ile beyaz olarak ayarlanmış Trafik Işığı Protokolü 'ni (TLP) vurgular ve açıklamasını ve etiketlerini İngilizce olarak netleştirin.

{
    "sourcesystem": "test", 
    "stixobjects":[
        {
            "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 STIX nesneleri 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 nesne 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."
            ]
        }
    ]
}

Nesneler bir dizi olarak gönderilir, bu nedenle recordIndex ile 0başlar.

Diğer örnekler

Örnek gösterge

Bu örnekte, gösterge common özelliğinde object_marking_refs kullanılarak marking-definition--089a6ecb-cc15-43cc-9494-767639779123 yeşil TLP ile işaretlenir. ve'in toxicityrank daha fazla uzantı özniteliği de eklenir. Bu özellikler göstergeler için Microsoft Sentinel şemasında olmasa da, bu özelliklere sahip bir nesne alındığında hata tetiklemez. Özelliklere yalnızca çalışma alanında başvurulmuyor veya dizine alınmıyor.

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "indicator",
          "spec_version": "2.1",
          "id": "indicator--12345678-71a2-445c-ab86-927291df48f8",
          "created": "2010-02-26T18:29:07.778Z",
          "modified": "2011-02-26T18:29:07.778Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "name": "Indicator 2.1 Test",
          "description": "TS ID: 35766958; iType: bot_ip; State: active; Org: 52.3667; Source: Emerging Threats - Compromised",
          "indicator_types": [
            "threatstream-severity-low",
            "threatstream-confidence-80"
          ],
          "pattern": "[ipv4-addr:value = '94.102.52.185']",
          "pattern_type": "stix",
          "pattern_version": "2.1",
          "valid_from": "2015-02-26T18:29:07.778Z",
          "valid_until": "2016-02-26T18:29:07.778Z",
          "kill_chain_phases": [
            {
              "kill_chain_name": "lockheed-martin-cyber-kill-chain",
              "phase_name": "reconnaissance"
            }
          ]
        }
    ]
}

Örnek saldırı düzeni

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
        {
          "type": "attack-pattern",
          "spec_version": "2.1",
          "id": "attack-pattern--fb6aa549-c94a-4e45-b4fd-7e32602dad85",
          "created": "2015-05-15T09:12:16.432Z",
          "modified": "2015-05-20T09:12:16.432Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": false,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "external_references": [
            {
              "source_name": "capec",
              "description": "spear phishing",
              "external_id": "CAPEC-163"
            }
          ],
          "name": "Attack Pattern 2.1",
          "description": "menuPass appears to favor spear phishing to deliver payloads to the intended targets. While the attackers behind menuPass have used other RATs in their campaign, it appears that they use PIVY as their primary persistence mechanism.",
          "kill_chain_phases": [
            {
              "kill_chain_name": "mandiant-attack-lifecycle-model",
              "phase_name": "initial-compromise"
            }
          ],
          "aliases": [
            "alias_1",
            "alias_2"
          ]
        }
    ]
}

Tehdit aktörü ve kimlikle örnek ilişki

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "identity",
          "spec_version": "2.1",
          "id": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "created": "2016-08-23T18:05:49.307Z",
          "modified": "2016-08-23T18:05:49.307Z",
          "name": "Identity 2.1",
          "description": "Disco Team is the name of an organized threat actor crime-syndicate.",
          "identity_class": "organization",
          "contact_information": "disco-team@stealthemail.com",
          "roles": [
            "administrators"
          ],
          "sectors": [
            "education"
          ],
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "type": "threat-actor",
          "spec_version": "2.1",
          "id": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "created": "2014-11-19T23:39:03.893Z",
          "modified": "2014-11-19T23:39:03.893Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "name": "Threat Actor 2.1",
          "description": "This organized threat actor group operates to create profit from all types of crime.",
          "threat_actor_types": [
            "crime-syndicate"
          ],
          "aliases": [
            "Equipo del Discoteca"
          ],
          "first_seen": "2014-01-19T23:39:03.893Z",
          "last_seen": "2014-11-19T23:39:03.893Z",
          "roles": [
            "agent"
          ],
          "goals": [
            "Steal Credit Card Information"
          ],
          "sophistication": "expert",
          "resource_level": "organization",
          "primary_motivation": "personal-gain",
          "secondary_motivations": [
            "dominance"
          ],
          "personal_motivations": [
            "revenge"
          ]
        },
        {
          "type": "relationship",
          "spec_version": "2.1",
          "id": "relationship--a2e3efb5-351d-4d46-97a0-6897ee7c77a0",
          "created": "2020-02-29T18:01:28.577Z",
          "modified": "2020-02-29T18:01:28.577Z",
          "relationship_type": "attributed-to",
          "description": "Description Relationship 2.1",
          "source_ref": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "target_ref": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "start_time": "2020-02-29T18:01:28.577Z",
          "stop_time": "2020-03-01T18:01:28.577Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        }
    ]
}

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