Control API - dzienniki, audyt i użycie

Użyj elementu FoxIDs Control API, aby wysyłać zapytania do dzienników diagnostycznych, zdarzeń inspekcji i danych dotyczących użycia oraz konfigurować typy dzienników emitowanych przez środowisko. Zasoby te mają różne cele i prawa dostępu:

  • Dzienniki pomagają operatorom diagnozować błędy, ostrzeżenia, przepływy protokołów, zdarzenia i metryki.
  • Audyt rejestruje działania związane z bezpieczeństwem i administracją, w tym aktywność logowania oraz żądania tworzenia, aktualizowania i usuwania Control API.
  • Wykorzystanie agreguje aktywność na potrzeby analizy operacyjnej i rozliczeniowej.

Przed wywołaniem tych operacji skonfiguruj Control API uwierzytelnianie i prawa dostępu. Swagger pozostaje dokładnym odniesieniem dla wszystkich parametrów zapytania, wartości wyliczeniowych, ustawień i schematów odpowiedzi:

Zakres zapytania i punkty końcowe

FoxIDs udostępnia trzy zakresy zapytań.

Zakres Baza punktów końcowych Dziennik diagnostyczny Rewizja Stosowanie
Jedno środowisko /api/{tenant_name}/{track_name} !tracklog !tracklogaudit !tracklogusage
Twój tenant /api/{tenant_name}/master !mytenantlog !mytenantlogaudit !mytenantlogusage
Administracja wdrożeniami /api/master/master !tenantlog !tenantlogaudit !tenantlogusage

Poprzedź bazę hostem FoxIDs Control, na przykład https://control.foxids.com. Zmień hosta dla wdrożenia samodzielnego. Wyślij token dostępu w nagłówku Authorization: Bearer {access_token}.

Zapytania o środowisko korzystają ze środowiska z trasy. Zapytania Tenant mogą opcjonalnie wybrać środowisko za pomocą trackName. Zapytania dotyczące administracji wdrażaniem mogą wybierać tenant i środowisko za pomocą tenantName i trackName. Zapytanie diagnostyczne dotyczące wdrożenia może również obejmować żądania odrzucone przed tenant i routing środowiska.

Użyj praw dostępu track:log, track:audit lub track:usage, opcjonalnie zawężonych do określonego środowiska. Inspekcja i użycie w całym wdrożeniu wymagają odpowiednich praw dostępu master. Zobacz kompletne tabele praw dostępu.

Zapytaj o dzienniki diagnostyczne

Żądanie dziennika diagnostycznego określa fromTime i toTime jako czas uniksowy w sekundach. Pojedyncze żądanie może obejmować maksymalnie 24 godziny. Wybierz jedną lub więcej kategorii, takich jak błędy, ostrzeżenia, ślady, zdarzenia i metryki, i użyj filter do filtrowania dowolnego tekstu.

Odpowiedź zawiera do 300 najnowszych pasujących wpisów. Sprawdź responseTruncated; gdy wynosi true, zawęź zakres czasu lub przefiltruj i zapytaj ponownie, zamiast zakładać, że wynik jest kompletny.

Application Insights nie obsługuje jednoczesnego wysyłania zapytań o ślady i zdarzenia za pomocą tej operacji. Wysyłaj osobne żądania, jeśli wymagane są obie kategorie. Staraj się, aby zakresy czasu były tak wąskie, jak to możliwe, aby poprawić wydajność zapytań i zmniejszyć ilość zwracanych poufnych danych.

Punkty końcowe zapytania wymagają podstawowego repozytorium dzienników z możliwością przeszukiwania. Nie mogą pobrać dzienników, jeśli podstawowym wyjściem dziennika wdrożenia jest wyjście standardowe (Stdout). W tej konfiguracji zamiast tego wyślij zapytanie do kontenera platformy lub systemu rejestrowania hosta. FoxIDs obsługuje zapytania kontrolne względem skonfigurowanych repozytoriów Application Insights i OpenSearch.

Zapytanie o zdarzenia audytu

Żądanie audytu określa fromTime i toTime jako czas uniksowy w sekundach i może obejmować maksymalnie siedem dni. toTime musi być równe lub późniejsze od fromTime. Opcjonalny element filter wykonuje ogólne wyszukiwanie dowolnego tekstu w polach kontroli i danych zdarzeń.

Odpowiedź zawiera do 300 najnowszych pasujących zdarzeń kontroli. Zaznacz opcję responseTruncated i podziel lub zawęź zapytanie, jeśli wymagany jest pełny wynik.

