lanfence 0.1.0__tar.gz

lanfence-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+<!--
+Copyright (c) 2026-present Stable State Consulting Ltd
+SPDX-License-Identifier: MIT
+-->
+
+# Changelog
+
+All notable changes to LAN Fence are recorded here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project aims to follow [Semantic Versioning](https://semver.org/).
+Each release is also published to
+[PyPI](https://pypi.org/project/lanfence/) and tagged on
+[GitHub](https://github.com/rosscooney/lanfence/releases).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-11
+
+Initial release. MVP scope: ARP scanning (active + passive), MAC tracking, an
+allowlist, basic device fingerprinting, CLI + JSON output, and syslog/email/
+webhook alerting.
+
+### Added
+
+- `lanfence scan` - one-time active ARP sweep of the local subnet (auto-
+  detected, or `--interface`/`--subnet`); records every device to a
+  persistent SQLite database and prints a device table plus any findings.
+- `lanfence monitor` - continuous watch: repeats an active ARP sweep on an
+  interval (`scan.scan_interval_seconds`) and, in parallel, passively sniffs
+  ARP traffic between sweeps for lower-latency detection of a device that
+  joins mid-interval. Runs until interrupted (Ctrl+C).
+- `lanfence allow <mac>` / `--list` / `--remove` - manage a YAML allowlist of
+  devices you trust; findings about an allowlisted device are downgraded to
+  `info` instead of alerting every time it reconnects.
+- `lanfence report --since <30m|24h|7d>` - summarizes connect/disconnect/
+  reappear events and findings recorded in the database over a time window,
+  for scheduled (cron/systemd-timer) daily or weekly reports.
+- `lanfence check` - verifies the host can run LAN Fence: root/raw-socket
+  access, whether `scapy` is installed, interface/subnet auto-detection, and
+  that the database path is writable.
+- Device lifecycle tracking (`new_device` / `reappeared` / `disconnected`)
+  persisted to SQLite, keyed by MAC address.
+- Built-in device fingerprinting: a curated offline OUI → vendor table
+  (`lanfence/data/oui_vendors.txt`) plus a rogue-device signature set
+  (`lanfence/data/rogue_signatures.yaml`) covering Espressif (ESP32/ESP8266 -
+  common in DIY hidden cameras and Wi-Fi implants), Raspberry Pi hardware,
+  USB-Ethernet gadget chipsets, and hostname signatures for Pwnagotchi, Hak5
+  Bash Bunny/LAN Turtle/WiFi Pineapple, Flipper Zero and O.MG Cable. Both
+  files are extensible via `vendor_file:` / `rogue_signatures_file:` in
+  config. A locally-administered (randomized/spoofed) MAC is flagged on its
+  own as a low-grade signal.
+- Plain-language findings with `high` / `medium` / `info` severity, a
+  rationale, a recommendation, and supporting evidence lines.
+- Alert dispatch to syslog, email (SMTP) and/or a webhook (JSON POST), gated
+  by `alerts.min_severity`; `--alert` on `scan`/`monitor` triggers dispatch.
+- JSON export (`--format json`) on `scan` and `report`, and
+  `--fail-on-findings` exit codes (`0`/`10`/`20` for info/medium/high) for CI
+  use.
+- YAML configuration (`--config`) for scan settings, alert channels, database
+  path, allowlist path, and extra vendor/signature files.
+- No telemetry and no calls to any third-party service; every network
+  destination (syslog target, SMTP host, webhook URL) is one the operator
+  configures themselves.
+
+[Unreleased]: https://github.com/rosscooney/lanfence/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rosscooney/lanfence/releases/tag/v0.1.0

lanfence-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to LAN Fence
+
+Thanks for your interest in improving LAN Fence. Contributions are welcome via
+pull requests at <https://github.com/rosscooney/lanfence>.
+
+## Licensing of contributions
+
+- LAN Fence is distributed under the [MIT License](LICENSE).
+- Contributions submitted to the project are expected to be distributed under
+  the MIT License as part of LAN Fence.
+- Contributors retain copyright in their own contributions unless separately
+  agreed in writing.
+- By submitting a pull request, you confirm that you have the right to submit
+  the code under the MIT License, and that you are licensing your contribution
+  under the MIT License.
+
+There is **no** Contributor Licence Agreement or copyright assignment to sign.
+
+## What not to submit
+
+- Proprietary or confidential code.
+- Code copied from third-party projects under licences incompatible with MIT
+  distribution (for example GPL/AGPL/SSPL source code copied into LAN Fence).
+- Significant new dependencies whose licences are incompatible with the
+  project's MIT distribution model. If a change adds a new runtime dependency,
+  note its licence in the pull request description.
+- A full copy of the IEEE OUI registry or similarly large generated data files.
+  `lanfence/data/oui_vendors.txt` is a small curated subset on purpose (see
+  the comment at the top of that file) - keep additions targeted.
+
+## Scope and non-goals
+
+LAN Fence is an **observation-only, defensive** tool. It scans, records and
+reports; it never sends anything beyond a standard ARP request, never joins,
+deauthenticates, spoofs, blocks, or otherwise touches another device on the
+network. Please do not propose features that add active exploitation, packet
+injection/deauth, DHCP/ARP spoofing, network blocking or throttling, or any
+other offensive capability against devices LAN Fence discovers - such pull
+requests will be closed.
+
+LAN Fence cannot prove a device is malicious or that a MAC address is genuine
+- vendor OUIs and hostnames are trivially spoofed. It surfaces evidence and
+heuristics for a human to judge. Keep documentation and finding wording
+consistent with that (a "finding" is a lead, not a verdict).
+
+## Development setup
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,scan]"
+pytest
+```
+
+Active/passive scanning itself needs root (or `CAP_NET_RAW`) and a real
+network interface, so most of the test suite exercises the scanning code with
+the network layer mocked - `lanfence/scanner.py` is intentionally the one
+thin module that talks to raw sockets.
+
+## Before opening a pull request
+
+- Add or update tests for behaviour changes.
+- Run the test suite: `pytest`.
+- Keep changes focused; describe the motivation in the PR description.
+- Add the source-file header to any **new** original source files:
+
+  ```python
+  # Copyright (c) 2026-present Stable State Consulting Ltd
+  # SPDX-License-Identifier: MIT
+  ```
+
+## Reporting bugs and security issues
+
+- Normal bugs: open a GitHub issue.
+- Security vulnerabilities in LAN Fence itself: open a GitHub issue marked
+  `security`, or email contributors@lanfence.dev.

lanfence-0.1.0/DISTRIBUTING.md

@@ -0,0 +1,62 @@
+<!--
+Copyright (c) 2026-present Stable State Consulting Ltd
+SPDX-License-Identifier: MIT
+-->
+
+# Distributing LAN Fence
+
+LAN Fence is MIT-licensed. The distribution model is deliberately
+**low-friction**: this project ships **only its own MIT code**, plus a small
+curated OUI vendor table and a handful of rogue-device fingerprint signatures
+(both plain-text/YAML data files, not compiled artifacts), and never
+redistributes a prebuilt operating-system image. Users install onto their own
+stock Raspberry Pi OS / Debian, so the GPL/LGPL parts of the OS come straight
+from Raspberry Pi Ltd and Debian - this project is not in that supply chain.
+
+> Not legal advice. If you redistribute at scale, have a solicitor review your
+> final artifact and its notices.
+
+## Supported ways to install
+
+### 1. pipx (recommended)
+
+```bash
+pipx install lanfence
+```
+
+Isolated from system Python, and puts the `lanfence` launcher on your `PATH`.
+
+### 2. pip / venv (any Debian/Ubuntu/RPi OS host)
+
+```bash
+python3 -m venv ~/.venvs/lanfence
+~/.venvs/lanfence/bin/pip install 'lanfence[scan]'
+```
+
+`scapy` (its own licence, GPL-2.0 - see below) is an optional extra
+(`lanfence[scan]`) because it is only needed for the actual ARP scanning code
+path; everything else (config, allowlist, database, reporting) has no GPL
+dependency.
+
+## A note on `scapy`
+
+`scapy` is licensed GPL-2.0-only. LAN Fence's own code is MIT and calls scapy
+as an ordinary, unmodified, independently-installed library dependency (an
+`import`, not vendored source) - this is the same relationship any Python tool
+has with a GPL library it depends on via PyPI. If your organisation's
+licence policy treats "depends on a GPL library at runtime" differently from
+"redistributes GPL source", get your own legal read before shipping a
+downstream product built on LAN Fence; LAN Fence's own source and the code it
+directly redistributes (`lanfence/data/*`) remain MIT regardless.
+
+## Publishing checklist (maintainers)
+
+See [RELEASING.md](RELEASING.md) for the full step-by-step. In short:
+
+- [ ] `python -m build` → `twine check dist/*` passes
+- [ ] `pip install dist/*.whl` in a clean venv; `lanfence --version` works
+- [ ] `CHANGELOG.md` has a dated section for this version
+- [ ] tag `vX.Y.Z`; publish to PyPI as `lanfence`
+- [ ] `LICENSE`, `CONTRIBUTING.md`, `CHANGELOG.md`, `DISTRIBUTING.md` present in
+      the sdist (`LICENSE` via `license-files` in `pyproject.toml`; the rest
+      via [`MANIFEST.in`](MANIFEST.in)) - check with `tar tzf dist/*.tar.gz`

lanfence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Stable State Consulting Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lanfence-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# Copyright (c) 2026-present Stable State Consulting Ltd
+# SPDX-License-Identifier: MIT
+
+include CONTRIBUTING.md CHANGELOG.md DISTRIBUTING.md

lanfence-0.1.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: lanfence
+Version: 0.1.0
+Summary: Defensive LAN device monitor - detect and alert on unauthorized devices joining your network
+Author-email: Stable State Consulting Ltd <contributors@lanfence.dev>
+Maintainer-email: Stable State Consulting Ltd <contributors@lanfence.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rosscooney/lanfence
+Project-URL: Source, https://github.com/rosscooney/lanfence
+Project-URL: Issues, https://github.com/rosscooney/lanfence/issues
+Keywords: network,security,defensive,arp,raspberry-pi,monitoring
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2.6
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: scan
+Requires-Dist: scapy>=2.5; extra == "scan"
+Dynamic: license-file
+
+# LAN Fence
+
+**LAN Fence is an open-source defensive network device monitor for Linux**
+(developed and tested on Raspberry Pi OS / Debian, and reasonably portable to
+other Debian/Ubuntu systems).
+
+- Source & downloads: <https://github.com/rosscooney/lanfence>
+  ([releases](https://github.com/rosscooney/lanfence/releases))
+- Package: [`lanfence` on PyPI](https://pypi.org/project/lanfence/)
+
+LAN Fence runs on a small Linux box (a Raspberry Pi is the common case) sitting
+on your network. It continuously scans for connected devices via ARP,
+maintains an allowlist of devices you already trust, and alerts in
+plain language when something unknown joins - a rogue device, unauthorized
+hardware, or a supply-chain implant on your LAN.
+
+LAN Fence **only observes**. It sends nothing beyond a standard ARP "who-has"
+request (the same thing every device on your LAN does routinely) and never
+touches, blocks, deauthenticates or spoofs anything.
+
+> ⚠️ LAN Fence **cannot prove a device is malicious, or that a MAC address is
+> genuine.** MAC vendor prefixes and hostnames are trivially spoofed by anyone
+> deliberately trying to blend in. A finding is a lead worth checking by hand,
+> not a verdict - use it as one input to your own judgement.
+
+## How it works
+
+1. **Active scanning** - LAN Fence periodically ARP-sweeps your subnet
+   (`lanfence scan` for one sweep, or on an interval inside `lanfence
+   monitor`), collecting every MAC/IP that answers.
+2. **Passive monitoring** - between active sweeps, `lanfence monitor` also
+   listens for ARP traffic on the wire, so a device that joins mid-interval is
+   caught sooner rather than waiting for the next sweep.
+3. Every sighting is folded into a persistent **SQLite database** keyed by MAC
+   address, which tracks each device's lifecycle: `new_device` the first time
+   it's ever seen, `reappeared` if it had gone offline and came back, and
+   `disconnected` when an active sweep no longer sees it.
+4. Each device is **fingerprinted**: an offline OUI → vendor lookup, a set of
+   built-in rogue-device signatures (see below), and a check of whether its
+   MAC is locally administered (randomized/spoofed rather than
+   vendor-assigned).
+5. Each device is checked against your **allowlist**
+   (`lanfence allow <mac>`). A brand-new or reappearing device not on the
+   allowlist produces a plain-language **finding** with a severity
+   (`high`/`medium`/`info`), a rationale, and a recommendation; an allowlisted
+   device is downgraded to `info` so your own hardware stops shouting every
+   time it reconnects.
+6. Findings can be dispatched to **syslog, email, or a webhook**, and
+   everything is available as a CLI table or JSON for automation.
+
+## Built-in rogue-device signatures
+
+Heuristics, not proof - a match is a lead to check by hand:
+
+| Signal | Category | Why it matters |
+|---|---|---|
+| Vendor: Espressif | `esp32_esp8266` | ESP32/ESP8266 - the chipset behind most cheap DIY hidden cameras, rogue APs, and ESP32-based Wi-Fi implants (as well as plenty of legitimate IoT). |
+| Vendor: Raspberry Pi | `raspberry_pi` | Legitimate everywhere, but also the common hardware basis for rogue network-tap / implant projects (P4wnP1, home-built taps). |
+| Vendor: ASIX Electronics | `usb_ethernet_gadget` | USB-Ethernet chipset used both by ordinary dongles and by BadUSB tools (Bash Bunny, LAN Turtle, O.MG cable) presenting as a network adapter. |
+| Hostname contains `pwnagotchi` | `pwnagotchi` | Pwnagotchi's distinctive default hostname. |
+| Hostname contains `bashbunny` / `lanturtle` / `pineapple` / `omg-cable` | Hak5/O.MG tooling | Default hostnames of common commercial implant/pentest hardware. |
+| Hostname contains `flipper` | `flipper_zero` | Flipper Zero (via its Wi-Fi dev board). |
+| Locally administered MAC | `locally_administered_mac` | No vendor OUI - common for privacy MAC-randomization on phones/laptops, but also for spoofed or gadget hardware. |
+
+Extend or override these with your own `rogue_signatures_file:` (same YAML
+shape as `lanfence/data/rogue_signatures.yaml`) and `vendor_file:` (same
+tab-separated shape as `lanfence/data/oui_vendors.txt`) in config.
+
+## Install
+
+```bash
+pipx install lanfence          # isolated, recommended
+# active/passive scanning needs the `scan` extra (scapy):
+pipx inject lanfence 'lanfence[scan]'
+```
+
+or
+
+```bash
+python3 -m venv ~/.venvs/lanfence
+~/.venvs/lanfence/bin/pip install 'lanfence[scan]'
+```
+
+Scanning needs raw-socket access, so `scan`/`monitor` typically need `sudo`
+(or `CAP_NET_RAW` on the interpreter). `allow`, `report` and `check` do not.
+
+## Commands
+
+```text
+lanfence scan                  # one-time active ARP scan; table + findings
+lanfence scan --format json    # same, machine-readable
+lanfence monitor                # continuous: active sweeps + passive sniffing
+lanfence allow <MAC> --name X   # trust a device; its findings become info
+lanfence allow --list           # show the allowlist
+lanfence allow --remove <MAC>   # untrust a device
+lanfence report --since 24h     # summarize events/findings from the database
+lanfence check                  # verify permissions, scapy, interface, storage
+```
+
+### Example: an unknown device joins
+
+```text
+$ sudo lanfence scan
+
+Devices seen (4)
+┌───────────────────┬──────────────┬──────────────┬────────────────────┬────────┬─────────┐
+│ MAC                │ IP           │ Hostname     │ Vendor              │ Status │ Trusted │
+├───────────────────┼──────────────┼──────────────┼────────────────────┼────────┼─────────┤
+│ b8:27:eb:12:34:56  │ 192.168.1.10 │ nas.local    │ Raspberry Pi        │ online │ yes (NAS)│
+│ 52:8a:1c:99:f4:2d  │ 192.168.1.47 │ [unknown]    │ [unknown]           │ online │ no      │
+└───────────────────┴──────────────┴──────────────┴────────────────────┴────────┴─────────┘
+
+Findings (1)
+
+  MEDIUM Unknown device connected
+    MAC: 52:8a:1c:99:f4:2d
+    The vendor bit pattern indicates a locally administered address rather
+    than one assigned by a hardware vendor. Common causes: MAC-randomization
+    privacy features on modern phones/laptops, virtual machines/containers,
+    or a device deliberately spoofing its address.
+    Recommendation: Verify this device belongs on your network. If it's
+    yours, run `lanfence allow 52:8a:1c:99:f4:2d` to stop future alerts.
+      • MAC: 52:8a:1c:99:f4:2d
+      • IP: 192.168.1.47
+      • Hostname: [unknown]
+      • Vendor: [unknown]
+      • mac = 52:8a:1c:99:f4:2d (U/L bit set, no vendor OUI match)
+
+Overall: 1 finding(s), highest severity: medium
+```
+
+## Running unattended
+
+LAN Fence does not ship its own scheduler; use `systemd` (recommended on a
+Pi) or `cron`.
+
+**Continuous monitoring** - `/etc/systemd/system/lanfence.service`:
+
+```ini
+[Unit]
+Description=LAN Fence continuous monitoring
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/lanfence monitor --config /etc/lanfence/config.yaml
+Restart=on-failure
+User=root
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable --now lanfence
+```
+
+**Daily report** - a cron entry (`sudo crontab -e`):
+
+```cron
+0 7 * * * /usr/local/bin/lanfence report --since 24h --format json > /var/log/lanfence/daily.json
+```
+
+## Configuration
+
+All settings are optional; everything has a sensible default. Pass
+`--config path/to/config.yaml` to any command.
+
+```yaml
+scan:
+  interface: null              # null = auto-detect
+  subnet: null                 # null = derive from the interface's own address
+  scan_interval_seconds: 60    # how often `monitor` repeats an active sweep
+  active_scan_timeout_seconds: 3
+  passive: true                # also sniff ARP traffic between sweeps
+  resolve_hostnames: true      # try reverse DNS for each device
+  dns_timeout_seconds: 1
+
+alerts:
+  min_severity: medium         # info | medium | high - dispatch threshold
+  syslog:
+    enabled: false
+    address: /dev/log
+    facility: user
+  email:
+    enabled: false
+    smtp_host: localhost
+    smtp_port: 587
+    use_tls: true
+    username: null
+    password: null
+    from_addr: null
+    to_addrs: []
+  webhook:
+    enabled: false
+    url: null
+    timeout_seconds: 5
+
+db_path: ~/.local/share/lanfence/lanfence.db
+allowlist_file: ~/.config/lanfence/allowlist.yaml
+vendor_file: null             # extra OUI table, merged with the packaged one
+rogue_signatures_file: null   # extra signatures, merged with the packaged ones
+```
+
+## Exit codes (`--fail-on-findings`)
+
+`scan` and `report` accept `--fail-on-findings` for CI/scripting use:
+
+| Highest severity in the result | Exit code |
+|---|---|
+| none / info | 0 |
+| medium | 10 |
+| high | 20 |
+
+## Privacy and security
+
+- **No telemetry, no external calls.** LAN Fence never phones home. The only
+  network destinations it ever contacts are ones *you* configure: your own
+  syslog daemon, your own SMTP relay, or your own webhook URL.
+- The vendor and signature databases are bundled, offline, and static -
+  nothing is fetched to "keep them fresh".
+- The device database and allowlist are written atomically and are
+  owner-readable only where the platform supports it.
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev,scan]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for scope and pull-request guidelines,
+and [DISTRIBUTING.md](DISTRIBUTING.md) for licensing notes on the optional
+`scapy` (GPL-2.0) dependency.
+
+## License
+
+MIT - see [LICENSE](LICENSE).