Porch Watch
Porch Watch notices new MAC addresses in the existing home-LAN neighbor cache. Initialize it once at home to mark current devices as known, then review newcomer notices and add your own labels. A randomized MAC gets an informational notice: phones often rotate private MACs, so a new address need not mean a new device.
Built and maintained by Dragon Lady — GitHub.
Posture
- Linux first, Python 3.10 or newer. Apache-2.0.
- Passive by default: reads kernel neighbor/routing tables without sending discovery packets. No telemetry, DNS lookups, hostnames, mDNS, DHCP scraping, router login, blocking, port scans, OS fingerprinting, or service discovery.
- Only its own state and explicitly requested local reports are written. Configuration and local vendor tables are read-only. There is no root use.
- Alert delivery is opt-in through
alert_channels. Active host discovery is separately opt-in withscan --active. Neither is enabled by a printed timer. - Local state/report metadata includes MACs, last IPs, user labels, vendor, randomized flag, and first/last observation rounded down to the UTC hour. These reports are private. No packet contents or address history are kept.
- Off-box alerts contain only newcomer counts, rule ID, and severity. They never contain MACs, IPs, labels, vendors, paths, hostnames, or machine identifiers.
- Recognized provider-token shapes in labels/vendor text and configured alert credentials are replaced by keyed fingerprints. Never enter passwords or arbitrary secrets as device labels: this is not a general secret detector.
- The home gateway uses an HMAC-SHA256 fingerprint (
fp:plus 16 hex digits) with a private random 32-byte key. No plain hash is used. - State directory: 0700. Every state/report file: 0600 at creation. Unsafe existing modes are refused; source permissions are never changed. Reports are create-only and cannot overwrite an existing file or tool state.
Install
Install the published package, or install from a source checkout:
python3 -m pip install porchwatch==0.1.2
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/porchwatch --help
Runtime uses the standard library and tomli only on Python 3.10. Building uses
setuptools; tests use pytest. No packages are installed during a scan. On Linux,
iproute2 supplies the passive ip commands; nmap is optional and is never
installed or elevated by Porch Watch.
Commands
Run init only while connected to the home network you intend to monitor. It
trusts that network as home; it cannot determine that a network belongs to you.
porchwatch init
porchwatch scan
porchwatch scan --format html --output porchwatch-report.html
porchwatch list --unlabeled --since 7d
porchwatch label 00:11:22:33:44:66 "Living room TV"
porchwatch known 00:11:22:33:44:66
porchwatch report --since 7d
porchwatch report --send
porchwatch forget 00:11:22:33:44:66
porchwatch print-timer --interval 15m
All commands accept --format text|json|md|html and --output FILE. Output is
also printed to stdout. Labels are escaped in HTML/Markdown output; text output
removes control characters. --since filters by last observation, with UTC-hour
precision; it is not a scan-history view. report --send retries only pending
notices in that report's selected window.
init imports every current device as unlabeled-known and sends no alerts. It
will never overwrite existing initialization. Each subsequently discovered MAC
is alerted once per configured channel. Successful channel receipts persist;
failed channels retry on scan or report --send. Labeling or marking a device
known suppresses pending notices. Forgetting removes its record and delivery
receipts, allowing a fresh notice if it is observed again. Changing/rotating a
channel's destination does not replay already delivered notices for that channel.
For a first home baseline, keep remote alert channels disabled, run init while
present on the intended network, and review list before configuring delivery
or a timer. The operator decides which devices are normal; the tool cannot make
that judgment.
Exit status: 0 no newly observed MACs (or not home), 1 newcomer(s), 2
usage/runtime/alert-delivery error. An alert failure does not drop the newcomer:
the next run retries it. A fresh scan with only already-notified devices exits 0.
Home-network guard
Before writing state, a key, a report, or delivery receipts, and before sending
alerts, Porch Watch requires an existing neighbor-cache MAC for the IPv4 default
gateway. A connected gateway subnet must be present. Multiple default interfaces
are accepted for passive checks only when each independently has the same gateway
address, gateway MAC, and connected subnet, with one unique lowest route metric.
Their neighbor caches are combined. This exception requires iproute2; the proc
fallback and all other multiple-route cases are refused.
The gateway fingerprint and subnet must match the initialized home identity.
Missing, ambiguous, or mismatched identity yields not home, exit 0, no alert,
and no writes. init with insufficient evidence exits 2 and creates nothing.
It never probes a missing gateway to make the guard pass.
The guard also covers label, known, forget, and report file output. Lists
and local reports conservatively return not home when identity is unknown.
Printing a timer to stdout needs no network or initialization. An interrupted
initialization or missing key is not silently repaired; preserve the state for
inspection and recovery. Deliberately re-initializing on a different network
requires you to archive the old private state yourself.
Home identity is advisory: cached entries can be stale, MACs can be spoofed, and a router replacement looks like a different home. Checks are snapshots, repeated before active discovery, state writes, and alert delivery; no user-space tool can atomically bind routing changes and an external delivery transaction. A crash after remote acceptance but before saving a receipt can produce a retry. There is no claim of exactly-once delivery across crashes or provider timeouts.
Passive and active coverage
Passive mode runs only these read operations (actual executable path resolved locally):
ip -j -4 route show table all
ip -j neigh show
ip -j -4 rule show
Neighbor states REACHABLE, STALE, DELAY, and PERMANENT are accepted. FAILED,
INCOMPLETE, and other states are ignored. IPv4 and IPv6 cache entries on the
selected interface are deduplicated by MAC; one deterministic last IP is stored,
preferring IPv4. IPv6-only home-gateway initialization is not supported in v0.1.
Without ip, /proc/net/route and /proc/net/arp provide an IPv4-only passive
fallback; proc files are accessed through this process's numeric proc directory
to avoid following /proc/net symlinks. No root or nmap is needed for passive use.
Cache visibility is limited: a silent device may never appear, and a disappearing
device is not considered removed. This is not an exhaustive network inventory.
For an explicit local host-discovery run:
porchwatch scan --active
The only permitted discovery command is nmap -sn -n <subnet>. Active discovery
requires a single default interface. There is no user-supplied target,
additional flag, port scan, DNS, or privilege elevation.
Only an exact, directly connected RFC1918 IPv4 subnet on the default-route
interface, at /22 or smaller, passes. All-table route evidence and standard
IPv4 policy rules are required. Public, CGNAT, link-local, overly broad,
overlapping, other-interface, multipath, or policy-routing ambiguity fails closed.
The proc fallback cannot authorize active mode. If the subnet is safe but nmap
is missing, the command reports nmap not installed; passive fallback.
After discovery, Porch Watch rechecks home identity and reads the kernel cache;
it does not ingest nmap's output or hostnames. Unprivileged nmap host discovery
may use TCP connection probes and may find fewer devices than privileged ARP
discovery. -sn disables the port-scan phase; it does not mean no TCP packets.
See the ip neighbor manual
and nmap host-discovery reference.
Vendor lookup uses only /usr/share/ieee-data/oui.txt or
/usr/share/nmap/nmap-mac-prefixes if present and under the 5 MB read limit.
Locally administered MACs do not receive an OUI vendor guess. Missing vendor
data is harmless; it is never downloaded.
Configuration and state
Configuration defaults to ~/.config/porchwatch/config.toml; state defaults to
~/.local/state/porchwatch/. XDG_CONFIG_HOME and XDG_STATE_HOME are respected.
An alternate config is selected before the command:
porchwatch --config ~/.config/porchwatch/config.toml scan
Configuration must be owned by the current user, 0600, and a regular file.
Porch Watch does not create or edit it. examples/config.toml
documents the accepted keys. An absent config, empty alert_channels, or
["stdout"] keeps alert handling local. There are no per-MAC remote payloads.
Slack webhooks, ntfy tokens, and SMTP passwords come from environment variable names, never inline config credentials. HTTP endpoints require HTTPS except on literal loopback/localhost; redirects are rejected. SMTP requires TLS except on loopback. Delivery has a 5-second timeout per channel. Error messages do not echo provider errors, URLs, labels, or credential values.
Private state consists of:
| File | Contents |
|---|---|
devices.json |
Only MAC, first_seen, last_seen, label, vendor, randomized, last_ip per device |
home.json |
Gateway MAC HMAC and initialized subnet |
fp.key |
Random 32-byte HMAC key |
alerts.json |
HMAC identities of known devices and permanent channel delivery receipts |
lock |
Empty advisory lock, preventing overlapping local state updates |
The extra receipt state is necessary to keep the specified device schema intact while supporting known devices, once-per-channel notices, and failure retries. No report/history file is automatically accumulated.
Scheduling and verification
print-timer prints a systemd user service and timer; it installs or enables
nothing. The printed service expects a ~/.local/bin/porchwatch executable:
adjust its path to your chosen environment before a separate manual installation.
It treats finding exit code 1 as success and runs passive scans only. Configure
remote channels and their environment separately before scheduling if desired.
python -m pytest
Tests use a fake HOME/XDG tree, fixture routes/neighbors, mocked commands and alert endpoints. They do not initialize a real network, execute nmap, install timers, send alerts, or touch the real home. Installing the package does not enable monitoring.
Metadata
Release files for porchwatch 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| porchwatch-0.1.2.tar.gz | 36.2 kB | With provenance | Details for porchwatch-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| porchwatch-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for porchwatch-0.1.2-py3-none-any.whl |
Total release size: 62.9 kB
Release files / porchwatch-0.1.2.tar.gz
| Download URL | porchwatch-0.1.2.tar.gz |
|---|---|
| Size | 36.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7b49481bdac3542002eff34050edc87bc3273e347f0fcecf015a1e2c99bb6ec4
|
|
BLAKE2b-256 checksum How to use checksums |
8d7e194cea51bde5bf75e50cef9aa43ca1af99377d51d7cc6bb54e61f380a207
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / porchwatch-0.1.2-py3-none-any.whl
| Download URL | porchwatch-0.1.2-py3-none-any.whl |
|---|---|
| Size | 26.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3bb3fdd04535244611ecab2bf03a8dcffd435db45968ffb9df6261bb53dec0d6
|
|
BLAKE2b-256 checksum How to use checksums |
143f026eddf3811ee3edddbc5e37bf105627c1e6d0402052be9f52bbc8b1d322
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logSecurity for porchwatch 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for porchwatch-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.