Arpwitch is a modern arpwatch replacement with JSON formatted outputs and easy options to trigger exec commands when network changes are observed.
- outputs are JSON which makes it nice-and-easy to pair with other tools
- easy triggers to –exec system commands when new network hosts are seen.
Since performing an nmap on new network hosts is a useful thing, there is also a built-in call to nmap that will invoke nmap with relatively mild but useful settings - you can easily fall back to a regular –exec if you need to do something more advanced.
Install
pip install [--upgrade] arpwitch
Example
arpwitch --debug --nmap --datafile /tmp/arpwitch.dat | jq .
The example above, watches for new network hosts; invokes an nmap scan
on them when they are discovered and saves results in XML format; saves
the arpwitch datafile to file /tmp/arpwitch.dat
(it’s JSON); pipes
the output through JQ to make it look pretty.
NB: arpwitch requires root/sudo access in order to packet-capture from the network interface(s) - the rather awesome scapy Python library is used for packet capture.
Documentation
Plenty more documentation and examples here -
Source
Have moved this repo from where I originally published it under verbnetworks (the laboratory)
Python Package
Usage
usage: arpwitch [-h] [-f <datafile>] [-i <seconds>] [-req | -noreq | -allreq]
[-rep | -norep | -allrep] [-e <command>] [-n] [-u <user>]
[-q <address>] [-v] [-w] [-d]
A modern arpwatch replacement with JSON formatted outputs and easy options to
execute commands when network changes are observed.
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.