Zdarzenia inspekcji obejmują aktywność uwierzytelniania użytkownika i mutacje administracyjne. Akcje Control API POST, PUT i DELETE są kontrolowane automatycznie, natomiast żądania GET tylko do odczytu nie są poddawane inspekcji. Zdarzenie kontroli może zawierać przydatne wartości korelacji, takie jak tenant, środowisko, metoda uwierzytelniania, aplikacja, użytkownik, sesja, adres IP klienta i agent użytkownika, jeśli te wartości są dostępne dla akcji.

Celem audytu jest pokazanie, jakie działanie miało miejsce i jaki jest jego kontekst. Nie jest to kolejka zdarzeń transakcyjnych i nie należy jej używać jako jedynego wyzwalacza synchronizacji o znaczeniu krytycznym dla firmy. Wyniki wyszukiwania zależą również od skonfigurowanego repozytorium dzienników i przechowywania.

Użycie zapytania

Żądania użycia wybierają zakres czasu, przesunięcie czasu UTC i poziom podsumowania. Dołącz flagi określają, czy odpowiedź zawiera tenants, środowiska, metody uwierzytelniania, użytkowników, loginy, żądania tokenów, dodatkowe użycie i aktywność Control API.

Wybierz najwęższy zakres i tylko wymiary potrzebne konsumentowi. Dzięki temu odpowiedzi są mniejsze i pozwala uniknąć niepotrzebnego ujawniania tenant lub szczegółów użytkownika. Użyj Swagger dla bieżącego zakresu czasu i wartości podsumowania.

Skonfiguruj rejestrowanie środowiska

Konfiguracja dziennika środowiska wykorzystuje:

Działanie Punkt końcowy Zamiar
Pobierz ustawienia GET /!tracklogsetting Odczytuj włączone typy dzienników diagnostycznych dla środowiska trasy.
Zapisz ustawienia POST /!tracklogsetting Zamień ustawienia dziennika środowiska.
Uzyskaj strumienie GET /!tracklogstreamssettings Przeczytaj konfigurację zewnętrznego strumienia dziennika.
Zapisuj strumienie POST /!tracklogstreamssettings Zastąp konfigurację zewnętrznego strumienia dziennika.

Ustawienia kontrolują ślady informacji, ślady roszczeń, ślady komunikatów i metryki. Błędy, ostrzeżenia, błędy krytyczne i zdarzenia pozostają dostępne niezależnie, zgodnie z opisem w Logowaniu. POST zastępuje pełny zasób ustawień; pobierz bieżący zasób, zachowaj niezmienione właściwości, a następnie zapisz pełną reprezentację.

Strumień dziennika przekazuje wybrane kategorie do zewnętrznego miejsca docelowego niezależnie od głównego repozytorium dzienników. Można tego użyć do wysłania kontrolowanego zestawu dzienników środowiska do oddzielnego zasobu Application Insights.

Ślady roszczeń i komunikatów mogą zawierać dane osobowe, tokeny i kompletne komunikaty protokołu. Włącz je tylko dla określonej potrzeby diagnostycznej, ogranicz dostęp, ustaw odpowiedni okres przechowywania i wyłącz je ponownie po zakończeniu badania.

Wskazówki operacyjne

  • Używaj znaczników czasu UTC Unix w integracjach i stosuj timeOffset tylko tam, gdzie prezentacja użycia wymaga lokalnej granicy.
  • Podziel długie badania na żądania w maksymalnym zakresie czasu punktu końcowego.
  • Zachowaj specyfikę filtrów dowolnego tekstu i unikaj polegania na wyświetlanym tekście jako stałym identyfikatorze komputera.
  • Chroń zwrócone dane dziennika i inspekcji jako informacje wrażliwe operacyjnie.
  • Użyj audytu, aby zbadać i udokumentować działania, a nie zastąpić gwarantowane powiadomienie lub synchronizację API.
  • Spodziewaj się, że zmiany w ustawieniach dzienników i strumieni zostaną poddane inspekcji, ponieważ są to mutacje Control API.

Typowe reakcje na błędy

  • 400 Bad Request, gdy zakres czasu, selektor, tenant, środowisko lub zasób ustawień jest nieprawidłowy.
  • 401 Unauthorized, gdy brakuje tokena dostępu lub jest on nieprawidłowy.
  • 403 Forbidden, gdy wywołujący nie ma wymaganego prawa dostępu do dziennika, audytu lub użytkowania.
  • 404 Not Found, gdy wybrane środowisko lub zasób ustawień nie istnieje.

Użyj treści odpowiedzi, aby uzyskać szczegółowe informacje dotyczące sprawdzania poprawności, oraz Swagger UI w przypadku odpowiedzi zadeklarowanych przez każdą operację.