netvu-Netview/README.md

Projekt magisterski - skaner ruchu bezprzewodowego sieci 802.11

Autor - Wojciech Pakulski - s426211

Podprojekty - netvu i Netview

1. netvu - skaner sieciowy, analizator plików PCAP, serwer HTTP
2. Netview - nakładka graficzna umożliwiająca interakcję z modułem serwera HTTP netvu

Dokumentacja - netvu

Opis

Program netvu jest aplikacją konsolową napisaną pod system Linux. Aplikacja wejściowa służy jako pośrednik, który przekazuje odpowiednie parametry do dostępnych modułów. Przed procesem budowania programu użytkownik może wybrać, które z modułów będą dostępne. Proces budowania i wymagane zależności są zapisane w odpowiednich plikach CMakeLists.txt.

Po uruchomieniu programu bez podania parametrów bądź z flagą -h/--help ukazane zostaną dostępne opcje i domyślne argumenty:

Allowed options:
  -h [ --help ]                         print usage information and exit
  -c [ --config ] arg (=netvu.conf)     alternative config file

Configuration:
  -m [ --mode ] arg                     runtime mode - scanner/analyzer/server

Scanner:
  -i [ --scanner.interface ] arg        wireless interface
  -C [ --scanner.channels ] arg         space separated 802.11 channels numbers
  -M [ --scanner.max_packets ] arg (=0) packet capture limit
  -l [ --scanner.log_dir ] arg (=log)   where to save captured packets
  -I [ --scanner.channel_hop_interval ] arg (=300)
                                        channel hop interval in milliseconds

Analyzer:
  -L [ --analyzer.log_dir ] arg (=log)  where captured packets are stored
  -D [ --analyzer.database_dir ] arg (=db)
                                        where to save analisys result

Server:
  -a [ --server.address ] arg (=0.0.0.0)
                                        listening address
  -p [ --server.port ] arg (=9000)      listening port
  -d [ --server.database_dir ] arg (=db)
                                        where analisys result is stored
  -o [ --server.cors ] arg (=*)         access control allow origin

Argumenty nie muszą być podawane wyłącznie z poziomu terminala. Netvu postara się odczytać także wartości z pliku konfiguracyjnego netvu.conf, jeśli taki istnieje. Użytkownik może podać inną ścieżkę do pliku konfiguracyjnego przez parametr -c/--config.

Przykładowy plik konfiguracyjny wygląda następująco:

mode=scanner

[scanner]
max_packets=2000

[analyzer]
log_dir=pcaps
database_dir=/home/x/my_db

Parametr -m/--mode ustala tryb w jakim netvu zostanie uruchomiony. W przypadku próby uruchomienia trybu, który nie został dołączony w procesie budowania, zostanie zwrócony błąd.

Dokładniejszy opis każdego z dostępnych parametrów zostanie opisany w sekcjach poświęconych danemu modułowi.

Budowanie

Do zbudowania wszystkich modułów wymagane są następujące narzędzia i biblioteki:

• Kompilator obsługujący C++17
• CMake 3.16
• libtins
• Boost >=1.7
• SQLite3
• nlohmann_json
• Biblioteka wątków (Threads)

Przykładowy proces zbudowania projektu może wyglądać następująco:

$ mkdir netvu/bin
$ cd netvu/bin
$ cmake ../src
$ cmake --build .

Moduł skanera sieciowego

Opis

Moduł skanera składa się z kilku funkcji - nie jest nią jedynie sniffowanie ruchu Wi-Fi. Do jego zadań należy również zapisywanie przechwyconych pakietów do plików i przełączanie kanałów. Ponadto, w jego skład wchodzą również funkcje pomocnicze, są to:

1. Wyszukiwanie domyślnego interfejsu karty bezprzewodowej.
2. Sprawdzanie obecności enkapsulacji RadioTap.
3. Włączanie/wyłączanie trybu Monitor na czas działania skanera.
4. Odszukanie dostępnych kanałów na danym interfejsie.

