pumaguard 21.post21__tar.gz → 21.post27__tar.gz

{pumaguard-21.post21 → pumaguard-21.post27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pumaguard
-Version: 21.post21
+Version: 21.post27
 Author-email: Nicolas Bock <nicolasbock@gmail.com>
 Project-URL: Homepage, http://pumaguard.rtfd.io/
 Project-URL: Repository, https://github.com/PEEC-Nature-Youth-Group/pumaguard

pumaguard-21.post27/docs/CAPTIVE_PORTAL.md

@@ -0,0 +1,267 @@
+# Captive Portal Configuration
+
+## Overview
+
+The PumaGuard device is configured to act as a **captive portal** when devices connect to its WiFi hotspot. This means phones, tablets, and laptops will automatically detect the portal and prompt users to open the PumaGuard web interface.
+
+## How It Works
+
+The captive portal implementation uses a **selective DNS hijacking** approach that preserves internet connectivity while still triggering captive portal detection on client devices.
+
+### Architecture
+
+```
+Phone/Device
+    │
+    ├─► Connects to "pumaguard" WiFi (wlan0)
+    │
+    ├─► Receives DHCP: IP=192.168.52.x, Gateway=192.168.52.1, DNS=192.168.52.1
+    │
+    ├─► Device queries captive portal detection URLs
+    │   (connectivitycheck.gstatic.com, captive.apple.com, etc.)
+    │
+    ├─► dnsmasq intercepts these specific domains → returns 192.168.52.1
+    │
+    ├─► Device makes HTTP request to port 80
+    │
+    ├─► UFW NAT rule redirects: port 80 → port 5000
+    │
+    └─► PumaGuard web UI responds → Captive portal detected!
+```
+
+### Components
+
+1. **dnsmasq** (`/etc/dnsmasq.d/10-pumaguard.conf`)
+   - Hijacks only captive portal detection domains
+   - Forwards all other DNS queries to upstream server (eth0)
+   - Preserves internet connectivity
+
+2. **UFW NAT rules** (`/etc/ufw/before.rules`)
+   - Redirects port 80 → 5000
+   - Ensures HTTP traffic reaches PumaGuard web UI
+
+3. **hostapd** (`/etc/hostapd/hostapd.conf`)
+   - Creates WiFi access point on wlan0
+   - SSID: `pumaguard`
+
+## Captive Portal Detection Domains
+
+The following domains are hijacked to trigger captive portal detection:
+
+### Android
+
+- `connectivitycheck.gstatic.com`
+- `www.google.com`
+- `clients3.google.com`
+- `play.googleapis.com`
+
+### iOS/macOS
+
+- `captive.apple.com`
+- `www.apple.com`
+
+### Windows
+
+- `www.msftconnecttest.com`
+- `www.msftncsi.com`
+
+### Firefox
+
+- `detectportal.firefox.com`
+
+All other domains are resolved normally through the upstream DNS server.
+
+## Network Topology
+
+### Lab Setup (Internet Connectivity)
+
+```
+Internet
+    │
+Laptop (eth0) ←─── Raspberry Pi (eth0: 192.168.51.1)
+                         │
+                    Raspberry Pi (wlan0: 192.168.52.1)
+                         │
+                    WiFi Hotspot "pumaguard"
+                         │
+                    └─► Phone/Device (192.168.52.x)
+```
+
+In the lab:
+
+- Raspberry Pi eth0 connected to laptop
+- Traffic from wlan0 forwarded to eth0
+- DNS queries forwarded to laptop via eth0
+- Devices on hotspot have internet access
+
+### Field Deployment (Isolated Network)
+
+```
+Raspberry Pi (wlan0: 192.168.52.1)
+    │
+WiFi Hotspot "pumaguard"
+    │
+└─► Phone/Device (192.168.52.x)
+```
+
+In the field:
+
+- No eth0 connection
+- Isolated network for camera trap monitoring
+- DNS forwarding fails gracefully
+- Captive portal still works (port 80 redirect)
+
+## Testing the Captive Portal
+
+### On Android
+
+1. Connect to "pumaguard" WiFi
+2. Enter password: `pumaguard`
+3. Look for notification: "Sign in to network" or "Captive portal detected"
+4. Tap notification → browser opens to PumaGuard UI
+
+### On iOS/iPhone
+
+1. Connect to "pumaguard" WiFi
+2. Enter password: `pumaguard`
+3. Captive portal sheet automatically appears
+4. Shows PumaGuard web interface
+
+### On macOS
+
+1. Connect to "pumaguard" WiFi
+2. Enter password: `pumaguard`
+3. System Preferences may show "Log in" button
+4. Click to open PumaGuard UI
+
+### On Windows
+
+1. Connect to "pumaguard" WiFi
+2. Enter password: `pumaguard`
+3. Action Center may show "Additional sign-in may be required"
+4. Click to open PumaGuard UI
+
+### Manual Access
+
+If captive portal doesn't auto-trigger:
+
+- Open browser to `http://192.168.52.1:5000`
+- Or `http://pumaguard.local:5000`
+- Or just `http://192.168.52.1` (redirects to port 5000)
+
+## Troubleshooting
+
+### Captive Portal Not Triggering
+
+**Check DNS resolution:**
+
+```bash
+# From a device connected to the hotspot
+nslookup connectivitycheck.gstatic.com
+# Should return: 192.168.52.1
+```
+
+**Check dnsmasq logs:**
+
+```bash
+sudo journalctl -u dnsmasq -f
+```
+
+**Verify UFW port redirect:**
+
+```bash
+sudo iptables -t nat -L PREROUTING -n -v
+# Should show: tcp dpt:80 redir ports 5000
+```
+
+### Internet Connectivity Issues
+
+**Verify eth0 connection:**
+
+```bash
+ip addr show eth0
+# Should have IP on 192.168.51.x network
+```
+
+**Check routing:**
+
+```bash
+ip route
+# Should show routes for both 192.168.51.0/24 and 192.168.52.0/24
+```
+
+**Test upstream DNS:**
+
+```bash
+dig @192.168.51.1 google.com
+# Should resolve to real Google IP
+```
+
+### Phone Shows "No Internet"
+
+This is **normal** when captive portal detection domains are hijacked. The phone detects the portal is active. After interacting with the portal, some phones will show internet connectivity.
+
+If actual internet is needed:
+
+1. Ensure eth0 is connected to upstream network
+2. Verify `server={{ dnsmasq_wired_gateway }}` is active in dnsmasq config
+3. Check IP forwarding is enabled (handled by netplan configuration)
+
+## Configuration Files
+
+- **Ansible playbook:** `scripts/configure-device.yaml`
+- **dnsmasq template:** `scripts/templates/dnsmasq-wlan0.conf.j2`
+- **hostapd template:** `scripts/templates/hostapd.conf.j2`
+- **Deployed dnsmasq config:** `/etc/dnsmasq.d/10-pumaguard.conf`
+- **Deployed hostapd config:** `/etc/hostapd/hostapd.conf`
+- **UFW rules:** `/etc/ufw/before.rules`
+
+## Security Considerations
+
+- Only port 80 (HTTP) triggers the portal - HTTPS traffic is not intercepted
+- DNS hijacking limited to captive portal detection domains only
+- Firewall (UFW) restricts access to only necessary services
+- Hotspot password required (default: `pumaguard` - **change in production!**)
+
+## Customization
+
+### Change Hotspot SSID/Password
+
+Edit `scripts/configure-device.yaml`:
+
+```yaml
+vars:
+  hostapd_ssid: "my-custom-ssid"
+  hostapd_passphrase: "my-secure-password"
+```
+
+### Disable Captive Portal (Full Internet Access)
+
+Edit `scripts/templates/dnsmasq-wlan0.conf.j2`:
+
+```bash
+# Comment out all the address=/ lines for captive portal domains
+# Keep only:
+address=/pumaguard.local/{{ dnsmasq_gateway }}
+server={{ dnsmasq_wired_gateway }}
+```
+
+### Change IP Range
+
+Edit `scripts/configure-device.yaml`:
+
+```yaml
+vars:
+  dnsmasq_dhcp_start: "192.168.52.50"
+  dnsmasq_dhcp_end: "192.168.52.150"
+  dnsmasq_gateway: "192.168.52.1"
+```
+
+## References
+
+- **dnsmasq documentation:** https://thekelleys.org.uk/dnsmasq/doc.html
+- **hostapd documentation:** https://w1.fi/hostapd/
+- **Captive portal detection:**
+  - Android: https://android.googlesource.com/platform/frameworks/base/+/master/services/core/java/com/android/server/connectivity/NetworkMonitor.java
+  - iOS: https://www.apple.com/library/test/success.html
+  - Windows: https://docs.microsoft.com/en-us/windows/win32/nativewifi/portal-detection

{pumaguard-21.post21 → pumaguard-21.post27}/docs/source/Performance.rst

@@ -37,6 +37,6 @@ References
 .. [A53ARM] https://www.arm.com/products/silicon-ip-cpu/cortex-a/cortex-a53
 .. [A53Wikipedia] https://en.wikipedia.org/wiki/ARM_Cortex-A53
 .. [Pi5] https://www.raspberrypi.com/products/raspberry-pi-5/
-.. [A76ARM] https://developer.arm.com/Processors/Cortex-A76
+.. [A76ARM] https://www.arm.com/products/silicon-ip-cpu/cortex-a/cortex-a76
 .. [A76Wikipedia] https://en.wikipedia.org/wiki/ARM_Cortex-A76
 .. [RaspberryPerformance] https://web.eece.maine.edu/~vweaver/group/green_machines.html

pumaguard-21.post27/pumaguard/pumaguard-ui/.last_build_id

@@ -0,0 +1 @@
+3269bc90c80e0ca8fecacfb7533f77fc

{pumaguard-21.post21 → pumaguard-21.post27}/pumaguard/pumaguard-ui/flutter_bootstrap.js

@@ -34,6 +34,6 @@ addEventListener("message", eventListener);
 if (!window._flutter) {
   window._flutter = {};
 }
-_flutter.buildConfig = {"engineRevision":"78fc3012e45889657f72359b005af7beac47ba3d","builds":[{"compileTarget":"dart2js","renderer":"canvaskit","mainJsPath":"main.dart.js"},{}],"useLocalCanvasKit":true};
+_flutter.buildConfig = {"engineRevision":"db373eb85a06eb3d706af362a45d42d0972f4b46","builds":[{"compileTarget":"dart2js","renderer":"canvaskit","mainJsPath":"main.dart.js"},{}],"useLocalCanvasKit":true};
 
 _flutter.loader.load();

{pumaguard-21.post21 → pumaguard-21.post27}/pumaguard/pumaguard-ui/main.dart.js

@@ -1714,7 +1714,7 @@ s.id=c
 b.appendChild(s)
 A.aXO(s,a,"normal normal 14px sans-serif")},
 aXO(a,b,c){var s,r,q,p=v.G
-a.append(p.document.createTextNode(b+" flt-scene-host {  font: "+c+";}"+b+" flt-semantics input[type=range] {  appearance: none;  -webkit-appearance: none;  width: 100%;  position: absolute;  border: none;  top: 0;  right: 0;  bottom: 0;  left: 0;}"+b+" input::selection {  background-color: transparent;}"+b+" textarea::selection {  background-color: transparent;}"+b+" flt-semantics input,"+b+" flt-semantics textarea,"+b+' flt-semantics [contentEditable="true"] {  caret-color: transparent;}'+b+" .flt-text-editing::placeholder {  opacity: 0;}"+b+":focus { outline: none;}"))
+a.append(p.document.createTextNode(b+" flt-scene-host {  font: "+c+";}"+b+" flt-semantics input[type=range] {  appearance: none;  -webkit-appearance: none;  width: 100%;  position: absolute;  border: none;  top: 0;  right: 0;  bottom: 0;  left: 0;}"+b+" input::selection {  background-color: transparent;}"+b+" textarea::selection {  background-color: transparent;}"+b+" flt-semantics input,"+b+" flt-semantics textarea,"+b+' flt-semantics [contentEditable="true"] {  caret-color: transparent;}'+b+" .flt-text-editing::placeholder {  opacity: 0;}"+b+":focus { outline: rgb(0, 0, 0) none 0px;}"))
 if($.bg().gdY()===B.bs)a.append(p.document.createTextNode(b+" * {  -webkit-tap-highlight-color: transparent;}"+b+" flt-semantics input[type=range]::-webkit-slider-thumb {  -webkit-appearance: none;}"))
 if($.bg().gdY()===B.cY)a.append(p.document.createTextNode(b+" flt-paragraph,"+b+" flt-span {  line-height: 100%;}"))
 if($.bg().gdY()===B.cC||$.bg().gdY()===B.bs)a.append(p.document.createTextNode(b+" .transparentTextEditing:-webkit-autofill,"+b+" .transparentTextEditing:-webkit-autofill:hover,"+b+" .transparentTextEditing:-webkit-autofill:focus,"+b+" .transparentTextEditing:-webkit-autofill:active {  opacity: 0 !important;}"))
@@ -92634,7 +92634,7 @@ A.Ob.prototype={
 K(a){var s,r=null,q=A.aA1(B.ae,r,r,B.nU)
 q=A.r8(B.mN,r,new A.mC(r,r,r,r,2,r,new A.cL(A.hY(12),B.u)),q,"Roboto",!0)
 s=A.aA1(B.aj,r,r,B.nU)
-return new A.Bw(new A.w3(new A.adF(),r,r,r,r,t.Gj),r,r,new A.AH(B.I0,"PumaGuard v21-21-g130964d",q,A.r8(B.mN,r,new A.mC(r,r,r,r,2,r,new A.cL(A.hY(12),B.u)),s,"Roboto",!0),B.Bn,!1,r),r,t.Bp)}}
+return new A.Bw(new A.w3(new A.adF(),r,r,r,r,t.Gj),r,r,new A.AH(B.I0,"PumaGuard v21-27-gd6de676",q,A.r8(B.mN,r,new A.mC(r,r,r,r,2,r,new A.cL(A.hY(12),B.u)),s,"Roboto",!0),B.Bn,!1,r),r,t.Bp)}}
 A.adF.prototype={
 $1(a){return new A.mu()},
 $S:556}
