Odkaz na starší verze rozhraní API pro indikátory nahrávání

Rozhraní API Microsoft Sentinel nahrávání indikátorů umožnilo platformám analýzy hrozeb nebo vlastním aplikacím importovat indikátory ohrožení ve formátu STIX do pracovního prostoru Microsoft Sentinel. Tento dokument slouží jako odkaz na starší verzi rozhraní API.

Volání rozhraní API pro indikátory nahrávání má pět komponent:

1. Identifikátor URI požadavku
2. Hlavička zprávy požadavku HTTP
3. Text zprávy požadavku HTTP
4. Volitelně zpracujte hlavičku zprávy odpovědi HTTP.
5. Volitelně zpracujte text zprávy odpovědi HTTP.

Registrace klientské aplikace v Microsoft Entra ID

Aby bylo možné ověřit Microsoft Sentinel, požadavek na rozhraní API pro indikátory nahrávání vyžaduje platný přístupový token Microsoft Entra. Další informace o registraci aplikace najdete v tématu Registrace aplikace pomocí Microsoft identity platform nebo základní kroky v rámci nastavení datového konektoru rozhraní API pro nahrání indikátorů.

Oprávnění

Toto rozhraní API vyžaduje, aby volající Microsoft Entra aplikaci byla udělena role přispěvatele Microsoft Sentinel na úrovni pracovního prostoru.

Vytvoření žádosti

Tato část se zabývá prvními třemi z pěti komponent popsaných výše. Nejprve je potřeba získat přístupový token z Microsoft Entra ID, který použijete k sestavení hlavičky zprávy požadavku.

Získání přístupového tokenu

Získejte přístupový token Microsoft Entra s ověřováním OAuth 2.0. V1.0 a V2.0 jsou platné tokeny přijímané rozhraním API.

Verze tokenu (v1.0 nebo v2.0), kterou vaše aplikace obdrží, je určená accessTokenAcceptedVersion vlastností v manifestu aplikace rozhraní API, které aplikace volá. Pokud accessTokenAcceptedVersion je nastavená hodnota 1, vaše aplikace obdrží token v1.0.

Pomocí knihovny MSAL knihovny Microsoft Authentication Library získejte přístupový token verze 1.0 nebo v2.0. Nebo odešlete požadavky do rozhraní REST API v následujícím formátu:

• PŘÍSPĚVEK https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
• Hlavičky pro používání aplikace Microsoft Entra:
• grant_type: "client_credentials"
• client_id: {ID klienta aplikace Microsoft Entra}
• client_secret: {secret of Microsoft Entra App}
• Rozsah: "https://management.azure.com/.default"

Pokud accessTokenAcceptedVersion je v manifestu aplikace nastavená hodnota 1, vaše aplikace obdrží přístupový token verze 1.0, i když volá koncový bod tokenu v2.

Hodnota prostředku nebo oboru je cílová skupina tokenu. Toto rozhraní API přijímá pouze následující cílové skupiny:

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

Sestavení zprávy požadavku

Byly k dispozici dvě verze starší verze rozhraní API. V závislosti na koncovém bodu se v textu požadavku vyžadoval jiný název pole. To bylo také reprezentováno dvěma verzemi akce konektoru aplikace logiky.

1. Název akce konektoru: Analýza hrozeb – Nahrání indikátorů ohrožení (zastaralé)
   • Koncový bod: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
   • Pole názvu indikátorů: value

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

• Název akce konektoru: Analýza hrozeb – Indikátory nahrání ohrožení (V2) (Preview)
  • Koncový bod: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Pole názvu indikátorů: indicators

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

Identifikátor URI požadavku

Správa verzí rozhraní API: api-version=2022-07-01
Koncový bod: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Metoda: POST

Hlavička požadavku

Authorization: Obsahuje nosný token OAuth2.
Content-Type: application/json

Text požadavku

Objekt JSON pro tělo obsahuje následující pole:

Vytvořte pole indikátorů pomocí specifikace formátu indikátoru STIX 2.1, která je zde zhuštěna pro usnadnění s odkazy na důležité části. Všimněte si také, že některé vlastnosti, i když jsou platné pro STIX 2.1, nemají odpovídající vlastnosti indikátoru v Microsoft Sentinel.

Zpracování zprávy odpovědi

Hlavička odpovědi obsahuje stavový kód HTTP. Další informace o tom, jak interpretovat výsledek volání rozhraní API, najdete v této tabulce.

Text odpovědi je pole chybových zpráv ve formátu JSON:

Objekt Error

Omezení omezení pro rozhraní API

Na uživatele se použijí všechna omezení:

• 100 indikátorů na žádost.
• 100 požadavků za minutu.

Pokud existuje více požadavků, než je limit, v hlavičce odpovědi se vrátí stavový 429 kód HTTP s následujícím textem odpovědi:

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

Přibližně 10 000 indikátorů za minutu představuje maximální propustnost před tím, než dojde k chybě omezování.

Text ukázky požadavku

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

Text ukázkové odpovědi s chybou ověření

Pokud jsou všechny indikátory úspěšně ověřeny, vrátí se stav HTTP 200 s prázdným textem odpovědi.

Pokud se ověření jednoho nebo více indikátorů nezdaří, tělo odpovědi se vrátí s dalšími informacemi. Pokud například odešlete pole se čtyřmi indikátory a první tři jsou dobré, ale čtvrtý pole neobsahuje id (povinné pole), vygeneruje se spolu s následujícím textem odpověď se stavovým kódem HTTP 200:

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

Indikátory se odesílají jako pole, takže začíná recordIndex na 0.

Další krok

Toto rozhraní API je starší verze. Proveďte migraci, abyste k nahrání analýzy hrozeb použili rozhraní API objektů STIX. Další informace najdete v tématu Rozhraní API objektů STIX.