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

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

Fontos

Ez az API előzetes verzióban érhető el, de már nem ajánlott. Használja az előzetes verzióban elérhető új STIX-objektumok API-t a fenyegetésfelderítés feltöltéséhez. További információ: STIX objects API. Az Azure előzetes verzió kiegészítő feltételei további jogi feltételeket tartalmaznak, amelyek Azure bétaverzióban, előzetes verzióban vagy más módon még nem általánosan elérhető funkciókra vonatkoznak.

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

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

Ügyfélalkalmazás regisztrálása a Microsoft Entra ID

A Microsoft Sentinel hitelesítéséhez a upload indicators API-nak küldött 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 az alapvető lépések a feltöltési mutatók API-adatösszekötő beállításának részeként.

Engedélyek

Ehhez az API-hoz a hívási Microsoft Entra alkalmazásnak Microsoft Sentinel közreműködői szerepkört kell biztosítani 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 Microsoft Entra ID, amelyet a kérés üzenetfejlécének összeállításához használ.

Hozzáférési jogkivonat beszerzése

Szerezzen be egy Microsoft Entra hozzáférési jogkivonatot 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 verzióját (v1.0 vagy v2.0) az accessTokenAcceptedVersion alkalmazás által hívott API alkalmazásjegyzékében lévő tulajdonság határozza meg. Ha accessTokenAcceptedVersion az értéke 1, 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:

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

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

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-nak két verziója volt. A végponttól függően a kérelem törzsében más tömbnévre volt szükség. Ezt a logikaialkalmazás-összekötő művelet két verziója is képviselte.

Képernyőkép a logic app connector action names for Microsoft Sentinel upload indicators API-hoz.

  1. Összekötő műveletneve: Fenyegetésfelderítés – 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ésfelderítés – 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érelem 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érelem törzse

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

Mező neve Adattípus Leírás
SourceSystem (kötelező) karakterlánc Azonosítsa a forrásrendszer nevét. Az érték Microsoft Sentinel korlátozott.
jelzők (kötelező) tömb Jelölők tömbje STIX 2.0 vagy 2.1 formátumban

Hozza létre a mutatók tömbjeit a STIX 2.1 mutatóformátum specifikációjával, amelyet itt tömörítettünk az Ön kényelme érdekében a fontos szakaszokra mutató hivatkozásokkal. Figyelje meg azt is, hogy egyes tulajdonságok, amelyek az STIX 2.1-hez érvényesek, nem rendelkeznek megfelelő mutatótulajdonságokkal Microsoft Sentinel.

Tulajdonság neve Típus Leírás
id (kötelező) karakterlánc A mutató azonosítására használt azonosító. A 2.9-es szakaszban talál további információt a létrehozásukról id. A formátum a következőképpen néz ki: indicator--<UUID>
spec_version (nem kötelező) karakterlánc STIX-jelző verziója. Ez az érték kötelező a STIX-specifikációban, de mivel ez az API csak a STIX 2.0-t és a 2.1-et támogatja, ha ez a mező nincs beállítva, az API alapértelmezés szerint a következő lesz: 2.1
type (kötelező) karakterlánc A tulajdonság értékének a következőnek kell lennie indicator: .
created (kötelező) timestamp A közös tulajdonság specifikációiért lásd a 3.2 . szakaszt.
modified (kötelező) timestamp A közös tulajdonság specifikációiért lásd a 3.2 . szakaszt.
name (nem kötelező) karakterlánc A mutató azonosítására használt név.

A termelőknek meg kell adniuk ezt a tulajdonságot, hogy segítsenek a termékeknek és az elemzőknek megérteni, hogy ez a mutató valójában mit csinál.
description (nem kötelező) karakterlánc Egy leírás, amely további részleteket és kontextust biztosít a mutatóról, beleértve annak célját és fő jellemzőit is.

A termelőknek meg kell adniuk ezt a tulajdonságot, hogy segítsenek a termékeknek és az elemzőknek megérteni, hogy ez a mutató valójában mit csinál.
indicator_types (nem kötelező) sztringek listája A mutató kategorizálásainak halmaza.

