Iottb

Installation

There are a few different ways to install iottb.

In Linux, to install to a users local bin directory using poetry or pip:

Move into the project root cd path/to/iottb-project, so that you are in the directory which contains the pyproject.toml file.

poetry install --editable
# or with pip
pip install -e .

Currently, this is the recommended method. Alternatively install with pip into any activated environment:

pip install -r requirements.txt

It is possible to make a single executable for you machine which you can just put in your path using pyinstaller.

Install pyinstaller

pip install pyinstaller

Make the executable

pyinstaller --onefile --name iottb --distpath ~/opt iottb/main.py

to be able to run it as iottb if `~/opt' is a directory on your PATH. A executable which should be able to run on linux is included in the repo.

Basic Invocation

Usage: iottb [OPTIONS] COMMAND [ARGS]...

Options:
  -v, --verbosity    Set verbosity  [default: 0; 0<=x<=3]
  -d, --debug        Enable debug mode
  --cfg-file PATH    Path to iottb config file  [default:
                     /home/seb/.config/iottb/iottb.cfg]
  --help             Show this message and exit.

  --dry-run BOOLEAN  currently NOT USED!  [default: True]
  
Commands:
  add-device           Add a device to a database
  init-db
  sniff                Sniff packets with tcpdump
  
Debugging Commands:
  show-all             Show everything: configuration, databases, and...
  show-cfg             Show the current configuration context

Usage Examples

Initializing a database

Before devices can be added and packet captures performed, there must be a database. Initialze a database with default values at the default location:

iottb init-db

Adding a device

Typically, captures are performed for devices. To add a device (to the current default database)

iottb add-device 'Echo Dot 2'

if the devices is named 'Echo Dot 2'. This will get the cannonical name 'echo-dot'. This name should be used when performing captures with iottb.

Performing captures/sniffing traffic

iottb sniff -a <ipv4-addr or mac-addr> 'echo-dot'

to sniff traffic on the previously added device 'Echo Dot 2' which received the canonical name 'echo-dot'. You can get the subcommand specif helptext by adding the --help option.

Configuration

Env Vars

IOTTB_CONF_HOME

By setting this variable you control where the basic iottb application configuration should be looked for

License

This project is licensed under a BSD 3-clause License, a copy of which is provided in the file code/iottb-project/LICENSE.

2.7 KiB Raw Blame History