Odwoływanie się do interfejsu API wskaźników przekazywania (wersja zapoznawcza) w celu zaimportowania analizy zagrożeń do usługi Microsoft Sentinel

Artykuł
10/31/2023

Interfejs API wskaźników przekazywania usługi Microsoft Sentinel umożliwia platformom analizy zagrożeń lub niestandardowym aplikacjom importowanie wskaźników naruszenia zabezpieczeń w formacie STIX do obszaru roboczego usługi Microsoft Sentinel. Niezależnie od tego, czy używasz interfejsu API z łącznikiem danych interfejsu API przekazywania wskaźników usługi Microsoft Sentinel, czy w ramach rozwiązania niestandardowego, ten dokument służy jako odwołanie.

Ważne

Ten interfejs API jest obecnie w wersji zapoznawczej. Dodatkowe postanowienia dotyczące wersji zapoznawczej platformy Azure obejmują dodatkowe postanowienia prawne dotyczące funkcji platformy Azure, które są dostępne w wersji beta, wersji zapoznawczej lub w inny sposób nie zostały jeszcze wydane w wersji ogólnodostępnej.

Wywołanie interfejsu API wskaźników przekazywania zawiera pięć składników:

Identyfikator URI żądania
Nagłówek komunikatu żądania HTTP
Treść komunikatu żądania HTTP
Opcjonalnie przetwórz nagłówek komunikatu odpowiedzi HTTP
Opcjonalnie przetwórz treść komunikatu odpowiedzi HTTP

Rejestrowanie aplikacji klienckiej przy użyciu identyfikatora Entra firmy Microsoft

Aby uwierzytelnić się w usłudze Microsoft Sentinel, żądanie do interfejsu API wskaźników przekazywania wymaga prawidłowego tokenu dostępu firmy Microsoft Entra. Aby uzyskać więcej informacji na temat rejestracji aplikacji, zobacz Rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft lub zobacz podstawowe kroki w ramach konfiguracji łącznika danych interfejsu API przekazywania wskaźników.

Uprawnienia

Ten interfejs API wymaga przyznania aplikacji Microsoft Entra roli współautora usługi Microsoft Sentinel na poziomie obszaru roboczego.

Tworzenie żądania

W tej sekcji omówiono pierwsze trzy z pięciu omówionych wcześniej składników. Najpierw musisz uzyskać token dostępu z identyfikatora Entra firmy Microsoft, który służy do tworzenia nagłówka komunikatu żądania.

Uzyskiwanie tokenu dostępu

Uzyskaj token dostępu firmy Microsoft Entra przy użyciu uwierzytelniania OAuth 2.0. 1.0 i V2.0 są prawidłowymi tokenami akceptowanymi przez interfejs API.

Wersja tokenu (wersja 1.0 lub wersja 2.0), którą otrzymuje aplikacja, jest określana przez accessTokenAcceptedVersion właściwość w manifeście aplikacji interfejsu API wywoływanego przez aplikację. Jeśli accessTokenAcceptedVersion ustawiono wartość 1, aplikacja otrzyma token w wersji 1.0.

Biblioteka MICROSOFT Authentication Library MSAL umożliwia uzyskanie tokenu dostępu w wersji 1.0 lub 2.0. Możesz też wysłać żądania do interfejsu API REST w następującym formacie:

POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
Nagłówki do korzystania z aplikacji Microsoft Entra:
grant_type: "client_credentials"
client_id: {Identyfikator klienta aplikacji Microsoft Entra App}
client_secret: {secret of Microsoft Entra App}
Zakres: "https://management.azure.com/.default"

Jeśli accessTokenAcceptedVersion w manifeście aplikacji ustawiono wartość 1, aplikacja otrzyma token dostępu w wersji 1.0, mimo że wywołuje punkt końcowy tokenu w wersji 2.

Wartość zasobu/zakresu jest odbiorcą tokenu. Ten interfejs API akceptuje tylko następujące grupy odbiorców:

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

