Firewalla MSP Integration for Home Assistant

Monitor one or multiple Firewalla MSP-managed devices from Home Assistant. Built against the Firewalla MSP API v2 for Home Assistant 2024.4+.

Note: Display of icons and logos in this integration require Home Assistant 2026.3+

---

Features

Feature	Default	Toggle
Box online/offline status	✅ Always	—
Device online/offline sensors	✅ Always	—
Device Tracker (presence detection)	✅ On	Options → Device Tracker
IP / MAC / Network sensors per device	✅ Always	—
Bandwidth (download/upload) per device	❌ Off	Options → Bandwidth Sensors
Active alarm count + details	❌ Off	Options → Alarm Sensors
Individual alarm binary sensors	❌ Off	Options → Alarm Sensors
Firewall rule switch (active/paused toggle)	❌ Off	Options → Rule Sensors
Per-flow traffic sensors	❌ Off	Options → Flow Sensors
Target list sensors (entry count + contents)	❌ Off	Options → Target List Sensors
Automatic stale device cleanup	✅ 30 days	Options → Stale Device Removal
Stale device tracking persists across HA restarts	✅ Always	—

Actions (Services)

Call these from automations, scripts, or Developer Tools → Actions:

Service	Description
firewalla.delete_alarm	Delete/dismiss an alarm (requires Alarm Sensors enabled)
firewalla.rename_device	Rename a network device (requires MSP 2.9+)
firewalla.search_alarms	Search alarms by query and return results to an automation via response_variable
firewalla.search_flows	Search network flows by query and return results to an automation via response_variable

Firewall rules are paused and resumed using the native switch.turn_off / switch.turn_on services targeting the rule's switch entity — no custom service required.

---

Installation

Option 1 — HACS (Recommended)

HACS gives you one-click installs and automatic update notifications.

If you don't have HACS yet:

1. Follow the HACS installation guide to install it in Home Assistant.

Add this repository to HACS:

1. In Home Assistant, go to HACS in the sidebar
2. Click the three-dot menu (⋮) in the top-right corner
3. Select Custom repositories
4. In the Repository field paste:

   https://github.com/shanelord01/hass-firewalla-ng
   

5. Set Type to Integration and click Add
6. Search for Firewalla in HACS and click Download
7. Restart Home Assistant when prompted

Option 2 — Manual

