Skip to content

UniFi Network integration

The Block in UniFi Network rule response adds each IOC domain a matched rule cites to one firewall policy on your UniFi gateway. The policy blocks traffic from the zone you choose to those domains. Entries do not expire: a domain stays blocked until newer IOCs push it out of Have I Been Squatted’s queue. The rule decides which alerts trigger the response. Connecting an API key alone blocks nothing.

  • A UniFi gateway, such as a Cloud Gateway, a Dream Machine or another gateway console, running UniFi Network 10.1 or later with the zone-based firewall.
  • Console firmware (UniFi OS) 5.0.3 or later.
  • The console linked to a UI account, so it appears in Site Manager at unifi.ui.com.
  • An owner or super admin who can create API keys at unifi.ui.com.
  • The network enforcement add-on on the Have I Been Squatted organization, and an organization admin to configure it.

Have I Been Squatted reaches the console only through the Site Manager cloud connector at api.ui.com. It never connects to the console’s own address, so nothing on your network needs to be exposed.

  1. Sign in to unifi.ui.com as an owner or super admin.
  2. Open Settings > API Keys and select Create New API Key.
  3. Name the key, for example haveibeensquatted.
  4. Choose an Expiration. UniFi defaults to 1 month. Blocking stops when the key expires, so choose the longest period your policy allows, or Never Expires, and note when to replace it.
  5. Keep Site Manager selected, and under UniFi Applications keep only Network. Limit Sites to the site you will connect, or keep All Sites.
  6. Select Create and copy the key; UniFi shows it once.

An organization key reaches every console in the UI organization. A personal key reaches only the consoles its owner owns, not consoles another admin owns. The UniFi Applications scope lets the key read data and manage settings in the applications and sites you select, so treat it as able to change anything the UniFi Network API exposes there. Have I Been Squatted uses it only for the calls listed on this page.

When the key expires or is revoked, deliveries fail with an authentication error and Test connection reports Authentication. Create a new key and select Reconnect to replace it.

  1. In the app, open Connectors > UniFi Network.
  2. Paste the API key and select Discover.
  3. Choose the Console. Have I Been Squatted checks its UniFi Network version and lists its sites.
  4. Choose the Site. Have I Been Squatted lists its firewall zones.
  5. Choose the zone to Block traffic from. The default is the system Internal zone. Traffic is blocked on its way to the External zone.
  6. Select Connect.

The key is sent to Have I Been Squatted’s servers for each step and stored server-side only once the connection is saved. It is never returned to the browser.

To use a new key, site or zone, fill in the form again and select Reconnect. Rule responses are kept.

Connecting looks for a firewall policy named haveibeensquatted-<organization id>-iocs on the site. The organization id is Have I Been Squatted’s identifier for your organization.

  • No such policy: creates one.
  • A block policy with that name: reuses it, with its domains and zones as they are. This is the case after a reconnect.
  • Any other policy with that name: stops with a policy conflict. Rename or delete that policy and connect again.

A new policy is created with these settings:

Setting Value
Action Block
Source The zone you chose
Destination The External zone, matching a list of domains
Domains unifi-placeholder.haveibeensquatted.com until a rule adds IOC domains
IP version IPv4 and IPv6
Logging On: matched traffic is logged and reported in Insights flows
Description Marks the policy as managed by Have I Been Squatted

UniFi requires at least one domain in a domain policy, so the policy always holds the placeholder unifi-placeholder.haveibeensquatted.com. It is not an IOC and does not count toward the cap.

Connecting then places the policy first among the user-defined policies for its source and destination zones, so an allow policy of yours cannot let IOC traffic through first. The order of your other policies is kept. If placing the policy fails, a policy that this connect created is deleted again, and so is one whose connection cannot be saved.

Test connection checks the console’s UniFi Network version and reads the policy back. It changes nothing. A failing check pauses blocking until a later check passes.

Result Meaning
Authentication UniFi rejected the key. It may be wrong, expired or revoked.
Permission missing The key cannot reach the console, for example a personal key of another admin.
Console offline The console did not answer through the cloud connector in time.
Unsupported version UniFi Network is older than 10.1, or the console firmware predates the connector.
Zone-based firewall missing The site has no zone-based firewall, or no External zone.
Policy conflict The policy no longer blocks a list of domains, or another policy has its name.
Policy missing The policy was deleted. Connect again to create it.
Rate limited The console’s request limit was reached. Test again in a minute.
Unavailable or Invalid UniFi timed out or returned an unusable response. Test again later.
  1. Create or edit a rule and open the Response tab.
  2. Select Add action > Block in UniFi Network.
  3. Select the firewall policy destination.
  4. Save the rule.

The destination is listed only while the connection’s last check passed. The response needs at least one domain condition in the rule, because only cited domain records produce entries.

For each active rule alert that cites domain records, Have I Been Squatted reads the policy, works out its new domain list and replaces the whole list in one update, then reads the policy back to confirm it.

  • Only domains from cited domain (permutation) records are sent.
  • The monitored domain and its subdomains are never sent.
  • Email and canary evidence never produce entries.

Because the whole list is replaced at once, a domain that is already listed is never briefly unlisted. Have I Been Squatted treats every domain in the policy as part of its queue, so a domain you add by hand can be removed like any other once newer IOCs push it out, and the next delivery rewrites the list in queue order. Add your own domains to a separate policy instead.

Entries never expire, because an expiring block could lift just before a malicious domain is used again. Instead, Have I Been Squatted keeps up to 50,000 IOC domains in the policy, ordered from most to least recently cited:

  • A new domain joins the head of the queue.
  • A domain cited again moves back to the head, so an IOC that rules keep citing is not the one removed.
  • When the queue is full, each new domain removes the least recently cited domain.

UniFi documents no maximum number of domains in a firewall policy. If UniFi refuses the list, the delivery shows as failed.

Have I Been Squatted stores the API key, the console and site with their names, the policy’s ID and name, the source zone’s name, the UniFi Network version and count of IOC domains at the last check, and the time and outcome of the last connection check. For each alert and response, it records the delivery status, the domains added and removed, and, when a delivery fails, a short error code. The key and UniFi response bodies are not stored in delivery records.

Disable stops new entries and keeps the connection and rule responses. A passing connection test turns blocking back on.

Disconnect deletes the stored key and removes the Block in UniFi Network response from every rule, along with those responses’ delivery records.

Neither action deletes the firewall policy, and its entries do not expire, so it keeps blocking the domains it holds. When you no longer want it, delete the policy named haveibeensquatted-<organization id>-iocs in UniFi Network. To revoke access, delete the API key at unifi.ui.com.

  • The cloud connector allows 100 requests per minute per console and ends each request after 25 seconds. A delivery makes at most three requests, or one when the list does not need to change.
  • Have I Been Squatted keeps up to 50,000 IOC domains in the policy. UniFi documents no limit on the domains in a firewall policy, and a policy of that size has not yet been verified on a live gateway. A list UniFi refuses shows as a failed delivery.
  • UniFi does not document whether a domain entry also matches its subdomains. This has not yet been verified on a live console.
  • The connector has not yet been verified end to end on a live console.
  • One site per organization. To block on another site, connect that site instead.

Network Intelligence is not available for UniFi. The UniFi Network API exposes no traffic or DNS logs to read.