---
title: Integracja z SIEM
description: Przesyłaj dzienniki audytu, alerty monitorowania i alerty bezpieczeństwa 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 → Klucze 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.
## 1. Zdecyduj, co przesyłać
Trzy strumienie odpowiadają na różne pytania i mają bardzo różne wolumeny.
Większość zespołów zaczyna od dwóch strumieni alertowych i dodaje dzienniki, gdy
mapowanie pól jest już ustalone.
| Strumień | Wolumen | Przesyłaj, gdy |
| -------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `/security-alerts` | Niski | Zawsze. To wykrycia Defender / Sentinel, wzbogacone o użytkowników, grupy i aplikacje, których dotyczą. |
| `/monitoring-alerts` | Niski | Zawsze. To wykrycia Twoich własnych reguł 1Security - nie ma ich nigdzie indziej. |
| `/logs` | Wysoki - pełny strumień aktywności | Chcesz mieć w SIEM aktywność M365 wraz z kontekstem uprawnień, urządzenia i lokalizacji. |
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 strumieni alertowych `from` i `to` obejmują moment wygenerowania alertu.
### 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. Alerty zmieniają się po wygenerowaniu
Dzienniki są niezmienne: raz przyjęte zdarzenie nigdy się nie zmienia. Alerty
takie nie są - są przypisywane, odkładane i rozwiązywane już po pojawieniu się.
Odpytywanie oparte wyłącznie na znaczniku uchwyci moment wygenerowania alertu i
nigdy nie zobaczy, co stało się z nim później.
Jeśli Twój SOC obsługuje alerty wewnątrz SIEM, dołóż obok odpytywania
przyrostowego **przebieg uzgadniający**: w wolniejszym rytmie, na przykład co
godzinę, pobierz ponownie alerty 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/monitoring-alerts?from=$(date -u -d '-7 days' +%FT%TZ)&limit=1000"
```
Dobierz okno uzgadniania do tego, jak długo alert zwykle pozostaje otwarty w
Twoim procesie. Pola `isResolved` i `resolvedAt` mówią, czym każdy z nich się
zakończył.
## 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), `lastScan` (alerty
monitorowania) 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 `/monitoring-alerts` 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` / `lastScan` /
`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` | `/monitoring-alerts` | `/security-alerts` |
| ------------------ | --------------------------------- | --------------------------- | -------------------------- |
| Czas zdarzenia | `occurredAt` | `lastScan` | `firstActivityDateTime` |
| Czas przyjęcia | `discoveredAt` | - | - |
| Klucz deduplikacji | `id` | `id` | `id` |
| Waga | `severity` | `severity` | `severity` |
| Aktor | `actorName`, `actorId`, `actorIp` | `assignedUser` | `actorDisplayName` |
| Zasób | `resourceName`, `resourceType` | `resources`, `resourceType` | `users`, `groups`, `apps` |
| Reguła / tytuł | `action` | `name` | `title` |
| Status | - | `status`, `isResolved` | `status`, `classification` |
Dwie kwestie normalizacyjne warte obsłużenia od razu:
- **Słowniki wag są różne.** Dzienniki i alerty monitorowania 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.** Dzienniki i alerty bezpieczeństwa zwracają pełny ISO-8601
z `Z`. Alerty monitorowania zwracają obecnie ten sam moment UTC bez `T` i `Z`
(`2026-06-05 09:12:44`). Parsuj tę wartość jako UTC. Przyszłe wydanie
ujednolici format do ISO-8601 wszędzie.
## 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.
## Co dalej
Planowane usprawnienia tej ścieżki integracji, abyś mógł je uwzględnić w
projekcie:
- **Wypychanie przez webhooks**, eliminujące pętlę odpytywania dla strumieni
alertowych.
- **Specyfikacja OpenAPI** wraz z referencyjnymi konektorami dla Sentinel i
Splunk, dzięki czemu konfiguracja z sekcji 5 stanie się importem, a nie
budową od zera.
- **Klucze na poziomie organizacji** dla dostawców MSSP, aby jeden konektor
obsługiwał całe portfolio tenantów zamiast jednego klucza na tenanta.
- **Synchronizacja dwukierunkowa**, aby zamknięcie alertu w SIEM zamykało go
również w 1Security.
## Dalej