Automate your Unifi network firewall and traffic rules with Home Assistant

Unifi network traffic rules are one of the most valuable and versatile ways to manage traffic and devices on your network. It's a feature that's been around for a little while, and it enables you to quickly set up basic rules like blocking specific devices from accessing the internet at specific times, blocking particular domains and apps on the entire network, or even setting up speed limits on my guest network. One specific use case of interest to me right now is to help manage my kid's screen time. My kids use many devices: phones, laptops, tablets, gaming handhelds, VR headsets, etc. There are usually ways to manage screen time on those devices individually, but it's different for iOS, Windows, Chrome/Google, Meta, etc. Frankly, it's too much. The common denominator is that all these devices need internet access, bringing us back to why we are here. Traffic rules will help identify and block all of those devices, even apps on those devices, but we lose some of the ease of use that many of those OS-specific screen time services provide. Services like extending screen time, temporarily disabling it, or enabling it on-demand. This is where Home Assistant (HA) comes in. Like many of you, HA is the "brains" of my smart home and where all of my other devices and sensors integrate, which makes it an ideal choice to integrate this functionally in an easy-to-use way. We're getting into the weeds on this one, so let's get into it!

Establishing the Rules

Let's create a rule or two. Navigate to Unif Network -> Settings -> Security -> Traffic & Firewall, where there are two tabs: Simple and Advanced. Simple is synonymous with Traffic rules, and Advanced is synonymous with Firewall rules. Though they are different and offer different features in the user interface, they are both essentially firewall rules. The difference is important, though, as Unifi stores them differently, which will matter when it's time to integrate with HA. From what I can gather, a traffic rule is essentially a feature-wrapped firewall rule that allows you to do additional things, like set a schedule and target specific devices without setting up Profile groups or other more advanced ways of identifying devices on the network. It's more or less a user-friendly way to set up a rather complicated thing, which is basically why you might want to use Unifi over something like pfsense, for example.

Integrating with UDM

Currently, there is no officially supported way to integrate with most of the advanced features of Unfi devices, like my Dream Machine Pro SE. This may eventually change, given the recent announcement of an official API, but this first version focuses on integrating site manager with 3rd party applications. For now, we have to get a bit more creative and leverage some of the existing private APIs utilized by the web and mobile app interfaces we use today. I wanted to start with something simple: enable my spouse and I to quickly and easily turn the rules we've just established on and off. As you see above, I'm already leveraging the schedule feature of the traffic rule, which is fine most of the time, but we needed more flexibility than that. Perhaps there are exceptions; it's the holidays, or they are on break, etc. Logging into the UDM network application, finding the rule, managing, and then pausing is fine and normal for me, but this is an interface for network administrators. And even though I know where to go and what to do, it's far less than ideal for this type of functionality. I want Apple Home-level simplicity and the ability to set up automations and triggers. Now, let's figure out how to do it!

To help you (and me) along, I've created a Bruno collection with all of the requests you'll need to get started. Get it on GitHub.

Logging in

I'm going to log in programmatically just like the Unifi web interface logs in, by calling the private API. There are a couple of caveats to this. Typically, in a public API, I'm either assigned a token that I can use to access, or I authenticate to request and refresh a token. I do need a token here as well, but it's stored in a cookie, and I also need to capture and send my CSRF token, which ensures my request is authentic.

First, I send a POST with my username and password in the JSON body, then I grab the cookie and the csrf-token and set them to environment variables, which I can use in subsequent requests. You'll also receive a full json payload with your user information, roles, groups, etc. Using a Local Admin account is necessary to get the required permissions to manage firewall rules. You can see here that I'm using the local account homeassistant.

Getting the Rules

This was a little harder to discover, but with some investigation using the browser development tools and the help of Claude, I found that we need two endpoints. One to pull the list of Firewall (advanced) rules, and one to get the list of Traffic (simple) rules. Here, I'm sending two separate GET requests, first pulling the csrf-token and cookie from the environment (saved from the login request) and then passing in the header. You'll receive a JSON array with each rule and its associated details.

Toggling the Rules

This one was even more challenging to discover and to get working correctly. To toggle the enabled flag on a Traffic or Firewall rule, we need to send back the entire rule, similar to what a form submission would do on a web page. So, let's first get the individual rules to ensure we have the complete shape expected, modify the enabled property, and then post back the modified payload. Use caution here, as posting incorrect values could cause some severe issues. Here, you'll see that we have the same GET and PUT endpoint for Firewall rules and separate GET and PUT endpoints for Traffic rules, along with the full rule payload in both Toggle requests.

Now that we have proved we can modify both sets of rules via the API, it's time to use that knowledge for home automation.

Home Assistant

HA has a rich ecosystem of integrations and components, and there are several out-of-the-box integrations for Unifi network and Unifi protect, both of which I highly recommend. In this case, I'm exposing more advanced functionality not covered by those existing extensions, which means building a new integration. More specifically, creating my own custom component. There are quite a few excellent tutorials, along with HA's excellent developer documentation. Still, since I'm not a Python developer and we are in the AI age, I leveraged Claude and ChatGPT to scaffold out my new integration. Many, many chats later, I had something that was starting to resemble the functionality I wanted. It was a great way to get to the 90% mark faster, but I needed good old-fashioned coding and debugging skills to get that last 10%. I've found this typical for prototyping and building apps with AI.

This integration has been tested on my local instance of HA, is open source, and is ready for anyone else to test and contribute to. Get it on Github and soon via Home Assistant Community Store (HACS)

Configuration

Once installed, go to Devices and Services and Add Integration, select the Unifi Rule Manager, and enter your UDM's IP address, username, and password.

Entities

Once configured, all your rules will now be available as switch entities, allowing you to toggle them on/off on demand. The integration will also look for changes every 5 minutes and pull those in as they occur.

Build a Dashboard

I love using custom dashboards in HA. They're a great way to organize functionality around a room, topic, or set of devices. In this case, I created a new dashboard called Screen Time and will place the Traffic rules I want to toggle as big, giant buttons that are easy to use from your phone.

Wrap up

It was a non-trivial 😉 amount of work just for a few buttons, but it was a lot of fun, which is what it was all about for me. It's working well, and I plan to keep it working as changes occur and as time allows. Good luck on your own integration and automation journey, and let me know how it goes!