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:
- A kérelem URI-ja
- HTTP-kérelem üzenetfejléce
- HTTP-kérés üzenettörzse
- A HTTP-válaszüzenet fejlécének feldolgozása opcionálisan
- 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.
- Ö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
- Végpont:
- Ö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":[] }
- Végpont:
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 id mó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 id az 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.