Podłączanie systemu SIEM do strumienia dziennika audytu Uniqkey

Uniqkey może przesyłać zdarzenia bezpieczeństwa Twojej organizacji do systemu SIEM (Microsoft Sentinel, Splunk, Elastic, Wazuh lub dowolnego narzędzia, które może odpytywać interfejs REST API). Ten artykuł wyjaśnia, jak włączyć integrację w Portalu Administratora, jak działa API zdarzeń oraz czego można oczekiwać od danych.

Kto może z tego korzystać

• Integracja jest włączana osobno dla każdej organizacji przez administratora organizacji w Portalu Administratora.
• Twój system SIEM musi mieć wychodzący dostęp HTTPS do punktu końcowego zdarzeń Uniqkey.
• Zdarzenia są tymi samymi wpisami dziennika audytu, które są już widoczne w sekcji Audit logs w Portalu Administratora. Nie są eksportowane żadne informacje, które nie są tam widoczne, a dane poufne z sejfu, hasła ani klucze nigdy nie są uwzględniane.

Krok 1: Włącz integrację i wygeneruj token

1. Zaloguj się do Portalu Administratora jako administrator.
2. Przejdź do Integrations i otwórz zakładkę SIEM.
3. Skopiuj API endpoint wyświetlany u góry widżetu. Jest to adres URL, który będzie odpytywany przez Twój system SIEM.
4. Włącz przełącznik SIEM lub kliknij Generate Token. W oknie dialogowym zostanie wyświetlony nowy token.
5. Skopiuj token i zapisz go w magazynie sekretów systemu SIEM. Token jest wyświetlany tylko raz. Po zamknięciu okna dialogowego nie będzie można wyświetlić go ponownie.

Późniejsze zarządzanie tokenem:

• Regenerate Token generuje nowy token i natychmiast unieważnia poprzedni. Zaktualizuj swój system SIEM przed regeneracją tokenu lub bezpośrednio po niej. W przeciwnym razie odpytywanie zostanie zatrzymane.
• Wyłączenie przełącznika SIEM usuwa token i wyłącza integrację. Twój system SIEM będzie otrzymywał 403 Forbidden until a new token is generated.
• Dla każdej organizacji dostępny jest jeden token. Jeśli kilka narzędzi korzysta ze strumienia, współdzielą ten sam token.
• Wygenerowanie lub usunięcie tokenu jest również rejestrowane w dzienniku audytu.

Krok 2: Skonfiguruj system SIEM

Każdy konektor SIEM wymaga tych samych trzech elementów:

Odpytywanie co 5 minut jest dobrym ustawieniem domyślnym. Zdarzenia stają się dostępne około 2 minuty po ich wystąpieniu (patrz „Czego oczekiwać od danych” poniżej), dlatego odpytywanie częściej niż co 2 minuty nie przynosi korzyści.

Szybki test za pomocą curl

curl -s "https://<endpoint>/api/v1/events?limit=5" \
  -H "Authorization: Bearer <your token>"

Prawidłowo działająca konfiguracja zwraca HTTP 200 z treścią JSON podobną do przedstawionej w sekcji „Odpowiedź”. 401 oznacza, że brakuje nagłówka Authorization lub nie jest on typu Bearer. 403 oznacza, że token jest nieznany, został ponownie wygenerowany lub integracja jest wyłączona.

Dokumentacja API

Żądanie

GET /api/v1/events

Żądanie bez parametrów jest prawidłowe i zwraca historię organizacji od początku, po jednej stronie naraz.

Kursor jest nieprzezroczysty. Nie twórz go, nie analizuj ani nie modyfikuj. Jego format może ulec zmianie bez powiadomienia, ale otrzymany wcześniej kursor będzie nadal działać.

Odpowiedź

{
  "events": [ ... ],
  "has_more": true,
  "cursor": "eyJUIjoiMjAyNi0wOS0wMVQwOToxNDoyMi4xMTdaIiwiSSI6Ijlh..."
}

• Zdarzenia są zwracane od najstarszego do najnowszego.
• has_more informuje, czy należy od razu pobrać następną stronę. Wykonuj pętlę na podstawie has_more, a nie pustej tablicy events: strona może być pusta, mimo że pozostały jeszcze dane.
• cursor jest zawsze obecny, również na pustych stronach i gdy has_more ma wartość false. Zapisuj go jako punkt kontrolny po każdej odpowiedzi.

Błędy zwracają HTTP 400 z kodem możliwym do odczytania maszynowego:

{ "error": { "code": "invalid_cursor", "message": "Cursor is not valid. Submit the cursor from a previous response verbatim." } }

JSON rozdzielany znakami nowej linii

Jeśli Twój kolektor preferuje jedno zdarzenie na linię (ogólne wejścia REST Splunk, Elastic, narzędzia przesyłające logi), wyślij Accept: application/x-ndjson. Treść odpowiedzi będzie wtedy zawierać jedno zdarzenie JSON w każdym wierszu bez obiektu nadrzędnego, a pola stronicowania zostaną przeniesione do nagłówków odpowiedzi:

Content-Type: application/x-ndjson
X-Next-Cursor: eyJUIjoi...
X-Has-More: true

