diff --git a/README.md b/README.md index abc46aa915424dca36de1df79f2a965ee89cabf6..535e6219e95215f0f003431cfa64efdf7afc7398 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,8 @@ Basically this tool enables the management of sniffers through a "sniffer manage ## **Sniffer manager** -See [INSTALL_SETUP.md](./INSTALL_SETUP.md) for installation and setup instructions. -See [PLAYBOOKS.md](./PLAYBOOKS.md) for information about the available playbooks -See [USAGE.md](./USAGE.md) for global usage instructions. +See [DOCUMENTATION.md](./docs/INSTALL_SETUP.md) for installation, setup and usage instructions. +See [PLAYBOOKS.md](./docs/PLAYBOOKS.md) for information about the available playbooks. The sniffer manager comprises several functions: @@ -73,7 +72,7 @@ Instructions are defined in Ansible's playbooks used to prepare all instructions ## Integration -- + - [ ] Number of sniffers by super-sniffer (5) - [x] Integrate Sniffers / Manager PC - [x] Integrate code sources from [1], [5] @@ -85,6 +84,7 @@ Instructions are defined in Ansible's playbooks used to prepare all instructions - [x] Interfaces configuration - [x] Sync and positioning using GPS (coordinates lat, lon) - [x] Timeout function in Scapy-sniffer +- [x] gzip compression - [x] Data transfer to manager PC / Mitik server *** diff --git a/docs/INSTALL_SETUP.md b/docs/INSTALL_SETUP.md new file mode 100644 index 0000000000000000000000000000000000000000..498af5873e315d3309f52016e2a1ca99d555ab89 --- /dev/null +++ b/docs/INSTALL_SETUP.md @@ -0,0 +1,78 @@ +# Playbooks +Playbooks are ran by ansible using `ansible-playbook path/to/playbook.yml`. +The ansible commands should be ran from the `mitik-mgmt/config` folder. +There are five main playbooks : +```bash +- device_setup.yml # set up a new device, or update configuration +- ssh_setup.yml # set up ssh keys +- start_sens_sniffer.yml +- stop_sens_sniffer.yml +- test_meta.yml # test functions +``` +## First master-nodes connection: SSH setup +In order to ease configuring ssh keys and passwordless authentication, the playbook `ssh_setup.yml` (previously `playbook_SSH_keygen.yml`) has been re-written. +- Asks for SSH password +- Installs sshpass and keychain (master) (needs superuser powers) +- Creates a ssh key (master) +- Copy public ssh key to authorized_hosts (nodes) +- Using `.bashrc`, autoload and load the ssh key (master) + +## Nodes setup and configuration +Multiple configuration scripts, here called microstasks, have been put into a single playbook `device_setup.yml` +- `microtask_network_drivers_update.yml` (nodes) + - install git and bc + - clone https://github.com/aircrack-ng/rtl8188eus/ + - build and load driver +- `microtask_networking_naming_scheme_udev_setup.yml` (nodes) + - Switch off predictable netfowk interface naming + - set up udev rules for forced interface naming + - if any interface is named "wlanX", copy current active connection to work with wifi0 +- `microtask_networkmanager_un_manager_setup.yml` (nodes) + - set up networkmanager to ignore wifi..8 +- `microtask_interfaces_monitor_mode_cron_setup.yml` (nodes) + - copy bash script to set interfaces wifi.8 to monitor mode + - set up a cron task to run this script on reboot +- `microtask_hostname_update.yml` (nodes) + - update device hostname to [group]-[inventory name]: ss1-s1 +- `microtask_hosts_update.yml` (nodes) + - Add addresses of all other sniffers to each sniffer's hosts file +- `microtask_getty_autologin_setup.yml` (nodes) + - Sets up automatic login for internal console (accessible by connecting a keybpard to your node) +- `microtask_mitik_sens_update.yml` (nodes) + - Gets and updates the mitik-sens files from git +- `microstask_GPS_setup.yml` (nodes) + - Sets timezone to Europe/Paris + - enable GPIO + - install gpsd, gpsd-client, pps-tools, chrony + - enable gpsd, chrony systemctl units + - enable pps-gpio device tree inside /boot/firmware/config.txt + - configure gpsd to make ttyS0 use the socket /var/run/gpsd.sock + - copy the gpsd config file to `/etc/default/gpsd` + - reconfigure gpsd + - copy another config file to `/lib/systemd/system/gpsd.socket` + - uninstall ntp + - copy chrony config file `/etc/chrony/chrony.conf` +- `microtask_reboot.yml` (nodes) + - ask the user if they want to reboot + +## Starting and Stopping mitik-sens + The playbook `start_sens_sniffer.yml` asks parameters to run mitik-sens : +- The folder of mitik-sens on the nodes. Defaults to `/home/tribe/mitik-sens-mod/` +- hour and minute at which to start the experiment. Defaults to current time +15m +- Timeout after which to stop the experiment in seconds. Defaults to 3600 (1h) +- The interfaces on which to run the experiment, separated by commas (e.g. `wifi5,wifi6`). Defaults to `wifi5`. Order matters. +- The channels on which to start the interface, separated by commas. (e.g. `6,11`). Defaults to `1`. Order matters. +- The subtype filter to choose which requests to capture. Defaults to `458` +- The interval in seconds for channel hopping. Defaults to 0 (disabled) +- The hashing function. Defaults to SHA256, can be MD5 and None +- The fields to anonymize. All MACs and ssids is 15; not ssid is 14; nothing is 0. Defaults to 15 + +Then it checks if the length of interfaces and channels is the same. +If they are, we set up a crontab to run the sniffer when planned. + +**`stop_sens_sniffer.yml`** +This playbook interrupts any running `sniffer.py`, and cancels planned crontabs. + +## Testing devices and statuses +`test_meta.yml` runs all tests playbooks. +[TODO] detailler les tests