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 → Klucze 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.

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.

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

# 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

6. Mapowanie pól

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

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