Nagłówki zapewniają te same gwarancje co treść JSON: kursor jest zawsze obecny, również na pustej stronie.

Format zdarzenia

{
  "id": "9a1c7f2e-4b13-4a8e-9f21-0c2b7d5e8a44",
  "timestamp": "2026-09-01T09:14:22.117Z",
  "category": "credential_access",
  "action": "get_vault_password_details",
  "action_id": "daf12269-a58f-4e3a-ab01-05b1293a7cac",
  "action_source": "extension",
  "outcome": "success",
  "organization_id": "d5ecd732-4a67-418c-9dea-38a097fba1f6",
  "actor": { "id": "3f2a...", "email": "jane.doe@example.com", "type": "user" },
  "client": { "system": "extension", "ip": "185.23.44.9" },
  "target": { "type": "vault", "id": "7c9d...", "name": "GitHub build account" }
}

Kategorie

Ponieważ każde zdarzenie zawiera kategorię, możesz skierować kilka konektorów do tego samego punktu końcowego z różnymi filtrami category, np. przekierować credential_access do tańszej warstwy pamięci masowej, a pozostałe dane zachować w warstwie analitycznej.

Czego oczekiwać od danych

• Dostarczenie odbywa się co najmniej raz. W pewnych warunkach zdarzenie może zostać dostarczone dwukrotnie. Deduplikuj na podstawie id.
• Zdarzenia pojawiają się około 2 minuty po wystąpieniu. Strumień celowo opóźnia najnowsze zdarzenia o 2 minuty, aby żadne zdarzenie nie zostało pominięte podczas kończenia operacji zapisu. Dlatego system SIEM nie powinien odpytywać częściej niż co 2 minuty.
• Historia jest ograniczona okresem przechowywania dziennika audytu. Strumień udostępnia dane przechowywane przez Twoją organizację. Sprawdź Data Cleanup & Retention w ustawieniach organizacji. Jeśli kolektor nie działa dłużej niż okres przechowywania, wygasłych zdarzeń nie można odzyskać. Utrzymuj kolektor w ciągłym działaniu.
• outcome nie jest sygnałem nieudanej próby logowania. Uniqkey obecnie nie rejestruje nieudanych prób logowania, dlatego każde zdarzenie authentication oznacza udane logowanie. failure jest używane wyłącznie dla działań, których celem jest zarejestrowanie odmowy, np. odrzucenia prośby o zatwierdzenie w aplikacji mobilnej. Nie twórz na podstawie tego strumienia reguł wykrywających ataki brute-force.
• client.ip nie zawsze jest dostępny. Zdarzenia zapisywane przez procesy działające w tle, SCIM lub niektóre przepływy klientów nie zawierają adresu IP. Wartość pochodzi z otrzymanego żądania i należy ją traktować jako zgłoszoną przez klienta, a nie zweryfikowaną przez infrastrukturę.
• Dane poufne nigdy nie są uwzględniane. Hasła, bezpieczne notatki, numery kart, klucze i inne zaszyfrowane dane sejfu nigdy nie opuszczają granicy zero-knowledge. Strumień zawiera wyłącznie metadane widoczne w dzienniku audytu Portalu Administratora.

Uwagi dotyczące poszczególnych systemów SIEM

Uniqkey nie udostępnia jeszcze gotowych pakietów konektorów. Punkt końcowy korzysta z tych samych konwencji co inni dostawcy rozwiązań do zarządzania tożsamością i hasłami, dlatego można użyć standardowego mechanizmu odpytywania REST danego SIEM.

• Microsoft Sentinel: użyj Codeless Connector lub Logic App z uwierzytelnianiem za pomocą klucza API (nagłówek Authorization, prefiks Bearer ). Skonfiguruj stronicowanie na podstawie pola odpowiedzi cursor, przesyłanego ponownie jako parametr zapytania cursor, oraz użyj has_more jako warunku pętli. API akceptuje jednocześnie start i cursor, co odpowiada sposobowi wysyłania drugiej strony przez Codeless Connector Framework.
• Splunk: można użyć modułowego wejścia REST lub wejścia Add-on Builder. Wyślij Accept: application/x-ndjson, aby każde zdarzenie było indeksowane jako osobny rekord, i odczytuj X-Next-Cursor oraz X-Has-More do zapisywania punktu kontrolnego.
• Elastic: Elastic Agent lub wejście Filebeat HTTP JSON / CEL może odpytywać punkt końcowy, zapisywać cursor jako stan kursora i wykonywać pętlę na podstawie has_more. Obsługiwany jest również tryb NDJSON.
• Wazuh: Wazuh nie ma natywnego mechanizmu odpytywania REST. Uruchom niewielki skrypt cykliczny, który odpytuje punkt końcowy, przechowuje cursor w pliku stanu i zapisuje zdarzenia jako wiersze JSON do pliku dziennika monitorowanego przez agenta Wazuh z log_format: json.

Rozwiązywanie problemów

Kontaktując się ze wsparciem, podaj identyfikator organizacji, dokładny adres URL żądania bez tokenu, status HTTP oraz treść odpowiedzi.