@@ -92997,7 +92997,7 @@ q=A.aj("System Information",h,h,h,h,A.l(q).ok.r,h,h)
 s=i.d
 s=s==null?h:s.b
 s=i.um("Backend Version",s==null?"Unknown":s)
-n=i.um("UI Version","v21-21-g130964d")
+n=i.um("UI Version","v21-27-gd6de676")
 l=i.d
 k=l==null
 j=k?h:l.d

{pumaguard-21.post21 → pumaguard-21.post27}/pumaguard/web_routes/settings.py

@@ -468,6 +468,16 @@ def register_settings_routes(app: "Flask", webui: "WebUI") -> None:
                 }
             )
 
-        except Exception as e:  # pylint: disable=broad-except
+        except Exception:  # pylint: disable=broad-except
             logger.exception("Error uploading sound file")
-            return jsonify({"error": str(e)}), 500
+            return (
+                jsonify(
+                    {
+                        "error": (
+                            "An internal error occurred while uploading the "
+                            "sound file."
+                        )
+                    }
+                ),
+                500,
+            )

{pumaguard-21.post21 → pumaguard-21.post27}/pumaguard.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pumaguard
-Version: 21.post21
+Version: 21.post27
 Author-email: Nicolas Bock <nicolasbock@gmail.com>
 Project-URL: Homepage, http://pumaguard.rtfd.io/
 Project-URL: Repository, https://github.com/PEEC-Nature-Youth-Group/pumaguard