1. Download this repository as a ZIP (click Code → Download ZIP on GitHub)
2. Unzip it and copy the custom_components/firewalla folder into your Home Assistant config/custom_components/ directory (create custom_components if it doesn't exist)
3. Restart Home Assistant

---

Setup

After installing and restarting:

1. Go to Settings → Devices & Services
2. Click + Add Integration and search for Firewalla
3. Enter your MSP Subdomain — the part before .firewalla.net (e.g. enter mycompany for mycompany.firewalla.net)
4. Enter your API Token — In the Firewalla MSP portal go to Account Settings → Create New Token, give it a name, and copy the token
5. Choose which optional features to enable (you can change these later)
6. Click Submit

---

Options

All options can be changed after setup via Settings → Devices & Services → Firewalla → Configure:

Option	Description	Default
Poll Interval	How often to query the API (seconds)	300s (5 min)
Enable Alarm Sensors	Alarm count + per-alarm binary sensors	Off
Enable Rule Sensors	Active/paused switch per firewall rule	Off
Enable Flow Sensors	Per-flow transfer sensor (can create many entities)	Off
Enable Bandwidth Sensors	Download/upload totals per device	Off
Enable Device Tracker	Presence detection via ScannerEntity	On
Enable Target List Sensors	Entry count + contents per target list	Off
Stale Device Removal	Days before absent devices are removed from HA	30
Enable Debug Logging	Write verbose debug output to the HA log	Off

---

Using the Actions (Services)

Controlling Firewall Rules

When Enable Rule Sensors is on, each firewall rule gets a switch entity on the box device card. The switch reflects live rule state — On = Active, Off = Paused — and can be toggled directly from the dashboard or targeted in automations using the standard switch services:

# Pause a rule
action: switch.turn_off
target:
  entity_id: switch.my_firewalla_block_test_user

# Resume a rule
action: switch.turn_on
target:
  entity_id: switch.my_firewalla_block_test_user

You can find the exact entity ID in Settings → Devices & Services → [your Firewalla box] → entities.

Rule display names

Rule entities are named using the following priority:

1. Notes field — if you have filled in the Notes field on a rule in the Firewalla portal, that text is used as the display name (e.g. Block: Test User, Allow: Guest Printer Access).
2. Composite label — if no notes are set, the name is synthesised from the action, target, and scope: Block: Internet on group 13, Allow: deb.debian.org on pi4nut.

Device-scoped rules resolve the MAC address against your device list to show the device name. Network and group scopes show a generic label (network, group 13) as these require API endpoints not currently available in the Firewalla MSP API.

Tip: For the clearest rule names in Home Assistant, fill in the Notes field on each rule in the Firewalla portal.

Delete an Alarm

Requires Alarm Sensors to be enabled in options.

In Developer Tools → Actions, select Firewalla: Delete Alarm and use the entity picker to choose the alarm's binary sensor — no need to find internal IDs.

In automations or scripts:

action: firewalla.delete_alarm
target:
  entity_id: binary_sensor.firewalla_alarm_intrusion_detected

Rename a Device

Requires Firewalla MSP 2.9+.

In Developer Tools → Actions, select Firewalla: Rename Device and use the device picker to choose the network device, then enter the new name.

In automations or scripts:

action: firewalla.rename_device
target:
  device_id: a1b2c3d4e5f6g7h8
data:
  name: "My Laptop"

The device_id here is the Home Assistant device ID, visible in the URL when viewing the device page under Settings → Devices & Services.

Search Alarms

Returns matching alarms to the calling automation via response_variable. Useful for building automations that react to specific alarm conditions, devices, or traffic thresholds.

action: firewalla.search_alarms
data:
  query: "device.name:Kids_iPad transfer.total:>50MB"
  limit: 20
response_variable: alarm_results
# alarm_results.count  → number of matches
# alarm_results.results → list of alarm objects

Query syntax examples:

• status:active — only unresolved alarms
• device.name:iphone — alarms for a specific device
• transfer.total:>50MB remote.category:game — large gaming transfers
• ts:>1695196894 — alarms after a specific Unix timestamp

Full query syntax is documented in the Firewalla MSP API docs.

Search Flows

Returns matching network flows to the calling automation via response_variable. Useful for detecting traffic patterns, large transfers, or connections to specific domains.

action: firewalla.search_flows
data:
  query: "device.name:Kids_iPad category:game"
  limit: 20
response_variable: flow_results
# flow_results.count   → number of matches
# flow_results.results → list of flow objects

Query syntax examples:

• device.name:iphone direction:outbound — outbound iPhone traffic
• total:>1GB domain:*youtube* — large YouTube transfers
• direction:outbound region:CN — outbound connections to China

Both services paginate automatically and support up to 10 pages (500 results with default limit of 50) per call. Use the limit field (1–200) to tune results per page.

---

Migrating from v2.2.x

If you have existing automations using firewalla.pause_rule or firewalla.resume_rule, update them to use the native switch services:

Old	New
firewalla.pause_rule with rule_id: "abc123"	switch.turn_off targeting the rule switch entity
firewalla.resume_rule with rule_id: "abc123"	switch.turn_on targeting the rule switch entity

The rule switch entity ID can be found in the Firewalla box device card after enabling Rule Sensors. The rule_id value is still exposed as an attribute on the switch entity if you need it for reference.

---

Stale Device Cleanup

Devices not seen via the API for the configured number of days (default 30) are automatically removed from the Home Assistant device registry.

Protected devices — those referenced by automations, scenes, or scripts — are never removed automatically. You can still manually delete them via Settings → Devices & Services → [device] → Delete.

---

Debug Logging

Enable verbose debug logging directly from the integration options — no configuration.yaml changes or restart required.

Go to Settings → Devices & Services → Firewalla → Configure and toggle Enable Debug Logging on. Logs appear immediately in Settings → System → Logs. Disable the toggle when you are done troubleshooting.

---

Credits

• Original integration: blueharford/hass-firewalla
• Refactored: DaneManes/hass-firewalla
• Rewritten for HA 2024.4+: shanelord01/hass-firewalla-ng
• Initial Services and API fixes: TechButton/hass-firewalla-ng

---

Changelog

For full release history see Releases.