Referencia az örökölt feltöltési mutatók API-jára

A Microsoft Sentinel upload indicators API lehetővé tette a fenyegetésfelderítési platformok vagy egyéni alkalmazások számára, hogy STIX formátumban importálják a biztonsági rések mutatóit a Microsoft Sentinel-munkaterületre. Ez a dokumentum az örökölt API-ra való hivatkozásként szolgál.

A upload indicators API-hívás öt összetevőből áll:

1. A kérelem URI-ja
2. HTTP-kérelem üzenetfejléce
3. HTTP-kérés üzenettörzse
4. A HTTP-válaszüzenet fejlécének feldolgozása opcionálisan
5. A HTTP válaszüzenet törzsének feldolgozása opcionálisan

Ügyfélalkalmazás regisztrálása a Microsoft Entra-azonosítóval

A Microsoft Sentinel felé történő hitelesítéshez a feltöltési mutatók API-jára irányuló kéréshez érvényes Microsoft Entra hozzáférési jogkivonatra van szükség. Az alkalmazásregisztrációval kapcsolatos további információkért lásd: Alkalmazás regisztrálása a Microsoft Identitásplatform, vagy tekintse meg az alapvető lépéseket a feltöltési mutatók API-adatösszekötő beállításának részeként.

Engedélyek

Ez az API megköveteli, hogy a hívó Microsoft Entra-alkalmazás megkapja a Microsoft Sentinel közreműködői szerepkört a munkaterület szintjén.

A kérés létrehozása

Ez a szakasz a korábban tárgyalt öt összetevő közül az első háromat ismerteti. Először be kell szereznie a hozzáférési jogkivonatot a Microsoft Entra-azonosítóból, amelyet a kérésüzenet fejlécének összeállításához használ.

Hozzáférési jogkivonat beszerzése

Microsoft Entra hozzáférési jogkivonat beszerzése OAuth 2.0-hitelesítéssel. A V1.0 és a V2.0 az API által elfogadott érvényes jogkivonatok.

Az alkalmazás által kapott jogkivonat (1.0-s vagy 2.0-s verzió) verzióját az accessTokenAcceptedVersion alkalmazás által hívott API alkalmazásjegyzékében lévő tulajdonság határozza meg. Ha accessTokenAcceptedVersion 1 értékre van állítva, akkor az alkalmazás egy 1.0-s jogkivonatot kap.

A Microsoft Authentication Library MSAL használatával beszerezhet egy 1.0-s vagy 2.0-s verziós hozzáférési jogkivonatot. Vagy küldjön kéréseket a REST API-nak a következő formátumban:

• POSTA https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
• Fejlécek a Microsoft Entra App használatához:
• grant_type: "client_credentials"
• client_id: {A Microsoft Entra App ügyfél-azonosítója}
• client_secret: {a Microsoft Entra App titkos kódja}
• kiterjedés: "https://management.azure.com/.default"

Ha accessTokenAcceptedVersion az alkalmazásjegyzékben 1 érték van beállítva, az alkalmazás 1.0-s hozzáférési jogkivonatot kap annak ellenére, hogy meghívja a v2-jogkivonat végpontját.

Az erőforrás/hatókör értéke a jogkivonat célközönsége. Ez az API csak a következő célközönségeket fogadja el:

• https://management.core.windows.net/
• https://management.core.windows.net
• https://management.azure.com/
• https://management.azure.com

A kérelemüzenet összeállítása

Az örökölt API két verziója volt. A végponttól függően a kérelem törzsében eltérő tömbnévre volt szükség. Ezt a logikai alkalmazás összekötő műveletének két verziója is képviselte.

1. Összekötő műveletneve: Fenyegetésintelligencia – Biztonsági rések feltöltése (elavult)
   • Végpont: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
   • Jelzők neve: value

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

• Összekötő műveletneve: Fenyegetésintelligencia – Biztonsági rések (V2) feltöltése (előzetes verzió)
  • Végpont: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Jelzők neve: indicators

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

Kérés URI-ja

API-verziószámozás: api-version=2022-07-01
Végpont: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Módszer: POST

Kérelem fejléce

Authorization: Az OAuth2 tulajdonosi jogkivonatát tartalmazza
Content-Type: application/json

Kérés törzse

A törzs JSON-objektuma a következő mezőket tartalmazza:

Hozza létre a mutatótömböt a STIX 2.1 mutatóformátum-specifikációval, amelyet itt sűrítettünk össze, hogy kényelmes legyen a fontos szakaszokra mutató hivatkozásokkal. Vegye figyelembe, hogy egyes tulajdonságok, amelyek az STIX 2.1-ben érvényesek, nem rendelkeznek megfelelő mutatótulajdonságok a Microsoft Sentinelben.

A válaszüzenet feldolgozása

A válaszfejléc egy HTTP-állapotkódot tartalmaz. Ebben a táblázatban további információt talál az API-hívás eredményének értelmezéséről.

A válasz törzse egy JSON formátumú hibaüzenetek tömbje:

Hibaobjektum

Az API szabályozási korlátai

Minden korlátozás felhasználónként van alkalmazva:

• 100 mutató kérésenként.
• Percenként 100 kérés.

Ha a korlátnál több kérés van, 429 a válaszfejlécben található HTTP-állapotkód a következő választörzsgel lesz visszaadva:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

Körülbelül 10 000 jelző/perc a maximális átviteli sebesség a szabályozási hiba fogadása előtt.

Mintakérés törzse

{
    "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"
                }
            ]
        }
    ]
}

Minta választörzs érvényesítési hibával

Ha az összes mutató ellenőrzése sikeresen megtörtént, a HTTP 200-állapotot egy üres választörzs adja vissza.

Ha egy vagy több mutató ellenőrzése sikertelen, a válasz törzse több információval lesz visszaadva. Ha például négy mutatót tartalmazó tömböt küld, és az első három jó, de a negyedik nem rendelkezik id (kötelező mezővel), akkor a rendszer a következő törzstel együtt létrehoz egy HTTP-állapotkódot 200-ra:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

A jelzők tömbként lesznek elküldve, így a kezdet a recordIndex következő lesz 0: .

Következő lépés

Ez az API örökölt. A fenyegetésintelligencia feltöltéséhez migráljon a STIX objects API használatával. További információ: STIX objects API.