Zmontuj komunikat żądania

Identyfikator URI żądania

Przechowywanie wersji interfejsu API: api-version=2022-07-01
Punktu końcowego: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?api-version=2022-07-01
Metoda: POST

Nagłówek żądania

Authorization: zawiera token elementu nośnego OAuth2
Content-Type: application/json

Treść żądania

Obiekt JSON treści zawiera następujące pola:

Nazwa pola	Typ danych	opis
SourceSystem (wymagany)	string	Zidentyfikuj nazwę systemu źródłowego. Wartość `Microsoft Sentinel` jest ograniczona.
Wartość (wymagana)	tablica	Tablica wskaźników w formacie STIX 2.0 lub 2.1

Utwórz tablicę wskaźników przy użyciu specyfikacji formatu wskaźnika STIX 2.1, która została tutaj skondensowana dla wygody z linkami do ważnych sekcji. Zwróć również uwagę na niektóre właściwości, chociaż są prawidłowe dla systemu STIX 2.1, nie mają odpowiednich właściwości wskaźnika w usłudze Microsoft Sentinel.

Nazwa właściwości	Typ	Opis
`id` (wymagane)	string	Identyfikator używany do identyfikowania wskaźnika. Zobacz sekcję 2.9 , aby uzyskać informacje o sposobie tworzenia elementu `id`. Format wygląda mniej więcej tak: `indicator--<UUID>`
`spec_version` (opcjonalny)	string	Wersja wskaźnika STIX. Ta wartość jest wymagana w specyfikacji STIX, ale ponieważ ten interfejs API obsługuje tylko pliki STIX 2.0 i 2.1, jeśli to pole nie jest ustawione, interfejs API będzie domyślnie ustawiony `2.1`
`type` (wymagane)	string	Wartość tej właściwości musi mieć wartość `indicator`.
`created` (wymagane)	sygnatura czasowa	Zobacz sekcję 3.2 , aby uzyskać informacje o specyfikacji tej wspólnej właściwości.
`modified` (wymagane)	sygnatura czasowa	Zobacz sekcję 3.2 , aby uzyskać informacje o specyfikacji tej wspólnej właściwości.
`name` (opcjonalny)	string	Nazwa używana do identyfikowania wskaźnika. Producenci powinni zapewnić tę właściwość, aby pomóc produktom i analitykom zrozumieć, co ten wskaźnik faktycznie robi.
`description` (opcjonalny)	string	Opis, który zawiera więcej szczegółów i kontekstu wskaźnika, potencjalnie łącznie z jego celem i jego kluczowymi cechami. Producenci powinni zapewnić tę właściwość, aby pomóc produktom i analitykom zrozumieć, co ten wskaźnik faktycznie robi.
`indicator_types` (opcjonalny)	lista ciągów	Zestaw kategoryzacji dla tego wskaźnika. Wartości tej właściwości powinny pochodzić ze wskaźnika-type-ov
`pattern` (wymagane)	string	Wzorzec wykrywania tego wskaźnika może być wyrażony jako wzorzec STIX lub inny odpowiedni język, taki jak SNORT, YARA itp.
`pattern_type` (wymagane)	string	Język wzorca używany w tym wskaźniku. Wartość tej właściwości powinna pochodzić z typów wzorców. Wartość tej właściwości musi być zgodna z typem danych wzorca uwzględnionych we właściwości pattern.
`pattern_version` (opcjonalny)	string	Wersja języka wzorca używanego dla danych we właściwości wzorca, która musi być zgodna z typem danych wzorca zawartych we właściwości wzorca. W przypadku wzorców, które nie mają specyfikacji formalnej, należy użyć wersji kompilacji lub kodu, z którą jest znany wzorzec. W przypadku języka wzorca STIX wersja specyfikacji obiektu określa wartość domyślną. W przypadku innych języków wartość domyślna powinna być najnowszą wersją języka wzorca w momencie utworzenia tego obiektu.
`valid_from` (wymagane)	sygnatura czasowa	Czas, z którego ten wskaźnik jest uznawany za prawidłowy wskaźnik zachowań, które są powiązane z lub reprezentuje.
`valid_until` (opcjonalny)	sygnatura czasowa	Czas, w którym ten wskaźnik nie powinien być już uznawany za prawidłowy wskaźnik zachowań, które są powiązane z lub reprezentuje. Jeśli właściwość valid_until zostanie pominięta, nie ma ograniczenia dla najnowszego czasu, dla którego wskaźnik jest prawidłowy. Ten znacznik czasu musi być większy niż sygnatura czasowa valid_from.
`kill_chain_phases` (opcjonalny)	lista ciągów	Fazy łańcucha zabić, do których odpowiada ten wskaźnik. Wartość tej właściwości powinna pochodzić z fazy kill chain.
`created_by_ref` (opcjonalny)	string	Właściwość created_by_ref określa właściwość ID jednostki, która utworzyła ten obiekt. Jeśli ten atrybut zostanie pominięty, źródło tych informacji jest niezdefiniowane. W przypadku twórców obiektów, którzy chcą pozostać anonimowi, zachowaj tę wartość jako niezdefiniowaną.
`revoked` (opcjonalny)	boolean	Odwołane obiekty nie są już uznawane za prawidłowe przez twórcę obiektu. Odwołowanie obiektu jest trwałe; nie można utworzyć przyszłych wersji obiektu`id`. Wartość domyślna tej właściwości to false.
`labels` (opcjonalny)	lista ciągów	Właściwość `labels` określa zestaw terminów używanych do opisywania tego obiektu. Terminy są definiowane przez użytkownika lub grupę zaufania. Te etykiety będą wyświetlane jako tagi w usłudze Microsoft Sentinel.
`confidence` (opcjonalny)	integer	Właściwość `confidence` identyfikuje pewność, że twórca ma poprawność swoich danych. Wartość ufności musi być liczbą z zakresu od 0 do 100. Dodatek A zawiera tabelę mapowań normatywnych na inne skale ufności, które muszą być używane podczas prezentowania wartości ufności w jednej z tych skali. Jeśli właściwość ufności nie jest obecna, pewność zawartości nie jest określona.
`lang` (opcjonalny)	string	Właściwość `lang` identyfikuje język zawartości tekstowej w tym obiekcie. Gdy jest obecny, musi być zgodny z kodem języka, aby RFC5646. Jeśli właściwość nie jest obecna, język zawartości to `en` (angielski). Ta właściwość powinna być obecna, jeśli typ obiektu zawiera właściwości tekstu możliwego do tłumaczenia (na przykład nazwa, opis). Język poszczególnych pól w tym obiekcie może zastąpić`lang` właściwość w szczegółowych oznaczeniach (patrz sekcja 7.2.3).
`object_marking_refs` (opcjonalnie, w tym TLP)	lista ciągów	Właściwość `object_marking_refs` określa listę właściwości identyfikatorów obiektów definicji oznaczania, które mają zastosowanie do tego obiektu. Na przykład użyj identyfikatora definicji oznaczania Traffic Light Protocol (TLP), aby wyznaczyć czułość źródła wskaźnika. Aby uzyskać szczegółowe informacje na temat identyfikatorów definicji oznaczeń do użycia dla zawartości TLP, zobacz sekcję 7.2.1.4 W niektórych przypadkach, choć nietypowe, same definicje oznaczania mogą być oznaczone za pomocą wskazówek dotyczących udostępniania lub obsługi. W takim przypadku ta właściwość nie może zawierać żadnych odwołań do tego samego obiektu definicji oznaczania (czyli nie może zawierać żadnych odwołań cyklicznych). Zobacz sekcję 7.2.2 , aby uzyskać dalszą definicję oznaczeń danych.
`external_references` (opcjonalny)	lista obiektów	Właściwość `external_references` określa listę odwołań zewnętrznych, które odnoszą się do informacji innych niż STIX. Ta właściwość służy do udostępniania co najmniej jednego adresu URL, opisów lub identyfikatorów rekordów w innych systemach.
`granular_markings` (opcjonalny)	lista szczegółowych oznaczeń	Właściwość `granular_markings` ułatwia definiowanie części wskaźnika w inny sposób. Na przykład język wskaźnika to angielski, `en` ale opis to Niemiecki, `de`. W niektórych przypadkach, choć nietypowe, same definicje oznaczania mogą być oznaczone za pomocą wskazówek dotyczących udostępniania lub obsługi. W takim przypadku ta właściwość nie może zawierać żadnych odwołań do tego samego obiektu definicji oznaczania (tj. nie może zawierać żadnych odwołań cyklicznych). Zobacz sekcję 7.2.3 , aby uzyskać dalszą definicję oznaczeń danych.

