--- title: Integracja z SIEM description: Przesyłaj wykrycia, alerty bezpieczeństwa, dzienniki audytu i skany zasad z 1Security do Splunk, Microsoft Sentinel, QRadar, Elastic lub dowolnego systemu SIEM potrafiącego odpytywać API REST. icon: Radar --- Ten przewodnik opisuje podłączenie 1Security do systemu SIEM od początku do końca: co przesyłać, jaka pętla odpytywania utrzymuje kompletność strumienia i jak połączyć to z popularnymi platformami. Sam kontrakt API - wszystkie punkty końcowe, parametry i pola - opisuje [dokumentacja API](/pl/docs/reference/api). Model jest **pull-based**. Twój SIEM odpytuje API zgodnie z harmonogramem i przechowuje znacznik czasu (watermark), dzięki czemu każde odpytanie pobiera tylko nowe dane. Nie jest wymagana żadna łączność przychodząca do Twojej sieci. ## Zanim zaczniesz Potrzebujesz klucza API z zakresami odpowiadającymi strumieniom, które chcesz przesyłać. Utwórz go w panelu w **Ustawienia → API** (wyłącznie administrator) i skopiuj sekret `1sec_live_…` - jest wyświetlany tylko raz. Zanim cokolwiek na nim zbudujesz, potwierdź, że działa: ```bash curl -H "Authorization: Bearer $ONESEC_API_KEY" \ https://api.1security.ai/api/v1/ping ``` Odpowiedź zwraca tenanta i zakresy przypisane do klucza. Jeśli brakuje zakresu, którego oczekiwałeś, popraw to teraz, zamiast diagnozować błąd `403` z wnętrza konektora. Zakładka **Konsola testowa** na tym samym ekranie wykonuje dowolny punkt końcowy na żywych danych tenanta wprost z przeglądarki - użyj jej, aby podejrzeć odpowiedzi i dopracować filtry, zanim trafią do konfiguracji konektora. ## 1. Zdecyduj, co przesyłać Strumienie odpowiadają na różne pytania i mają bardzo różne wolumeny. Dwa z nich to strumienie alertowe w rozumieniu SOC - `/security-alerts` i `/detections` - i od nich warto zacząć. | Strumień | Wolumen | Przesyłaj, gdy | | ------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/security-alerts` | Niski | Zawsze. To wykrycia Defender / Sentinel, wzbogacone o użytkowników, grupy i aplikacje, których dotyczą. | | `/detections` | Niski | Zawsze. Własne wykrycia 1Security - epizody anomalii oznaczone przez Twoje zasady i detektory - nie ma ich nigdzie indziej. Zakres `detections:read`. | | `/logs` | Wysoki - pełny strumień aktywności | Chcesz mieć w SIEM aktywność M365 wraz z kontekstem uprawnień, urządzenia i lokalizacji. | | `/notifications` | Niski | Chcesz mieć ślad audytowy tego, co 1Security komu przekazało - każdą decyzję o powiadomieniu: wysłane, wstrzymane z powodem lub nieudane. Zakres `notifications:read`. | | `/policy-scans` | Niski | Chcesz mieć liczniki postawy bezpieczeństwa jako metryki. Każdy wiersz to migawka - „w chwili T zasada P pasowała do N zasobów" - a nie alert. Zakres `policy-scans:read`. | `/detections` zwraca stanowe epizody w **kopercie rozróżnianej polem `kind`**: dziś każdy wiersz ma `kind: "anomaly"`, a rejestr będzie rósł (np. podróż niemożliwa czy werdykty phishingowe) bez zmiany samej koperty. Każdy epizod niesie `status` (`open · acknowledged · dismissed · resolved`), `openedAt` / `lastSeenAt` / `resolvedAt`, detektor (`detector`), podmiot (`entity` - `null` dla epizodów zagregowanych na poziomie tenanta) oraz liczby specyficzne dla rodzaju pod `details`. Domyślnie zwracane są tylko epizody z poziomu alertowego; dodaj `includeInfoTier=true`, jeśli chcesz też poziom informacyjny. `/notifications` to dziennik powiadomień: jeden wiersz na decyzję, z odbiorcami, informacją, czy wiadomość wyszła z Twojej własnej skrzynki czy z mailera platformy, polityką lub detektorem anomalii, z którego pochodzi, efektywną ważnością, a dla powiadomień o anomaliach - z podmiotem (`resourceType` / `resourceId`). Filtruj przez `source`, `kind`, `decision`, `reason`, `policyId`, `resourceType`, `resourceId`, `from`, `to`; odpytuj tak jak pozostałe źródła. To sposób, by na pytanie „dlaczego nie dostaliśmy maila o X" odpowiedzieć z poziomu SIEM. `/policy-scans` celowo nie nazywamy strumieniem alertowym: wiersz skanu to punktowa próbka licznika dopasowań zasady - przydatna jako seria metryk albo do raportowania postawy, ale przesyłanie każdego skanu jako alertu to prosta droga do zmęczenia alertami. Jeśli przekroczenie progu przez zasadę ma kogoś powiadomić, skonfiguruj na niej wyzwalacz natychmiastowy - jego zadziałanie pojawi się w `/notifications`. Na dużym tenancie to `/logs` generuje koszt licencji SIEM. Filtruj po stronie API, a nie po ingest: `severity=high,critical` albo konkretna lista `action` utrzymuje wolumen proporcjonalny do tego, czego naprawdę używają Twoje detekcje. Zakres zawsze można później poszerzyć. ## 2. Pętla odpytywania Odpytuj **zamknięte okno czasowe** i przesuwaj znacznik dopiero wtedy, gdy całe okno zostanie pobrane. To domknięcie okna decyduje o niezawodności. Zapytanie otwarte rośnie w trakcie stronicowania - nowe zdarzenia dopływają na początek porządku sortowania i przesuwają wiersze pomiędzy żądaniami. Okno domknięte z obu stron jest zbiorem stałym: nie może się zmienić w trakcie odczytu. ### Okno po czasie przyjęcia zdarzenia Dla `/logs` używaj `discoveredFrom` i `discoveredTo`, a nie `from` i `to`. `discoveredAt` to moment przyjęcia zdarzenia przez 1Security, `occurredAt` to moment, w którym zdarzenie wystąpiło w M365. Microsoft potrafi ujawniać zdarzenia wiele godzin po fakcie, a tylko czas przyjęcia jest monotoniczny - dlatego tylko on gwarantuje, że nie przeoczysz opóźnionego zdarzenia. Dla `/security-alerts` i `/detections` `from` i `to` obejmują moment wygenerowania alertu lub epizodu; dla `/policy-scans` - moment wykonania skanu. ### Zostaw niewielkie opóźnienie Kończ okno minutę lub dwie za bieżącym zegarem, a nie dokładnie na „teraz". Na granicy okna wciąż zatwierdzane są zapisy, a niewielkie opóźnienie zapobiega sytuacji, w której zdarzenie pojawia się tuż po tym, jak odczytałeś ten zakres. ### Sortuj rosnąco i pobierz wszystkie strony Dla `/logs` dodaj `sort=discoveredAtAsc`. Ten porządek rozstrzyga remisy po identyfikatorze zdarzenia, więc każdy wiersz ma dokładnie jedną pozycję w sekwencji stron. Podążaj za `pagination.nextCursor`, przekazując go jako `?cursor=`, aż `hasMore` przyjmie wartość `false`. ### Przesuwaj znacznik tylko po sukcesie Przesuń znacznik na **koniec okna, które właśnie pobrałeś**, i wyłącznie po tym, jak wszystkie strony zakończyły się powodzeniem. Jeśli którakolwiek strona zawiedzie, zachowaj stary znacznik i powtórz całe okno - ponowny odczyt jest tani, a deduplikacja po `id` pochłania nakładanie. Kompletny skrypt odpytujący, na tyle krótki, by przeczytać go za jednym razem: ```bash #!/usr/bin/env bash set -euo pipefail STATE_FILE=/var/lib/1security/watermark LAG_SECONDS=120 # trzymaj się nieco za "teraz", by nic nie wpadło za krawędź SINCE=$(cat "$STATE_FILE" 2>/dev/null || date -u -d '-1 hour' +%FT%TZ) UNTIL=$(date -u -d "-${LAG_SECONDS} seconds" +%FT%TZ) BASE="https://api.1security.ai/api/v1/logs" QUERY="discoveredFrom=$SINCE&discoveredTo=$UNTIL&sort=discoveredAtAsc&limit=1000" CURSOR="" while :; do URL="$BASE?$QUERY" [ -n "$CURSOR" ] && URL="$URL&cursor=$CURSOR" RESP=$(curl -sS --fail-with-body \ -H "Authorization: Bearer $ONESEC_API_KEY" "$URL") echo "$RESP" | jq -c '.data[]' >> /var/log/1security-logs.ndjson CURSOR=$(echo "$RESP" | jq -r '.pagination.nextCursor // empty') [ -z "$CURSOR" ] && break done # Wykonywane tylko wtedy, gdy każda strona zakończyła się powodzeniem. echo "$UNTIL" > "$STATE_FILE" ``` Uruchamiaj go co jedną do pięciu minut. Lekkie nakładanie okien i poleganie na deduplikacji po `id` w SIEM jest bezpieczniejsze niż próba trafiania w dokładne granice. ## 3. Pierwsze uruchomienie Pobranie historii to ta sama pętla, tyle że dla ustalonej sekwencji okien zamiast jednego okna przesuwnego. 1Security przechowuje aktywność do trzech lat, więc przed startem zdecyduj, jak głęboko wstecz Twój SIEM naprawdę potrzebuje danych. - Przechodź zakres **stałymi porcjami** - od jednej do sześciu godzin, zależnie od wielkości tenanta. Każda porcja jest zamkniętym oknem, więc każdą można wznowić niezależnie. - Zostaw `limit=1000` i mieść się w limicie 600 żądań na minutę. - Zapisuj, na której porcji jesteś. Jeśli proces przerwie się, wznawiasz od tej porcji, a nie od początku. - Uruchom pobieranie historii i odpytywanie bieżące jako **osobne zadania** z osobnymi znacznikami. Niech bieżące odpytywanie startuje od teraz, a pobieranie historii pracuje wstecz za nim - dzięki temu bieżące pokrycie nigdy nie czeka na historię. ## 4. Wykrycia zmieniają się po wygenerowaniu Dzienniki są niezmienne: raz przyjęte zdarzenie nigdy się nie zmienia. Wykrycia takie nie są - są **stanowe**. Epizod z `/detections` pozostaje otwarty, dopóki zachowanie trwa, bywa potwierdzany lub odrzucany przez analityka i w końcu zostaje rozwiązany; wiersze `/security-alerts` przechodzą w ten sam sposób przez cykl statusów i klasyfikacji Microsoftu. Flaga `stateful: true` na wykryciu to jawny sygnał, że wiersz już pobrany może się zmienić. Odpytywanie oparte wyłącznie na znaczniku uchwyci moment otwarcia epizodu i nigdy nie zobaczy, co stało się z nim później. Jeśli Twój SOC obsługuje wykrycia wewnątrz SIEM, dołóż obok odpytywania przyrostowego **przebieg uzgadniający**: w wolniejszym rytmie, na przykład co godzinę, pobierz ponownie epizody wygenerowane w ostatnich N dniach niezależnie od znacznika i zaktualizuj je po `id`. Zmiany stanu będą wtedy trafiać do SIEM w ciągu jednego przebiegu. ```bash # Uzgadnianie co godzinę - ponowny odczyt ostatnich 7 dni i aktualizacja po id curl -H "Authorization: Bearer $ONESEC_API_KEY" \ "https://api.1security.ai/api/v1/detections?from=$(date -u -d '-7 days' +%FT%TZ)&limit=1000" ``` Dobierz okno uzgadniania do tego, jak długo epizod zwykle pozostaje otwarty w Twoim procesie. Pola `status` i `resolvedAt` mówią, czym każdy z nich się zakończył. Wiersze `/policy-scans` są próbkami punktowymi i przebiegu uzgadniającego nie potrzebują - jedyny wyjątek: administrator może w panelu zmienić `status` / `isResolved` skanu, więc obejmij je przebiegiem tylko wtedy, gdy śledzisz ten proces. ## 5. Podłączenie do systemu SIEM Użyj **Codeless Connector Platform** albo **Logic App**, jeśli chcesz mieć pełną kontrolę nad pętlą. - **Uwierzytelnianie**: `Authorization: Bearer ` jako sekret połączenia. - **Stronicowanie**: przekazuj `pagination.nextCursor` do parametru `cursor`; zatrzymaj się, gdy `hasMore` przyjmie wartość `false`. - **Miejsce docelowe**: wysyłaj `data[]` do tabeli niestandardowej w Log Analytics przez Data Collection Endpoint i regułę zbierania. - **TimeGenerated**: mapuj z `occurredAt` (dzienniki), `openedAt` (wykrycia), `scannedAt` (skany zasad) lub `firstActivityDateTime` (alerty bezpieczeństwa). - **Stan**: przechowuj koniec okna w stanie konektora i przesuwaj go dopiero po pełnym pobraniu. Ponieważ 1Security sam pobiera alerty z Defender i Sentinel, przesyłanie `/security-alerts` z powrotem do Sentinel może dublować to, co już tam jest. Większość zespołów przesyła do Sentinel `/detections` i `/logs`, a `/security-alerts` zostawia dla systemów SIEM, które tego źródła nie mają. Użyj **modular input typu REST API** (Splunk Add-on Builder lub równoważny dodatek). - **Punkt końcowy**: osobny input dla każdego przesyłanego strumienia. - **Nagłówek uwierzytelnienia**: `Authorization: Bearer `. - **Obsługa odpowiedzi**: indeksuj każdy element `data[]` jako osobne zdarzenie. - **Czas zdarzenia**: pobieraj z `occurredAt` / `openedAt` / `scannedAt` / `firstActivityDateTime`, a nie z czasu indeksowania - dzięki temu opóźnione zdarzenia M365 trafią na właściwą oś czasu. - **Deduplikacja**: ustaw `id` jako klucz zdarzenia, aby nakładające się okna się scalały. - **Punkt kontrolny**: zapisuj koniec okna pomiędzy uruchomieniami. - **Harmonogram**: co jedną do pięciu minut. Obie platformy natywnie odpytują JSON po REST. - **QRadar**: źródło logów oparte o **Universal REST API Protocol**, z tokenem bearer w nagłówku, `data[]` jako ścieżką rekordów i `pagination.nextCursor` sterującym parametrem stronicowania. - **Elastic**: input **httpjson** w Elastic Agent lub Filebeat. Rozdziel po `data[]`, użyj zmiennej kursora dla `nextCursor` i ustaw `@timestamp` na podstawie pola czasu zdarzenia. W obu przypadkach utrzymaj wzorzec zamkniętego okna z sekcji 2 - skonfiguruj żądanie tak, aby wysyłało `discoveredFrom` i `discoveredTo`, a nie zapytanie otwarte. Skrypt z sekcji 2 jest całą integracją. Zapisuje NDJSON, który potrafi czytać każdy kolektor logów - Fluent Bit, Vector, Filebeat lub zwykły forwarder. Uruchamiaj go z crona albo timera systemd co jedną do pięciu minut. Trzymaj plik znacznika na trwałym magazynie i zadbaj, aby działała tylko jedna instancja naraz (`flock`) - inaczej dwa uruchomienia mogą przesunąć znacznik poza okno, którego żadne z nich nie dokończyło. ## 6. Mapowanie pól | Zastosowanie | `/logs` | `/detections` | `/security-alerts` | `/policy-scans` | `/notifications` | | ------------------ | --------------------------------- | -------------------------- | -------------------------- | --------------------------- | ------------------------------ | | Czas zdarzenia | `occurredAt` | `openedAt` | `firstActivityDateTime` | `scannedAt` | `createdAt` | | Czas przyjęcia | `discoveredAt` | - | - | - | - | | Klucz deduplikacji | `id` | `id` | `id` | `id` | `id` | | Waga | `severity` | `severity` | `severity` | `severity` | `severity` | | Aktor | `actorName`, `actorId`, `actorIp` | `entity.name`, `entity.id` | `actorDisplayName` | `assignedUser` | `recipients` | | Zasób | `resourceName`, `resourceType` | `entity.type` | `users`, `groups`, `apps` | `resources`, `resourceType` | `resourceType`, `resourceId` | | Reguła / tytuł | `action` | `detector.name`, `kind` | `title` | `name` | `policyName`, `source`, `kind` | | Status | - | `status`, `stateful` | `status`, `classification` | `status`, `isResolved` | `decision`, `reason` | Dwie kwestie normalizacyjne warte obsłużenia od razu: - **Słowniki wag są różne.** Dzienniki, wykrycia, skany zasad i powiadomienia używają skali `info · low · medium · high · critical`. Alerty bezpieczeństwa idą za skalą Microsoftu: `informational · low · medium · high · unknown`. Zmapuj obie na własną skalę SIEM, zamiast przepuszczać te wartości bez zmian. - **Znaczniki czasu to ISO-8601 UTC** (`2026-06-05T09:12:44Z`) w każdym strumieniu. Wcześniejsze wydania zwracały znaczniki skanów zasad bez `T` i `Z`; to już poprawione, więc jeden parser ISO obsługuje wszystkie strumienie. ## 7. Utrzymanie integracji `429` - odczekaj liczbę sekund podaną w `Retry-After` i ponów to samo żądanie. `500` - ponawiaj z wykładniczym odstępem i nie przesuwaj znacznika. `401` - klucz został unieważniony lub wygasł; integracja jest wtedy niedostępna do czasu jego wymiany, więc alarmuj zamiast ponawiać. `403` - kluczowi brakuje zakresu, co jest problemem konfiguracji, a nie usterką przejściową. Zapisuj go poza procesem - w pliku stanu, we własnym magazynie stanu konektora albo we wpisie KV. Znacznik trzymany wyłącznie w pamięci po każdym wdrożeniu po cichu startuje od wartości domyślnej, co objawia się falą duplikatów albo luką - zależnie od tego, jaka jest ta wartość domyślna. Dodaj kontrolę typu dead-man: alarmuj, jeśli przez czas dłuższy niż kilka interwałów odpytywania do SIEM nie trafiło żadne zdarzenie z 1Security. Skrypt, który po cichu przestał działać, wygląda dokładnie tak samo jak spokojny tenant - i to jest ta awaria, o której dowiadujesz się w trakcie postępowania wyjaśniającego. Filtruj po stronie API, nie po ingest. Zawężaj `/logs` przez `severity`, `action` lub `workload` i poszerzaj w miarę potrzeb swoich detekcji. Dla alertów bezpieczeństwa przesyłaj punkt listowy, a `/security-alerts/{id}` pobieraj na żądanie podczas triage'u, zamiast indeksować pełny ładunek `rawData` dla każdego alertu. 600 żądań na minutę na klucz. Jedno odpytanie na strumień na minutę przy `limit=1000` zużywa niewielki ułamek tego budżetu. Realnie zbliżyć się do limitu może tylko pobieranie historii - to je ograniczaj, nie odpytywanie bieżące. `/policy-scans` nazywał się wcześniej `/monitoring-alerts`. Klucze, które nadal mają stary zakres `monitoring-alerts:read`, działają dalej - serwer traktuje go jak `policy-scans:read` - ale nowe klucze powinny prosić o nową nazwę zakresu. ## Co dalej Planowane usprawnienia tej ścieżki integracji, abyś mógł je uwzględnić w projekcie: - **Nowe rodzaje wykryć** w `/detections` - koperta jest rozróżniana polem `kind` właśnie po to, aby nowości (podróż niemożliwa, werdykty phishingowe) pojawiały się jako nowe wartości `kind` z własnymi `details`, a nie jako nowe punkty końcowe. - **Wypychanie przez webhooks**, eliminujące pętlę odpytywania dla strumieni wykryć. - **Referencyjne konektory** dla Sentinel i Splunk, dzięki czemu konfiguracja z sekcji 5 stanie się importem, a nie budową od zera. Specyfikacja OpenAPI jest już dostępna pod `GET /api/v1/openapi.json`. - **Synchronizacja dwukierunkowa**, aby zamknięcie wykrycia w SIEM zamykało je również w 1Security. Dwie pozycje z wcześniejszych wersji tej listy zostały już dostarczone: specyfikacja OpenAPI oraz [klucze dla całej organizacji](/pl/docs/reference/api#klucze-dla-całej-organizacji-mssp) dla dostawców MSSP - jeden klucz obejmujący całe portfolio tenantów, z tenantem wybieranym przy każdym żądaniu nagłówkiem `X-Tenant-Id`. ## Dalej