Skip to main content

A modern arpwatch replacement with JSON formatted outputs and easy options to exec commands when network changes are observed

Project description


PyPi Python Versions Build Status License

A modern arpwatch replacement with JSON formatted outputs and easy options to exec commands when network changes are observed. Includes a hard coded convenience --exec that invokes nmap when new network-addresses are observed.



Legacy versions based on year-date (eg v2018.2) have been hard-deprecated in favour of a backward incompatible standard versioning scheme (eg v0.2.0). With this major revision change the arguments are quite different to previous versions however they are based on what-works-well in the field.


usage: arpwitch [-h] [-f <datafile>] [-i <seconds>] [-req | -noreq | -allreq]
                [-rep | -norep | -allrep] [-e <command>] [-n] [-u <user>]
                [-q <address>] [-v] [-w] [-d]

arpwitch v0.2.0

optional arguments:
  -h, --help            show this help message and exit
  -req, --new-request   Select ARP request packet events that include new
                        ip/hw addresses not yet observed (DEFAULT).
  -noreq, --no-request  Ignore all ARP request packet events.
  -allreq, --all-request
                        Select all ARP request packet events regardless if
                        addresses have been previously observed.
  -rep, --new-reply     Select only reply packet events that include new ip/hw
                        addresses not yet observed (DEFAULT).
  -norep, --no-reply    Ignore all ARP reply packet events.
  -allrep, --all-reply  Select all ARP reply packet events regardless if the
                        addresses have been previously observed.

datafile arguments:
  -f <datafile>, --datafile <datafile>
                        The arpwitch datafile where ARP event data is stored
                        as a JSON formatted file (REQUIRED). The datafile is
                        also easy to manually query and inspect with external
                        tools such as `jq`
  -i <seconds>, --interval <seconds>
                        Interval seconds between writing to the datafile
                        (DEFAULT: 30)

ARP event command execution arguments:
  The following exec command substitutions are available: {IP}=ipv4-address,
  {HW}=hardware-address, {TS}=timestamp-utc, {ts}=timestamp-utc-short

  -e <command>, --exec <command>
                        Command line to exec on selected ARP events. Commands
                        are run async
  -n, --nmap            A hard coded convenience --exec that causes nmap to be
                        run against the IPv4 target with nmap-XML formatted
                        output written to the current-working-directory. This
                        option cannot be used in conjunction with --exec.
  -u <user>, --user <user>
                        User to exec commands with, if not set this will be
                        the same user context as arpwitch.

run-mode arguments:
  Switches that invoke run-modes other than ARP capture.

  -q <address>, --query <address>
                        Query the <datafile> for an IPv4 or HW address and
                        return results in JSON formatted output and exit.
  -v, --version         Return the arpwitch version and exit.
  -w, --witch           Supply one witch to <stdout> and exit.
  -d, --debug           Debug messages to stdout.

A modern arpwatch replacement with JSON formatted outputs and easy options to
execute commands when network changes are observed.


Example 1: Use the built-in nmap --exec definition to nmap scan new hosts when they are first observed. Additionally use --debug logging output and pipe the JSON outputs through jq for pretty formatting.

ndejong@laptop:$ sudo arpwitch --debug --nmap --datafile /tmp/arpwitch.dat | jq .
2020-02-29T21:18:28+00:00 - INFO - arpwitch v0.2.1
2020-02-29T21:18:28+00:00 - DEBUG - do_sniffer(datafile=/tmp/arpwitch.dat, save_interval=30, request_select=new, reply_select=new, exec=nmap -n -T4 -Pn -oX arpwitch-nmap-{IP}-{ts}.xml {IP}, exec_user=None)
2020-02-29T21:18:28+00:00 - DEBUG -
2020-02-29T21:18:28+00:00 - WARNING - - no existing data file found
2020-02-29T21:18:28+00:00 - DEBUG - arpwitch: 0.2.2
2020-02-29T21:18:28+00:00 - DEBUG - starts: 0
2020-02-29T21:18:28+00:00 - DEBUG - ts_first: 2020-02-29T21:18:28+00:00
2020-02-29T21:18:28+00:00 - DEBUG - ts_last: 2020-02-29T21:18:28+00:00
2020-02-29T21:18:28+00:00 - DEBUG - hw_count: 0
2020-02-29T21:18:28+00:00 - DEBUG - ip_count: 0
  "op": "request",
  "ip": {
    "addr": "",
    "new": true
  "hw": {
    "addr": "cc:32:e5:00:00:00",
    "new": true
  "trigger": "new_ip_request"
2020-02-29T21:18:32+00:00 - DEBUG - ArpWitch.async_command_exec(<exec_command>, <packet_data>, <as_user>)
2020-02-29T21:18:32+00:00 - DEBUG - ArpWitch.command_exec(command_line="nmap -n -T4 -Pn -oX arpwitch-nmap-")
2020-02-29T21:18:32+00:00 - DEBUG - ArpWitch.async_command_exec_threads_wait(wait_max=30)
2020-02-29T21:18:41+00:00 - DEBUG - ArpWitch.async_command_exec_threads_wait() - done
2020-02-29T21:18:59+00:00 - DEBUG - ArpWitchDataFile.write(filename=/tmp/arpwitch.dat, data=<data>)
2020-02-29T21:18:59+00:00 - DEBUG - ArpWitchDataFile.write() - datafile written

ndejong@laptop:$ ls -al arpwitch-nmap-*
-rw-r--r--   1 root    root     5304 Feb 29 17:01 arpwitch-nmap-

Example 2: Query the datafile to extract data about the address supplied.

ndejong@laptop:$ arpwitch -f /tmp/arpwitch.dat -q
  "ip": {
    "": {
      "cc:32:e5:00:00:00": {
        "count": 5,
        "ts_first": "2020-02-29T21:18:28+00:00",
        "ts_last": "2020-02-29T21:19:57+00:00",
        "hw_vendor": "TP-LINK TECHNOLOGIES CO.,LTD."


This code is written by Nicholas de Jong via the Verb Networks lab project.


MIT licensed. See LICENSE file for full details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for arpwitch, version 0.2.2
Filename, size File type Python version Upload date Hashes
Filename, size arpwitch-0.2.2-py3-none-any.whl (19.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size arpwitch-0.2.2.tar.gz (9.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page