Przetwarzanie komunikatu odpowiedzi

Nagłówek odpowiedzi zawiera kod stanu HTTP. Zapoznaj się z tą tabelą, aby uzyskać więcej informacji na temat interpretowania wyniku wywołania interfejsu API.

Kod stanu	opis
200	Powodzenie. Interfejs API zwraca wartość 200, gdy co najmniej jeden wskaźnik zostanie pomyślnie zweryfikowany i opublikowany.
400	Nieprawidłowy format. Coś w żądaniu nie jest poprawnie sformatowane.
401	Brak autoryzacji.
404	Nie można odnaleźć pliku. Zazwyczaj ten błąd występuje, gdy nie można odnaleźć identyfikatora obszaru roboczego.
429	Liczba żądań w ciągu minuty została przekroczona.
500	Błąd serwera. Zazwyczaj błąd w interfejsie API lub usługach Microsoft Sentinel.

Treść odpowiedzi to tablica komunikatów o błędach w formacie JSON:

Nazwa pola	Typ danych	opis
błędy	Tablica obiektów błędów	Lista błędów walidacji

Błąd obiektu

Nazwa pola	Typ danych	opis
recordIndex	int	Indeks wskaźników w żądaniu
errorMessages	Tablica ciągów	Komunikaty o błędach

