Tapirx ("taper ecks") passively discovers and identifies networked medical
devices.
Tapirx is written in cross-platform Go and runs on
Linux, macOS, and Windows. The following products already support Tapirx
discovery out of the box:
Quick Start
Install Go, then install Tapirx:
$ go get -u -v github.com/virtalabs/tapirx
If you already have Tapirx installed, the above command will update you to the
latest version.
(See Windows instructions below if you run into trouble
on Windows.)
Read a sample pcap file (included with this package) and output JSON data:
$ SRC=$(go env GOPATH)/src/github.com/virtalabs/tapirx
$ tapirx -pcap "$SRC"/testdata/HL7-ADT-UDI-PRT.pcap -verbose
List your network interfaces, then sniff live traffic and display discovered
device data:
$ tapirx -interfaces # show a list of interfaces available for capture
$ sudo tapirx -iface <interface_name> -verbose
Read on to understand how to share discovered asset information with other
tools to fit your workflow.
Detailed Instructions
Finding Devices via a SPAN Port (a/k/a Port Mirroring)
In this configuration, a single network switchport will receive a copy of all
traffic arriving at a set of switchports you want to monitor. A typical
"managed" switch can copy traffic from all switchports on the switch, or just a
subset of them. Ask your network administrator to configure a SPAN
port
(a/k/a a mirror port) on a switch or router, then connect your machine to that
port with an Ethernet cable. If you run Wireshark
or tcpdump
on your machine's Ethernet interface,
you should start to see traffic from the other switchports.
On the machine you've connected to the SPAN port, you should begin to see
device information as the other connected devices on the switch generate HL7 or
DICOM traffic:
$ sudo tapirx -iface <your_ethernet_interface> -verbose
(On Windows, you may need to run tapirx -interfaces
to find the appropriate
interface name to pass to -iface
, which will look like
"\Device\NPF_{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
.)
If you are looking for an inexpensive switch to experiment with, we suggest
Netgear's inexpensive managed
switches,
such as the GS108E, which offers eight gigabit Ethernet ports and supports port
mirroring via its web interface.
Finding Devices via Prerecorded Pcap Files
In this configuration, you will record and analyze a pcap file, which is the
predominant format for network traffic captures.
To generate a Pcap file, run Wireshark on a machine that is connected to a SPAN
port, then save the resulting capture(s) to pcap file(s). Instead of Wireshark,
you can instead run tcpdump -w myfile.pcap
. Or ask your network administrator
to capture traffic on your behalf and share a pcap file with you.
You can then pass the pcap file directly to Tapirx instead of specifying a
network interface:
$ tapirx -pcap myfile.pcap
Connecting Tapirx to Other Systems
Tapirx can share data about discovered devices with other systems. For example,
you can:
- Leave an instance running for a fixed amount of time to collect a snapshot of
active inventory;
- Continuously catalogue devices' MAC and IP addresses along with
identification data to maintain a high level of preparedness for security
incidents; or
- Automatically highlight ePHI devices for HIPAA record keeping.
Device data can be automatically shared with any tool that offers a REST API.
As it discovers devices and identifiers, Tapirx will issue POST
requests that
look like this (in this example, Tapirx spotted an infusion pump on 10.0.0.155
communicating with an EHR via HL7 on port 2575):
$ tapirx -apiurl https://my-asset-management.example.com/assets [-apitoken MY_SECRET]
The following is POSTed to https://my-asset-management.example.com/assets
:
{
"ipv4_address": "10.0.0.155",
"ipv6_address": "",
"open_port_tcp": "",
"connect_port_tcp": "2575",
"mac_address": "00:03:b1:b5:b6:48",
"identifier": "Infuse-O-Matic Peach B+",
"provenance": "HL7 PRT-16",
"last_seen": "2019-01-02T12:37:22.938687-08:00",
"client_id": "mymachine.example.com"
}
Alternatively, you can stream CSV output to a file using the -csv
command-line option.
Run tapirx -help
to see more usage information.
Building on Windows
Building Tapirx on Windows is somewhat more involved than on Linux or macOS,
but it's within reach with a tiny bit of elbow grease:
(This procedure will become easier once gopacket supports npcap; see
@google/gopacket#568.)
Building on Linux
You will need to install libpcap
development headers, which fortunately are
in most distributions' main repositories. After you have done so, the quick
start instructions above should work properly.
Ubuntu (or other Debian-based distributions):
$ sudo apt install build-essential libpcap-dev
RHEL7 or CentOS:
$ sudo yum install gcc libpcap-devel
Building on macOS
If you've never built programs from source, you may have to run xcode-select --install
to install Apple's collection of command-line tools. Once you've
done that, the quick start instructions above should work properly.
Tests and Benchmarking
To find sample pcap files for experimentation, look in this repository's
testdata directory or the testdata
directory on your own
computer:
$ cd $(go env GOPATH)/src/github.com/virtalabs/tapirx/testdata
$ ls -l *.pcap
Run go test github.com/virtalabs/tapirx
to run the test suite.
Run go test -bench=. github.com/virtalabs/tapirx
to run tests and performance
benchmarks.
Frequently Asked Questions
How do I select specific network traffic to monitor?
Incoming data, whether live or from a file, can be filtered using
BPF expressions. For
example, if we want to sniff port 2575 (common for HL7 traffic):
$ sudo tapirx -iface <interface_name> -bpf 'port 2575' -verbose
What does "discover" mean?
Tapirx inspects network traffic, either live or prerecorded, and extracts
device information. Essentially, you can think of this tool as emitting a
continuous stream of clues along the lines of "this device was spotted using
the network at this moment." You can collect these clues, and over time you
will discover a population of devices that use your network.
Tapirx does not discover devices that don't appear to be medical devices. Put
another way, if a device doesn't use HL7, DICOM, or another protocol that
Tapirx understands, it won't appear in Tapirx's announcements. This is by
design, as medical devices merit special attention and there are plenty of
other tools that can simply regurgitate MAC-to-IP mappings. (For example, if
you run tcpdump arp
for long enough, you'll get a sense of a network
segment's population over time but you won't see information extracted from
medical device protocols.)
To risk stating the obvious, Tapirx won't discover devices that never use the
network.
What does "identify" mean?
Tapirx can help you answer the following questions about many devices:
- Is this a medical device?
- Does this device connect to an EHR or DICOM system?
- What is this device's manufacturer and model?
- What is this device's GUDID?
But it may not help with the following questions, which require information
that is not generally found in network traffic:
- What software is this device running?
- What is this device's serial number?
What protocols can Tapirx currently inspect?
HL7 and DICOM. Support for more discovery methods and protocol fields is on the
way. See the Contributing section to see how you can help.
What can't Tapirx do?
Tapirx can extract device identifiers from medical devices' network traffic,
but it will not attempt to guess a device's identity if it cannot find relevant
information.
One simple way to assign (somewhat reliable) manufacturer information to
discovered devices is to connect Tapirx to a system that looks up MAC addresses
in the public OUI database.
Plenty of free and commercial tools fit the bill.
There are many, many medical devices out there. Contact the maintainers if you
would like to see support for a specific kind of medical device that Tapirx
does not adequately discover or identify.
Are there prebuilt releases so I don't have to build Tapirx myself?
Not yet, but building it yourself requires only one go get
command; see
above.
Why is Tapirx free?
Three reasons:
- Discovery and identification of networked devices are crucial building blocks
for cybersecurity, but they're not the most interesting parts. Democratizing
this important function means organizations can move past initial stumbling
blocks.
- You deserve complete control over your data (such as ePHI). You shouldn't
have to give a company or a proprietary data collector all of your
proprietary traffic in order to catalogue your own devices.
- Free tools scale better. Given the variety of devices in the world and the
prohibitive cost of scaling proprietary tools in modern healthcare
environments, the community needs free, open-source tools that aren't locked
into a single vendor's product line.
Contributing
This is a community project, and contributions from the community are welcome!
We have written a guide for contributing.
Authors
The original authors of this project are Andrew DeOrio (@awdeorio), Henrik Holm
(@ukrutt), and Ben Ransford (@ransford) of Virta
Labs.
Third-Party Dependencies (Bill of Materials)
This project would be far more complex if it weren't for the following
open-source software:
To see a list of third-party dependencies:
$ go list -f '{{ join .Imports "\n" }}' github.com/virtalabs/tapirx | grep github