A tulajdonság értékeinek a mutató-típus-ov típusból kell származnia
pattern (kötelező) karakterlánc A mutató észlelési mintája STIX-mintázatként vagy más megfelelő nyelvként (például SNORT, YARA stb.) fejezhető ki.
pattern_type (kötelező) karakterlánc A mutatóban használt mintanyelv.

A tulajdonság értékének mintatípusokbólkell származnia.

A tulajdonság értékének meg kell egyeznie a mintatulajdonságban szereplő mintaadatok típusával.
pattern_version (nem kötelező) karakterlánc A mintatulajdonságban lévő adatokhoz használt mintanyelv verziója, amelynek meg kell egyeznie a mintatulajdonságban szereplő mintaadatok típusával.

A formális specifikációval nem rendelkező minták esetében azt a build- vagy kódverziót kell használni, amellyel a minta ismert.

A STIX-mintanyelv esetében az objektum specifikációs verziója határozza meg az alapértelmezett értéket.

Más nyelvek esetén az alapértelmezett értéknek a mintázatnyelv legújabb verziójának kell lennie az objektum létrehozásakor.
valid_from (kötelező) timestamp Az az idő, amelytől ezt a mutatót érvényesnek tekintik a kapcsolódó vagy ábrázolt viselkedések szempontjából.
valid_until (nem kötelező) timestamp Az az időpont, amikor ez a mutató már nem tekinthető érvényes mutatónak azokhoz a viselkedésekhez, amelyekhez kapcsolódik vagy amelyeket képvisel.

Ha a valid_until tulajdonság nincs megadva, akkor nincs korlátozás arra az időpontra vonatkozóan, amelyre a mutató érvényes.

Ennek az időbélyegnek nagyobbnak kell lennie a valid_from időbélyegnél.
kill_chain_phases (nem kötelező) sztringlista A leölési lánc fázisa(i), amelyekhez ez a mutató megfelel.

Ennek a tulajdonságnak az értékének a kill chain fázisbólkell származnia.
created_by_ref (nem kötelező) karakterlánc A created_by_ref tulajdonság határozza meg az objektumot létrehozó entitás ID tulajdonságát.

Ha ezt az attribútumot nem adja meg, az információ forrása nincs meghatározva. Azoknak az objektumkészítőknek, akik névtelenek szeretnének maradni, ne definiálják ezt az értéket.
revoked (nem kötelező) Logikai A visszavont objektumokat az objektum létrehozója már nem tekinti érvényesnek. Egy objektum visszavonása végleges; az objektum jövőbeli verzióit ezzel idnem szabad létrehozni.

A tulajdonság alapértelmezett értéke hamis.
labels (nem kötelező) sztringek listája A labels tulajdonság az objektum leírásához használt kifejezések halmazát adja meg. A kifejezések felhasználó által definiált vagy megbízhatósági csoportként vannak definiálva. Ezek a címkék címkékként jelennek meg a Microsoft Sentinel.
confidence (nem kötelező) egész szám A confidence tulajdonság azonosítja azt a megbízhatóságot, amelyet a létrehozó az adatok helyességében élvez. A megbízhatósági értéknek 0 és 100 közötti számnak kell lennie.

Az A függelék az egyéb megbízhatósági skálákra vonatkozó normatív leképezéseket tartalmazó táblázatot tartalmaz, amelyet a megbízhatósági értéknek az egyik skálán való bemutatásakor kell használni.

Ha a megbízhatósági tulajdonság nincs jelen, akkor a tartalom megbízhatósága nincs meghatározva.
lang (nem kötelező) karakterlánc A lang tulajdonság azonosítja az objektum szöveges tartalmának nyelvét. Jelen esetben a RFC5646 megfelelő nyelvi kódnak kell lennie. Ha a tulajdonság nincs jelen, akkor a tartalom en nyelve (angol).

Ennek a tulajdonságnak jelen kell lennie, ha az objektumtípus lefordítható szövegtulajdonságokat (például nevet, leírást) tartalmaz.