Limity ograniczania przepustowości dla interfejsu API

Wszystkie limity są stosowane dla użytkownika:

100 wskaźników na żądanie.
100 żądań na minutę.

Jeśli istnieje więcej żądań niż limit, 429 kod stanu http w nagłówku odpowiedzi jest zwracany z następującą treścią odpowiedzi:

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

Około 10 000 wskaźników na minutę to maksymalna przepływność przed odebraniem błędu ograniczania przepustowości.

Przykładowa treść żądania

{
    "sourcesystem": "test", 
    "value":[
        {
            "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"
                }
            ]
        }
    ]
}

Przykładowa treść odpowiedzi z błędem weryfikacji

Jeśli wszystkie wskaźniki zostaną pomyślnie zweryfikowane, stan HTTP 200 zostanie zwrócony z pustą treścią odpowiedzi.

Jeśli walidacja nie powiedzie się dla co najmniej jednego wskaźnika, treść odpowiedzi zostanie zwrócona z więcej informacji. Jeśli na przykład wysyłasz tablicę z czterema wskaźnikami, a pierwsze trzy są dobre, ale czwarty nie ma id (wymagane pole), zostanie wygenerowany kod stanu HTTP 200 wraz z następującą treścią:

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

Wskaźniki są wysyłane jako tablica, więc recordIndex zaczyna się od 0.

Następne kroki

Aby dowiedzieć się więcej na temat pracy z analizą zagrożeń w usłudze Microsoft Sentinel, zobacz następujące artykuły:

Omówienie analizy zagrożeń
Praca ze wskaźnikami zagrożeń
Wykrywanie zagrożeń przy użyciu pasującej analizy
Korzystanie z kanału informacyjnego analizy firmy Microsoft i włączanie łącznika danych MDTI

Share via