Skip to content

Latest commit

 

History

History
110 lines (91 loc) · 4.5 KB

README.md

File metadata and controls

110 lines (91 loc) · 4.5 KB
Raw

netwatch

netwatch is a library and command line tool for aggregating and inferring information about hosts in a network by passively sniffing packets. It fashions events based on changes to those hosts, e.g. a new host with new MAC address has entered the local network, a known host is using never before used port 22/tcp, or a host is performing an ARP scan.

Dual-licensed under MIT or the UNLICENSE.

Examples

% sudo -E go run main.go --only log
INFO[2019-09-24 20:28:38] using first up interface: eth0
INFO[2019-09-24 20:28:44] new Host(xx:xx:xx:xx:xx:xx, 192.168.86.50)
INFO[2019-09-24 20:28:44] new 1900/udp on Host(xx:xx:xx:xx:xx:xx, 192.168.86.50)
INFO[2019-09-24 20:28:46] new Host(yy:yy:yy:yy:yy:yy, 192.168.86.20)
INFO[2019-09-24 20:28:46] new 44054/tcp on Host(yy:yy:yy:yy:yy:yy, 192.168.86.20)
INFO[2019-09-24 20:28:46] new Host(zz:zz:zz:zz:zz:zz, 0.0.0.0)
INFO[2019-09-24 20:28:46] new 443/tcp on Host(zz:zz:zz:zz:zz:zz, 0.0.0.0)

Using the config, you can also configure your own hook events, with builtin event names, and templated variables for use in commands:

% cat > config.toml <<END
[triggers]
  [triggers.new-host]
    onEvents = ["host.new"]
    doShell = "echo 'New host {{.Host.MAC}} on {{.Host.IPv4}}'"
END
% sudo netwatch --only new-host

You can also filter events by a shell command that exits 0 on success, instead of builtin onEvents like in the example above. For example we could send an email to ourselves with github.com/henrywallace/notify whenever SSH port is used on some IP address of interest:

% cat > config.toml <<END
[triggers]
  [triggers.gmail-ssh]
    onShell = '[ "{{.Host.IPv4}}:{{.PortString}}" = "192.168.86.4:22" ]'
    doShell = "NOTIFY_TO=alerts@mydomain.io notify --subject '{{.Description}}'"
END
% sudo netwatch --only gmail-ssh

As a disclaimer, there do indeed exist many other tools adjacent to this functionality such as bettercap [1] skydive [2], wireshark [3], ad nauseum. I'm naive, curious, and selfishly motivated by personal learning. Please forgive what may seem like reinventing the wheel; it's really fun.

There are a few concepts that aim to make this a flexible framework:

  • A Host is identified by a MAC address. It also holds aggregated port usage, and connections to other hosts over time. If no activity is seen originating from a Host it becomes inactive.

  • A View is a collection of extracted data from a single frame/packet about one Host, such as MAC address, IP address, ports, and adjacent Hosts that it's communicating with.

  • Events are high level descriptions of changes to Hosts. For example, a port that was being used hasn't seen any activity for say 30 seconds, and is deemed inactive. Or a Host appears to be performing an ARP scan. Or a Host is sending a packet whose TLS signature matches that of a known metasploit exploit [6]. Events should be timestamped in case you'd like to analyze a offline pcap file [4].

  • Subscribers are hooks to a stream of new Events. As a CLI, Subscribers can be configured in a config.toml, each of which can be either hardcoded named builtins such as "log" events, or custom shell scripts. As a library, Subscribers are just functions that take in a single Event as an argument.

Wishlist

The following is a wishlist of what I want to do next, which should eventually get converted to issues:

  • Use persistent storage, such as PostgreSQL/Redis.
  • SSI signal strength, for use in location triangulation. I shit you not. [10]
  • Hardware vendor OUI names [5].
  • Detect ARP scan being triggered from Host.
  • Keep track of touched, and most used domain/paths requests from Hosts, e.g. Bob's laptop visits example.com/foobar most frequently.
  • Create events whenever unencrypted traffic is detected.
  • JA3 TLS/SSL client/server fingerprinting [6].
  • HASSH SSH client/server fingerprinting [7].
  • IP geo location lookup [8].
  • Record surrounding window of packets, for events of interest.
  • File extraction fingerprinting [9].
  • Stenography detection [11].

References