Az objektum egyes mezőinek nyelve felülbírálhatja a lang tulajdonságot részletes jelölésekkel (lásd a 7.2.3 szakaszt).
object_marking_refs (nem kötelező, beleértve a TLP-t is) sztringek listája A object_marking_refs tulajdonság az objektumra vonatkozó jelölődefiníciós objektumok azonosítótulajdonságainak listáját adja meg. Használja például a Traffic Light Protocol (TLP) jelölődefiníció-azonosítóját a mutatóforrás érzékenységének kijelöléséhez. A TLP-tartalomhoz használandó jelölésdefiníciós azonosítók részleteiért lásd a 7.2.1.4 szakaszt

Bizonyos esetekben, bár nem gyakori, a definíciók megjelölése megosztási vagy kezelési útmutatóval is megjelölhető. Ebben az esetben ez a tulajdonság nem tartalmazhat ugyanahhoz a jelölődefiníciós objektumhoz kapcsolódó hivatkozásokat (vagyis nem tartalmazhat körkörös hivatkozásokat).

Az adatjelölések további meghatározásához lásd a 7.2.2 szakaszt.
external_references (nem kötelező) objektumlista A external_references tulajdonság olyan külső hivatkozások listáját adja meg, amelyek nem STIX-információkra hivatkoznak. Ez a tulajdonság egy vagy több URL-cím, leírás vagy azonosító megadására szolgál más rendszerek rekordjai számára.
granular_markings (nem kötelező) részletes jelölések listája A granular_markings tulajdonság segít a mutató részeinek eltérő meghatározásában. Például a mutató nyelve angol, en de a leírás német, de.

Bizonyos esetekben, bár nem gyakori, a definíciók megjelölése megosztási vagy kezelési útmutatóval is megjelölhető. Ebben az esetben ez a tulajdonság nem tartalmazhat ugyanahhoz a jelölődefiníciós objektumhoz való hivatkozást (azaz nem tartalmazhat körkörös hivatkozásokat).

Az adatjelölések további meghatározásához lásd a 7.2.3 szakaszt.

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.

Állapotkód Leírás
200 Siker. Az API 200-at ad vissza, ha egy vagy több mutató ellenőrzése és közzététele sikeresen megtörtént.
400 Hibás formátum. A kérésben szereplő valami nem megfelelően van formázva.
401 Jogosulatlan.
404 A fájl nem található. Ez a hiba általában akkor fordul elő, ha a munkaterület-azonosító nem található.
429 A kérések száma egy perc alatt túllépte az értéket.
500 Kiszolgálóhiba. Általában hiba az API-ban vagy Microsoft Sentinel szolgáltatásokban.

A válasz törzse hibaüzenetek tömbje JSON formátumban:

Mező neve Adattípus Leírás
Hibák Hibaobjektumok tömbje Érvényesítési hibák listája

Hibaobjektum

Mező neve Adattípus Leírás
recordIndex Int A kérelemben szereplő mutatók indexe
errorMessages Sztringek tömbje Hibaüzenetek

Az API szabályozási korlátai

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

  • Kérésenként 100 mutató.
  • 100 kérés percenként.

Ha a korlátnál több kérés van, 429 a rendszer a válaszfejlécben egy HTTP-állapotkódot ad vissza a következő választörzsgel:

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

A szabályozási hiba beérkezése előtt percenként körülbelül 10 000 mutató a maximális átviteli sebesség.

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

Mintaválasz törzse érvényesítési hibával

Ha az összes mutató ellenőrzése sikeres, a rendszer egy ÜRES választörzset tartalmazó HTTP 200-állapotot ad 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óval rendelkező 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ő szöveggel együtt létrehoz egy 200-ás HTTP-állapotkódot:

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

A mutatók tömbként lesznek elküldve, így a recordIndex kezdete 0.

További lépés

Ez az API örökölt. Migráljon, hogy a STIX-objektumok API-jának használatával töltse fel a fenyegetésfelderítést. További információ: STIX objects API.

  • Utolsó frissítés időpontja: