[*] cli-essentials #1 – jq

W tym artykule chciałbym przybliżyć program jq, który może nam posłużyć do analizy plików .json – w tym między innymi do analizy logów w tym formacie. Jest to pierwszy artykuł z planowanej przeze mnie serii cli-essentials, gdzie postaram się przedstawić przydatne programy w pracy analityka SOC (ale nie tylko) z poziomu terminala.

Kolejnym programem z serii będzie prawdopodobnie popularny cURL. Tymczasem wracamy do naszego głównego tematu, czyli jq. Zachęcam do pobrania przygotowanych przeze mnie logów w formacie .json i własnych ćwiczeń z programem.

PODSTAWY

Zacznijmy od pierwszej komendy – prostej kropki, która wykonuje pretty print, czyli wyświetla całą zawartość pliku w czytelnym formacie:

Kolejna komenda pozwala wyciągnąć zawartość konkretnego klucza. Dobra praktyka w dużych plikach jest dodanie sekcji z informacjami o zawartości – poniżej przykład wyciągnięcia klucza metadata, ale może to być równie dobrze info czy header:

Następne komendy pozwolą nam na analizę wybranych indeksów tablicy. Poniższa zwróci każdy alert osobno, jeden po drugim:

Aby pobrać konkretny element po indeksie (np. pierwszy), używamy zapisu z nawiasem:

Możemy też wyciągnąć zakres – poniższa komenda zwróci elementy o indeksach 1, 2 i 3:

PIPE I BUDOWANIE OBIEKTÓW

Przejdziemy do kolejnej sekcji – pipe. Zacznijmy od budowy nowych obiektów z wybranych przez nas pól:

Rozbijmy tę komendę na części:

• .alerts[] – wejście do klucza alerts i rozwinięcie tablicy (każdy alert osobno)
• | – pipe, czyli weź wynik z lewej i przekaż jako wejście do prawej – dokładnie tak samo jak w bashu
• {id:.id, lvl:.level} – budujemy nowy obiekt JSON złożony z dwóch pól: klucz id z wartością .id oraz klucz lvl z wartością .level z oryginalnego alertu

Zamiast dostawać cały alert ze wszystkimi polami, wybieramy tylko to co nas interesuje. Powyższa komenda budowała obiekt {}. Możemy też zbudować tablicę []:

Zwraca tablicę wartości bez kluczy. Kiedy używać którego formatu?

• {} – gdy chcemy czytelny output, np. do dalszej analizy w terminalu
• [] – do eksportu, np. w formacie CSV

Kolejny przykład to komenda map(), która zwraca wyniki jako tablicę zamiast osobnych outputów:

Warto porównać to z alternatywnym zapisem:

Otrzymujemy ten sam wynik, ale w innym formacie. map() przydaje się w momencie, gdy chcemy zachować tablicę, co pozwoli nam dalej analizować dane – np. za pomocą unique lub sort. Dla zapisu z | .src_ip nie będzie to już możliwe.

FILTROWANIE – select, test, contains

Komenda select() zwraca wszystkie obiekty spełniające podany warunek:

Możemy łączyć warunki logiczne za pomocą and, or i not:

Filtrujemy obiekty, gdzie severity jest większe od 7 i acknowledged wynosi false.

Komenda test() pozwala filtrować za pomocą wyrażeń regularnych:

Zwraca wszystkie alerty, gdzie pole src_ip zaczyna się od 10. – czyli wewnętrzna adresacja IP. ^ oznacza początek stringa, a \\. to dosłowna kropka.

Komenda contains() filtruje po zawartości ciągu znaków:

Zwraca alerty, gdzie rule_name zawiera słowo "Cobalt" – szukamy zwykłego ciągu znaków, bez regex.

AGREGACJE

Jedna z prostszych komend na początek – length zwróci nam liczbę alertów w tablicy:

Komenda sort_by() pozwala posortować wyniki. Połączona z reverse da nam alerty od najwyższej do najniższej wartości severity:

Komenda unique_by() przydaje się do deduplikacji. Poniższy przykład zwraca liczbę unikalnych adresów IP w tablicy alerts:

Na koniec komenda add, która pozwala zsumować elementy tablicy. Poniżej obliczamy cały ruch przychodzący – tworzymy tablicę wartości bytes_in za pomocą map(), a następnie sumujemy wszystkie elementy przez add:

To wszystko co chciałem przekazać w tym artykule. Zachęcam do własnych ćwiczeń z przygotowanymi przeze mnie logami i życzę powodzenia w pracy z jq!