83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
# 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.
|
|
```bash
|
|
poetry install --editable
|
|
# or with pip
|
|
pip install -e .
|
|
```
|
|
Currently, this is the recommended method.
|
|
Alternatively install with pip into any activated environment:
|
|
```bash
|
|
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.
|
|
1. Install pyinstaller
|
|
```bash
|
|
pip install pyinstaller
|
|
```
|
|
2. Make the executable
|
|
```bash
|
|
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
|
|
```bash
|
|
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:
|
|
```bash
|
|
iottb init-db
|
|
```
|
|
### Adding a device
|
|
Typically, captures are performed for devices. To add a device (to the current default database)
|
|
```bash
|
|
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
|
|
```bash
|
|
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`.
|
|
|