porchwatch 0.1.0__tar.gz

porchwatch-0.1.0/LICENSE

@@ -0,0 +1,158 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal Entity
+authorized to submit on behalf of the copyright owner. For the purposes of this
+definition, "submitted" means any form of electronic, verbal, or written
+communication sent to the Licensor or its representatives, including but not
+limited to communication on electronic mailing lists, source code control
+systems, and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but excluding
+communication that is conspicuously marked or otherwise designated in writing by
+the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable patent license to make, have made, use,
+offer to sell, sell, import, and otherwise transfer the Work, where such license
+applies only to those patent claims licensable by such Contributor that are
+necessarily infringed by their Contribution(s) alone or by combination of their
+Contribution(s) with the Work to which such Contribution(s) was submitted. If
+You institute patent litigation against any entity (including a cross-claim or
+counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated
+within the Work constitutes direct or contributory patent infringement, then any
+patent licenses granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

porchwatch-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md
+recursive-include examples *.toml
+recursive-include tests *.py

porchwatch-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: porchwatch
+Version: 0.1.0
+Summary: Private, passive home-LAN newcomer notices
+License-Expression: Apache-2.0
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Dynamic: license-file
+
+# 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](https://github.com/Dragon-Lady).
+
+## 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 with `scan --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:
+
+```sh
+python3 -m pip install porchwatch==0.1.0
+```
+
+```sh
+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.
+
+```sh
+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 unique default interface and connected gateway subnet must be present.
+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):
+
+```text
+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:
+
+```sh
+porchwatch scan --active
+```
+
+The only permitted discovery command is `nmap -sn -n <subnet>`. 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](https://man7.org/linux/man-pages/man8/ip-neighbour.8.html)
+and [nmap host-discovery reference](https://nmap.org/book/man-host-discovery.html).
+
+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:
+
+```sh
+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](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.
+
+```sh
+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.

porchwatch-0.1.0/README.md

@@ -0,0 +1,216 @@
+# 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](https://github.com/Dragon-Lady).
+
+## 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 with `scan --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:
+
+```sh
+python3 -m pip install porchwatch==0.1.0
+```
+
+```sh
+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.
+
+```sh
+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 unique default interface and connected gateway subnet must be present.
+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):
+
+```text
+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:
+
+```sh
+porchwatch scan --active
+```
+
+The only permitted discovery command is `nmap -sn -n <subnet>`. 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](https://man7.org/linux/man-pages/man8/ip-neighbour.8.html)
+and [nmap host-discovery reference](https://nmap.org/book/man-host-discovery.html).
+
+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:
+
+```sh
+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](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.
+
+```sh
+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.

porchwatch-0.1.0/examples/config.toml

@@ -0,0 +1,21 @@
+# Example only. Create your private config at 0600 before using it.
+# An absent config or empty list means local stdout only.
+alert_channels = ["stdout"]
+
+# Opt-in channels: stdout, slack, ntfy, email. Configure before scheduling.
+# alert_channels = ["stdout", "slack"]
+# alert_slack_webhook_env = "PORCHWATCH_SLACK_WEBHOOK"
+
+# alert_ntfy_topic = "https://ntfy.example.invalid/topic"
+# alert_ntfy_token_env = "PORCHWATCH_NTFY_TOKEN"
+
+# alert_smtp_host = "smtp.example.invalid"
+# alert_smtp_port = 587
+# alert_smtp_security = "starttls"  # ssl or starttls; none only on loopback
+# alert_smtp_from = "monitor@example.invalid"
+# alert_email = "operator@example.invalid"
+# alert_smtp_username = "monitor"
+# alert_smtp_password_env = "PW_SMTP_PASSWORD"
+
+# Active discovery has no persistent config switch: use scan --active explicitly.
+# Off-box payloads are aggregate counts/rule/severity only.

porchwatch-0.1.0/porchwatch/__init__.py

@@ -0,0 +1,2 @@
+"""Porch Watch: private, passive home-LAN newcomer notices."""
+__version__ = "0.1.0"

porchwatch-0.1.0/porchwatch/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())