Create the Whitelist Alias in the Web UI in pfsense+
To protect critical corporate assets, VIP hardware, or network testing infrastructure from being accidentally quarantined, we can implement an allowlist (whitelist). The cleanest way to do this inpfSense is to reference a dedicated Firewall Alias inside our tracking loop. This allows you to manage whitelisted devices directly from the pfSense user interface without ever needing to touch the background script again.
Step 1: Create the Whitelist Alias in the Web UI
- Navigate to Firewall > Aliases > IP tab.
- Click Add to create a new alias:
- Name: Hotspot_Whitelist (Case-sensitive; must match the script exactly)
- Type: Host(s)
- Description: Devices permitted to bypass TTL mismatch hotspot restrictions.
- In the Properties section, add the static IP addresses or network blocks of your executive laptops, administrative workstations, or authorized infrastructure [pfsense.org].
- Click Save and Apply Changes.
Step 2: Update the Script to Cross-Reference the Whitelist
We will modify the core loops to query the pfctl table of our whitelist alias before taking any blocking actions.
- Open your /root/hotspot_alert.sh file and replace its contents with this updated script:
bash #!/bin/sh # pfSense Hotspot Auto-Block & Alert Script (With UI Whitelist Support) AUTHORIZED_TTL=65 LOG_FILE="/var/log/filter.log" ALERT_LOG="/var/log/hotspot_alerts.log" BLOCK_ALIAS="Hotspot_Blocklist" WHITELIST_ALIAS="Hotspot_Whitelist" echo "Monitoring logs for hotspots. Whitelist cross-referencing active..." clog $LOG_FILE | while read -r line; do if echo "$line" | grep -q "ttl $(($AUTHORIZED_TTL - 1))"; then SRC_IP=$(echo "$line" | awk -F',' '{print $12}') TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S") [ -z "$SRC_IP" ] && continue # 1. Check if the offending IP exists within the UI Whitelist Alias if pfctl -t $WHITELIST_ALIAS -T show 2>/dev/null | grep -q "$SRC_IP"; then # Log the bypass event silently for audit purposes, but do not block echo "[BYPASS] $TIMESTAMP - Whitelisted device $SRC_IP generated a TTL mismatch." >> $ALERT_LOG continue fi # 2. Check if IP is already blocked to avoid duplicate rule reloads if ! pfctl -t $BLOCK_ALIAS -T show 2>/dev/null | grep -q "$SRC_IP"; then # Push the untrusted IP address to the quarantine table pfctl -t $BLOCK_ALIAS -T add "$SRC_IP" ALERT_MSG="[BLOCK SYSTEM] $TIMESTAMP - Device $SRC_IP blocked for unauthorized hotspotting." echo "$ALERT_MSG" >> $ALERT_LOG # Send high-priority notification to administrators /usr/local/bin/php -r "require_once('notices.inc'); file_notice('Hotspot_Block', '$ALERT_MSG', 'Network Security', true);" # Automatically remove the block after 2 hours (7200 seconds) (sleep 7200 && pfctl -t $BLOCK_ALIAS -T delete "$SRC_IP") & fi fi done
Use code with caution.
Step 3: Verify and Maintain the Whitelist
- Adding a New Allowed Device: When a new device requires hotspot privileges, simply go to Firewall > Aliases, edit Hotspot_Whitelist, append their static IP address, and click Save. The script will pick up the addition immediately.
- Confirming Whitelist Traversal: You can monitor your custom dashboard text widget or check /var/log/hotspot_alerts.log. Whitelisted devices will clearly display a [BYPASS] entry instead of a [BLOCK SYSTEM] action.
Now that your automated mitigation engine is fully operational with whitelist capabilities, would you like to build a weekly PDF report script to track network infractions, or do you have any specific DHCP static mapping questions to make sure target devices keep their whitelisted IPs? if yes let us know, then we will publish the script.