Integracja z SIEM

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.

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:

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ąć.

/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.

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.

Kompletny skrypt odpytujący, na tyle krótki, by przeczytać go za jednym razem:

#!/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.

# 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

6. Mapowanie pól

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

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 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