Nie wszystkie zadania muszą być wykonywane po uruchomieniu skanera. Część zadań może być całkowicie pominięta w zależności od parametrów podanych przez użytkownika. Większość zadań jest wykonywana synchronicznie, wyjątkiem są sniffowanie pakietów i przełączanie kanałów, które są podzielone na dwa osobne wątki.

Spośród pozostałych modułów jest to jedyny, który musi zostać uruchomiony z podwyższonymi uprawnieniami np. poprzez sudo.

Parametry

• interface - określa, który interfejs sieciowy zostanie wykorzystany do skanowania .
• channels - oddzielone spacją numery kanałów po których interfejs będzie się przełączać. W przypadku nie podania wartości lub wartości 0 netvu postara się automatycznie wykryć listę dostępnych kanałów na danym interfejsie. Zostaną wówczas wykorzystane wszystkie wykryte kanały.
• max_packets - określa, po ilu pakietach skanowanie zostanie przerwane. W przypadku nie podania wartości lub wartości 0 skanowanie będzie trwało do momentu przerwania przez użytkownika.
• log_dir - katalog do którego zostanie zapisany wynik skanowania w formacie pcap.
• channel_hop_interval - podawany w milisekundach czas po którym netvu będzie przełączać kanały.

Wymagania

• Bezprzewodowa karta sieciowa i sterownik z obsługą trybu Monitor
• Podwyższone uprawnienia systemowe
• Obecność następujących programów:
  1. ip - w celu wykrycia obecności enkapsulacji RadioTap na karcie sieciowej
  2. ifconfig - w celu włączania/wyłączania interfejsu karty
  3. iwconfig - w celu przełączania między trybami Managed/Monitor na czas uruchomienia programu, wyszukiwaniu interfejsów bezprzewodowych oraz przełączaniu kanałów
  4. iwlist - w celu wykrycia dostępnych kanałów

Przykład

Wywołanie bez podania konkretnego interfejsu, skanowanie jedynie kanałów 1,6 i 12 z interwałem przełączania kanału co pół sekundy i limitem 300 pakietów. Przed wywołaniem programu na interfejsie WLAN włączony był tryb Managed.

 % sudo ./netvu --scanner.channels 1 6 12 --scanner.max_packets 300 --scanner.channel_hop_interval 500 --mode scanner
Starting scanner
lo        no wireless extensions.

enp11s0   no wireless extensions.

enp12s0   no wireless extensions.

br-06884e076801  no wireless extensions.

docker0   no wireless extensions.

Using wlp9s0
Turning wlp9s0 down
Enabling Monitor mode
Turning wlp9s0 up
Packet: 1/300
Packet: 2/300
Packet: 3/300
Packet: 4/300
Packet: 5/300

...

Packet: 298/300
Packet: 299/300
Packet: 300/300
Turning wlp9s0 down
Enabling Managed mode
Turning wlp9s0up
All done

Budowanie

Do zbudowania modułu skanera wymagane są następujące komponenty:

• Boost (thread, filesystem, system)
• libtins
• Threads

Moduł analizatora

Opis

Zadaniem analizatora jest iteracja po wszystkich plikach pcap z danego katalogu utworzonych przez skaner i wyciągnięcie z nich konkretnych danych. Wśród tych danych należą m. in. adresy MAC, połączenia między urządzeniami i ilość przesłanych pakietów między hostami, średnia siła sygnału czy interwały w których wykryto ruch z lub do danego urządzenia. Wszystkie dane wyciągnięte z plików są umieszczane w pamięciowej bazie danych SQLite, która jest zrzutowana do pliku po zakończeniu pracy modułu.

Przykład

Wywołanie modułu z domyślnymi parametrami:

 % ./netvu --mode analyzer
Starting analyzer
Adding hosts..Done
Adding connections..Done
Adding host info..Done
Adding packet types..Done
Adding timestamps..Done
Adding scanning times..Done

% ls db 
2021-01-31_13-30-01.sqlite

Kompilacja

Do skompilowania modułu analizatora wymagane są następujące komponenty:

