# 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. ![Graf sieci](./doc-img/graph.png) 2. Widok statystyk składający się z wykresów sumy wysłanych, odebranych i transmitowanych pakietów. ![Statystyki](./doc-img/stats.png) 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 1. 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 ![Info](./doc-img/host_info.png) ![Punkty dostępu](./doc-img/aps.png) 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 ![Ogólne](./doc-img/overall.png) 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. ![Zmiana adresu](./doc-img/disconnected.png) ### 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ę.