Megosztás a következőn keresztül:


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.

Fontos

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

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.

Képernyőkép a Microsoft Sentinel upload indicators API logikaialkalmazás-összekötő műveletnevéről.

  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:

Mezőnév Adattípus Leírás
SourceSystem (kötelező) húr Azonosítsa a forrásrendszer nevét. Az érték Microsoft Sentinel korlátozott.
jelzők (kötelező) array Mutatótömb STIX 2.0 vagy 2.1 formátumban

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.

Tulajdonság neve Típus Leírás
id (kötelező) húr A mutató azonosítására használt azonosító. További információt a 2.9. szakaszban talál a létrehozás idmódjáról. A formátum a következőképpen néz ki: indicator--<UUID>
spec_version (nem kötelező) húr STIX-jelző verziója. Ez az érték kötelező az STIX specifikációban, de mivel ez az API csak az 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ő) húr A tulajdonság értékének a következőnek kell lennie indicator: .
created (kötelező) időbélyeg A közös tulajdonság specifikációiért lásd a 3.2. szakaszt.
modified (kötelező) időbélyeg A közös tulajdonság specifikációiért lásd a 3.2. szakaszt.
name (nem kötelező) húr A mutató azonosítására használt név.

A gyártóknak ezt a tulajdonságot kell biztosítaniuk, hogy segítsenek a termékeknek és az elemzőknek megérteni, hogy ez a mutató valójában mit tesz.
description (nem kötelező) húr 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őbb jellemzőit is.

A gyártóknak ezt a tulajdonságot kell biztosítaniuk, hogy segítsenek a termékeknek és az elemzőknek megérteni, hogy ez a mutató valójában mit tesz.
indicator_types (nem kötelező) sztringek listája Kategorizálások halmaza ehhez a mutatóhoz.

A tulajdonság értékeinek a indicator-type-ov értékéből kell származnia
pattern (kötelező) húr Ennek a mutatónak az é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ő) húr Az ebben a mutatóban használt mintanyelv.

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

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

Olyan minták esetében, amelyek nem rendelkeznek hivatalos specifikációval , a minta által ismert build- vagy kódverziót kell használni.

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

Más nyelvek esetében az alapértelmezett értéknek a mintázó nyelv legújabb verziójának kell lennie az objektum létrehozásakor.
valid_from (kötelező) időbélyeg Az az idő, amelytől ezt a mutatót érvényesnek tekintik azoknak a viselkedéseknek a jelzésére, amelyekhez kapcsolódik vagy jelöl.
valid_until (nem kötelező) időbélyeg Az az időpont, amikor ez a mutató már nem tekinthető érvényes mutatónak azoknak a viselkedéseknek, amelyekhez kapcsolódik vagy jelöl.

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, mint a valid_from időbélyeg.
kill_chain_phases (nem kötelező) sztringlista A leölési lánc fázisa(i), amelynek ez a mutató megfelel.

A tulajdonság értékének a Kill Chain fázisból kell származnia.
created_by_ref (nem kötelező) húr A created_by_ref tulajdonság az objektumot létrehozó entitás azonosító tulajdonságát adja meg.

Ha ez az attribútum nincs megadva, 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. Az objektum visszavonása végleges; ezzel idaz objektum jövőbeli verziói nem hozhatók létre.

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 készleté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 Sentinelben.
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 adatai helyességében ad meg. 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 ilyen skálán való megjelenítésekor kell használni.

Ha a megbízhatósági tulajdonság nem jelenik meg, akkor a tartalom megbízhatósága nincs meghatározva.
lang (nem kötelező) húr 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 nem található, 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ülírhatja a lang tulajdonságot részletes jelölésekben (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ésdefiní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 meghatározásához. 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ésdefiní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.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. A mutató nyelve például 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ésdefiníció-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 Sikeres. Az API 200 értéket ad vissza, ha egy vagy több mutató sikeres érvényesítése és közzététele megtörtént.
400 Rossz formátum. A kérésben szereplő valami nem megfelelően van formázva.
401 Nem engedélyezett.
404 A fájl nem található. Ez a hiba általában akkor fordul elő, ha a munkaterület azonosítója nem található.
429 Egy perc alatt túllépte a kérések számát.
500 Kiszolgálóhiba. Általában hiba az API-ban vagy a Microsoft Sentinel-szolgáltatásokban.

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

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

Hibaobjektum

Mezőnév Adattípus Leírás
recordIndex egész 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:

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