Odwoływanie się do interfejsu API wskaźników przekazywania (wersja zapoznawcza) w celu zaimportowania analizy zagrożeń do usługi Microsoft Sentinel
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.nethttps://management.azure.com/https://management.azure.com
Zmontuj komunikat żądania
Interfejs API wskaźników przekazywania ma dwie wersje. W zależności od punktu końcowego w treści żądania wymagana jest inna nazwa tablicy. Jest to również reprezentowane przez dwie wersje akcji łącznika aplikacji logiki.
Nazwa akcji łącznika: Analiza zagrożeń — wskaźniki przekazywania naruszenia (przestarzałe)
- Punkt końcowy:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Tablica nazw wskaźników:
value{ "sourcesystem":"TIsource-example", "value":[] }
- Punkt końcowy:
Nazwa akcji łącznika: Analiza zagrożeń — wskaźniki naruszenia bezpieczeństwa (wersja 2) (wersja zapoznawcza)
- Punkt końcowy:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Tablica nazw wskaźników:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Punkt końcowy:
Identyfikator URI żądania
Przechowywanie wersji interfejsu API: api-version=2022-07-01
Punkt końcowy: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?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. |
| wskaźniki (wymagane) | 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) |
timestamp | Zobacz sekcję 3.2 , aby uzyskać informacje o specyfikacji tej wspólnej właściwości. |
modified (wymagane) |
timestamp | 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) |
timestamp | 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) |
timestamp | 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.4W 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",
"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"
}
]
}
]
}
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