{pumaguard-21.post21 → pumaguard-21.post27}/pumaguard.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ docs/CAMERA_INTEGRATION.md
 docs/CAMERA_STATUS_REFRESH.md
 docs/CAMERA_TRACKING.md
 docs/CAMERA_URL_TROUBLESHOOTING.md
+docs/CAPTIVE_PORTAL.md
 docs/DYNAMIC_URL_DETECTION.md
 docs/HEARTBEAT_FEATURE.md
 docs/IMAGE_BROWSER.md

{pumaguard-21.post21 → pumaguard-21.post27}/scripts/configure-device.yaml

@@ -211,6 +211,16 @@
       tags:
         - firewall
 
+    - name: Enable IPv4 forwarding
+      ansible.posix.sysctl:
+        name: net.ipv4.ip_forward
+        value: "1"
+        sysctl_set: true
+        state: present
+        reload: true
+      tags:
+        - firewall
+
     - name: Configure UFW NAT rules for port 80 to 5000 redirect
       ansible.builtin.blockinfile:
         path: /etc/ufw/before.rules
@@ -230,6 +240,47 @@
       tags:
         - firewall
 
+    - name: Configure UFW NAT masquerading for IP forwarding
+      ansible.builtin.blockinfile:
+        path: /etc/ufw/before.rules
+        insertbefore: "^# Don't delete these required lines"
+        marker: "# {mark} ANSIBLE MANAGED BLOCK - PumaGuard NAT masquerading"
+        block: |
+          # NAT table rules for masquerading (IP forwarding)
+          *nat
+          :POSTROUTING ACCEPT [0:0]
+
+          # Enable masquerading for outbound traffic on eth0
+          -A POSTROUTING -o eth0 -j MASQUERADE
+
+          # Commit NAT rules
+          COMMIT
+      notify: Restart ufw
+      tags:
+        - firewall
+
+    - name: Configure UFW FORWARD chain rules for wlan0 to eth0 traffic
+      ansible.builtin.blockinfile:
+        path: /etc/ufw/before.rules
+        insertbefore: "^# Don't delete these required lines"
+        marker: "# {mark} ANSIBLE MANAGED BLOCK - PumaGuard FORWARD rules"
+        block: |
+          # FORWARD chain rules for traffic between wlan0 and eth0
+          *filter
+          :FORWARD ACCEPT [0:0]
+
+          # Allow existing connections to return from eth0 to wlan0
+          -A FORWARD -i eth0 -o wlan0 -m state --state RELATED,ESTABLISHED -j ACCEPT
+
+          # Allow new requests from the hotspot (wlan0) to go out via eth0
+          -A FORWARD -i wlan0 -o eth0 -j ACCEPT
+
+          # Commit FORWARD rules
+          COMMIT
+      notify: Restart ufw
+      tags:
+        - firewall
+
     - name: Enable logging for dropped packets
       community.general.ufw:
         logging: "medium"
