IO Ninja Hardware Client

There are three kinds of hardware sniffers for IO Ninja: Serial Tap, Ethernet Tap, and I2C/SPI Tap. Of course, each of those taps has a dedicated plugin to access all the functionality provided by the hardware. You attach an IO Ninja tap to a USB port on your PC, start the corresponding IO Ninja plugin, and you can see the captured data log in real time. Everything is great! Right?

Well, what if the data link you must inspect is physically situated far away from your PC? Grabbing a laptop and going on-site might not be the most convenient option due to many factors. For instance, imagine you need to capture a data stream for analysis overnight, and the site itself is a floor of a noisy manufacturing facility!

Realizing these challenges, we created a dedicated tool to control the IO Ninja hardware taps remotely. This tool is called ioninja-hwc, which stands for "IO Ninja Hardware Client." Now, you can attach an IO Ninja tap to a headless Raspberry Pi (or any other Linux box with USB ports) and use this tap over SSH from another PC located wherever is convenient for you.

How it works

The remote machine must be configured to enable ioninja-hwc over SSH connections.

1. Installation of ioninja-hwc

Installing IO Ninja through our APT repository or from the *.deb package is the easiest way. An alternative approach is simply copying bin/ioninja-hwc from the .tar.xz package and into usr/local/bin or usr/bin — ioninja-hwc is a self-contained executable, so one file is all you need. If you choose another directory, pay attention to the next paragraph.

2. Adding ioninja-hwc to SSH PATH

It's important to make sure ioninja-hwc is accessible from non-interactive SSH sessions for your user. The non-interactive part means that adding it to PATH in your .bashrc is not going to cut it (bash isn't going to be launched).

The easiest way to achieve that is to simply symlink ioninja-hwc into usr/local/bin, usr/bin, or any other standard Linux directory for executables:

$ sudo ln -s <IONINJA_ROOT_DIR>/bin/ioninja-hwc /usr/local/bin/ioninja-hwc

Otherwise, you need to add it to the PATH for SSH sessions manually:

1. Edit /etc/ssh/sshd_config as root and make sure this line exists:

PermitUserEnvironment = true

2. Edit ~/.ssh/environment (create if it doesn't exist) and append the following:

PATH=$PATH:<IONINJA_ROOT_DIR>/bin/

3. Configuring USB permissions

On Linux, all non-standard USB devices are owned by root with no read-write permissions for other users by default. This means that you won't be able to access IO Ninja taps under your user account unless you do it with sudo — which, of course, is rather inconvenient.

Instead, we recommend always allowing everyone to use IO Ninja taps. To do so, please:

1. Create a file /etc/udev/rules.d/900-ioninja-hw.rules with the following contents:

SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0e26", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0e27", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="326f", ATTR{idProduct}=="0001", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="326f", ATTR{idProduct}=="0002", MODE="0666", GROUP="users"
SUBSYSTEM=="usb", ATTR{idVendor}=="326f", ATTR{idProduct}=="0003", MODE="0666", GROUP="users"

2. If an IO Ninja tap was plugged in, unplug it and plug it back in again (there's no need to reboot).

4. Hardware setup

Now, you can attach your IO Ninja tap to the remote system in the same way you attached it to your PC before. Make sure to properly attach the wires or connectors between the tap and the actual data link you will monitor. Refer to the hardware manual for wiring details.

Done! The setup is complete.

You can now run IO Ninja on a PC located anywhere, start one of our new plugins (Serial Tap over SSH or Ethernet Tap over SSH), and capture data remotely over SSH just as if the tap is plugged directly into your PC!

Capturing from the command line

It's possible to use ioninja-hwc to capture traffic with your hardware taps and write it directly to an .njlog for further analysis. This is an alternative to using the "over SSH" set of plugins, and in certain cases it might just be more suitable.

For example, to capture from a Serial Tap attached to your Raspberry Pi, run the following in an SSH session:

$ ioninja-hwc --serial-tap --njlog --out=file.njlog

Replace file.njlog with a desired name for the output file. Instead of --serial-tap, you can also specify --ethernet-tap, --i2c-tap, or --spi-tap to capture from the corresponding kind of a tap.

In case when there are multiple taps of the same kind attached to your box, you can use the command line --index parameter to specify a zero-based index of the tap to use — in the order they appear in the output of the system lsusb command.

For example, to capture from the Serial Tap that appears second, please use --index=1:

$ ioninja-hwc --serial-tap --index=1 --njlog --out=file.njlog

What else can ioninja-hwc do?

There are two more important applications of ioninja-hwc besides controlling the IO Ninja hardware sniffers.

Firstly, ioninja-hwc can remotely control regular serial devices with the Serial over SSH plugin.

Secondly, now you can capture packets with your Ethernet Tap directly from Wireshark!

Command-line option breakdown

In most cases, you won't need to invoke ioninja-hwc directly — the corresponding plugins will do that for you. However, sometimes, you may want to better understand what's happening under the hood (e.g., if you plan to write a custom script to process data captured with your Serial Tap).

Please refer to the following section for more information on the command-line options of ioninja-hwc:

IO Ninja Hardware Controller v5.2.0 (amd64)
Usage: ioninja-hwc [<options>...]
General options
  -h, --help                    Display this help
  -v, --version                 Display IO Ninja Hardware Controller version
  -s, --suspend                 Don't start capturing immediately
  --firmware=<file.rpd>         Upload FPGA firmware file
  --njlog                       Output in the *.njlog file
  -n, --index=<n>               Open the attached tap #n (zero-based index)

Transport options
  --stdin                       Accept commands trom stdin
  --stdout                      Write output to stdout
  -i, --in, -f=<file>           Read from this file (write unless overriden by -o)
  -o, --out=<file>              Write output to this file
  -t, --tcp, --tcp-port=<port>  Start a TCP server on this port
  --np, --named-pipe=<pipe>     Start a named pipe server with this name

Serial options
  --serial=<COMn>               Open the specified serial port
  --serial-tap                  Open the attached Serial Tap device
  --ser-enum                    Enumerate available serial ports
  --ser-baud=<baud>             Specify serial baud rate
  --ser-data=<bits>             Specify serial data bit count (7|8)
  --ser-stop=<bits>             Specify serial stop bit count (1|15|2)
  --ser-parity=<parity>         Specify serial parity (none|even|odd|mark|space)
  --ser-flow=<flow>             Use RTS/CTS flow control (0|1)
  --ser-dtr=<dtr>               Set serial DTR line (0|1)
  --ser-rts=<rts>               Set serial RTS line (0|1)

I2C/SPI Tap options
  --i2c-tap                     Open the attached I2C/SPI Tap device in I2C mode
  --spi-tap                     Open the attached I2C/SPI Tap device in SPI mode
  --spi-mode=<mode>             Specify SPI mode (0|1|2|3); default: 0
  --spi-data=<bits>             Specify SPI data bits (4|8|12|16); default: 8
  --spi-little-endian           Use little-endian SPI (0|1); default: 0

Ethernet Tap options
  --ethernet-tap                Open the attached Ethernet Tap device
  --pcap                        Output in the *.pcap format

EZ-USB options
  --vid=<vid>                   Specify VID of the device
  --pid=<pid>                   Specify PID of the device
  --ezusb=<file.iic>            Upload an EZ-USB config file