• SQLite3
• libtins
• Threads

Moduł serwera

Opis

Moduł ten pełni funkcję lekkiego serwera HTTP udostępniającego dane w formacie JSON z najnowszej bazy SQLite wygenerowanej przez moduł analizatora. Serwer asynchronicznie otwiera połączenia po otrzymaniu odpowiedniej metody HTTP. Serwer nie umożliwia modyfikacji bazy, jego zadaniem jest jedynie pobieranie danych na żądanie i przesyłanie ich do klienta. W razie potrzeby istnieje możliwość ustawienia innych parametrów nasłuchiwania i odczytu danych z innego katalogu.

Parametry

• address - adres, pod którym serwer będzie nasłuchiwał nadchodzących połączeń
• port - port, pod którym serwer będzie nasłuchiwał nadchodzących połączeń
• database_dir - katalog, w którym zawarte są pliki sqlite wygenerowane przez analizator
• cors - URI, na które serwer będzie odpowiadał

Budowanie

Do zbudowania modułu serwera wymagane są następujące komponenty:

• Boost (thread)
• SQLite3
• nlohmann_json
• Threads

Dokumentacja - Netview

Opis

Netview jest aplikacją internetową za pomocą której można interaktywnie obejrzeć wyniki modułu analizatora netvu. Do komunikacji z netvu nie jest potrzebny serwer proxy - Netview można uruchomić lokalnie otwierając plik index.html w przeglądarce. Aplikacja postara się automatycznie załadować z serwera dane o hostach po jej uruchomieniu. Domyślnie Netview będzie próbować się połączyć z serwerem na adresie lokalnym i porcie 9000. Adres ten można zmienić w widoku ustawień, a po jego zmianie dane zostaną pobrane automatycznie.

Aplikacja składa się z:

1. Interaktywnego grafu w którym widoczne są wykryte urządzenia, połączenia a także natężenie ruchu między urządzeniami. W widoku tym można przełączać wyświetlanie danych elementów

• Odległość wierzchołków od skanera jest wyliczona na podstawie średniej arytmetycznej wykrytych sił sygnału (dBm).
• Grubość krawędzi jest zależna od ilości przesłanych pakietów w daną stronę. Można dzięki temu łatwiej stwierdzić, czy dany host pełni funkcję punktu dostępowego.
• Szczegółowe informacje o urządzeniach w kolejnych zakładkach dostępne są po zaznaczeniu wierzchołków.
• W celu ułatwienia analizy możliwe jest przemieszczanie wierzchołków.

2. Widok statystyk składający się z wykresów sumy wysłanych, odebranych i transmitowanych pakietów.

3. Widok szczegółów urządzeń oraz wykrytych SSID wraz z powiązanymi z nimi punktami dostępowymi. W widoku szczegółów dostępne są informacje takie jak:
   1. Adres MAC
   2. Liczba pakietów z/do danego hosta
   3. Powiązany adres BSSID i SSID
   4. Partnerzy z którymi host nawiązał połączenie
   5. Wykres dostępności urządzenia - punkty w czasie, w których wykryto ruch z/do urządzenia

4. Widoku informacji ogólnych, w którym zawarty jest wykres liczby pakietów danego typu, a także przedziały czasowe w którym rozpoczęto i zakończono skanowanie

Jeśli istnieje potrzeba zmiany adresu serwera, można to zrobić klikając w przycisk ustawień dostępnym na pasku nawigacji. Po jego kliknięciu otworzy się okienko zmiany adresu.

Wymagania

• Do pobrania danych konieczny jest uruchomiony moduł serwera netvu.
• Przeglądarka internetowa.

Budowanie - wymagania

W celu zbudowania Netview z kodu źródłowego konieczna jest instalacja Vue CLI (Vue.js 3). Do poprawnego zbudowania należy także pobrać zależności projektu zawarte w pliku package.json. Następnie, należy wykonać polecenie npm run build. Zostanie wówczas wygenerowany katalog dist zawierający gotową aplikację.