@@ -479,7 +530,7 @@
       tags:
         - networking
 
-    - name: Configure dnsmasq for wlan0 hotspot
+    - name: Configure dnsmasq for wlan0 hotspot (captive portal)
       ansible.builtin.template:
         lstrip_blocks: true
         trim_blocks: true
@@ -491,6 +542,10 @@
       notify: Restart dnsmasq
       tags:
         - networking
+      # This configures selective DNS hijacking for captive portal detection domains only.
+      # Real DNS queries are forwarded to eth0 for internet connectivity.
+      # Combined with port 80->5000 redirect, this triggers captive portal detection
+      # on phones/devices while preserving internet access through the wired interface.
 
     - name: Configure hostapd for wlan0 access point
       ansible.builtin.template:

{pumaguard-21.post21 → pumaguard-21.post27}/scripts/templates/dnsmasq-wlan0.conf.j2

@@ -26,12 +26,33 @@ expand-hosts
 # Static DNS entry for pumaguard.local
 address=/pumaguard.local/{{ dnsmasq_gateway }}
 
+# Captive Portal Detection Configuration
+# Hijack only captive portal detection domains to trigger portal on client devices
+# This allows internet connectivity while still triggering captive portal behavior
+
+# Android captive portal detection
+address=/connectivitycheck.gstatic.com/{{ dnsmasq_gateway }}
+address=/www.google.com/{{ dnsmasq_gateway }}
+address=/clients3.google.com/{{ dnsmasq_gateway }}
+address=/play.googleapis.com/{{ dnsmasq_gateway }}
+
+# iOS/macOS captive portal detection
+address=/captive.apple.com/{{ dnsmasq_gateway }}
+address=/www.apple.com/{{ dnsmasq_gateway }}
+
+# Windows captive portal detection
+address=/www.msftconnecttest.com/{{ dnsmasq_gateway }}
+address=/www.msftncsi.com/{{ dnsmasq_gateway }}
+
+# Firefox captive portal detection
+address=/detectportal.firefox.com/{{ dnsmasq_gateway }}
+
 # Enable IPv6 Router Advertisements
 enable-ra
 # IPv6 DHCP range for wlan0
 dhcp-range={{ dnsmasq_ipv6_prefix }}:10,{{ dnsmasq_ipv6_prefix }}:2000,{{ dnsmasq_lease_time }}
 
-# Upstream DNS server (wired network)
+# Upstream DNS server (wired network) - preserves internet connectivity
 server={{ dnsmasq_wired_gateway }}
 
 # Enable logging

pumaguard-21.post21/pumaguard/pumaguard-ui/.last_build_id

@@ -1 +0,0 @@
-e01c6dcff88825e413a1183b5781dab4