Assess Ubiquiti UniFi Security with cnspec

Rely on cnspec to ensure your Ubiquiti UniFi controllers follow recommended security and operational best practices, such as verifying firewall policies, checking wireless network security settings, validating threat management configuration, and assessing site-wide hardening settings.

Prerequisites

To test a UniFi controller with cnspec, you must have:

cnspec installed on your workstation
Network access to the UniFi controller management interface
Valid credentials: either a username and password, or an API key

Give cnspec access to your UniFi controller

To scan a UniFi controller, cnspec connects through the UniFi REST API over HTTPS. You can authenticate with either a local admin account or an API key.

Authentication setup

Option 1: Username and password

Use the credentials of a local administrator account on the UniFi controller. The account must have permissions to read site configuration and settings.

Option 2: API key

If your UniFi controller supports API keys (UniFi OS 4.x+), you can create a dedicated API key for cnspec:

Log in to the UniFi controller web interface.
Navigate to Settings > Control Plane > API Keys.
Create a new API key and copy the value.

API key authentication avoids storing username and password credentials and is the recommended approach for automated scanning.

Test your connection

Before running a full scan, verify that cnspec can connect by opening a cnspec shell.

With username and password:

cnspec shell unifi --hostname CONTROLLER_IP --username admin --ask-pass

With an API key:

cnspec shell unifi --hostname CONTROLLER_IP --api-key YOUR_API_KEY

To skip TLS certificate verification (for self-signed certificates):

cnspec shell unifi --hostname CONTROLLER_IP --username admin --ask-pass --insecure

If cnspec connects successfully and shows a prompt, you're ready to scan.

Connection options

Option	Description
`--hostname`	Hostname or IP address of the UniFi controller
`--port`	Port of the UniFi controller API (default: 443)
`--username`, `-u`	Username for authentication
`--password`, `-p`	Password for authentication
`--ask-pass`	Prompt for the password
`--api-key`	API key for authentication (alternative to username/password)
`--site`	UniFi site name (default: "default")
`--insecure`, `-k`	Skip TLS certificate verification

Scan UniFi controllers

To scan a UniFi controller, use the cnspec scan command:

cnspec scan unifi --hostname CONTROLLER_IP --username admin --ask-pass

Or with an API key:

cnspec scan unifi --hostname CONTROLLER_IP --api-key YOUR_API_KEY

To scan a specific site on a multi-site controller:

cnspec scan unifi --hostname CONTROLLER_IP --api-key YOUR_API_KEY --site mysite

Understand scan output

When a scan completes, cnspec prints a summary of all the checks it ran, grouped by policy. Each check shows a pass or fail result.

At the end of the output, cnspec shows a risk score from 0 (no risk) to 100 (highest risk). Failed checks include remediation guidance to help you fix issues.

You can also create your own policies or specify a particular policy bundle with --policy-bundle.

Example checks

You can interactively explore and test checks using the cnspec shell. To open a shell connected to your UniFi controller:

cnspec shell unifi --hostname CONTROLLER_IP --api-key YOUR_API_KEY

Below are some example checks you can run from the shell.

Ensure SSH is disabled on managed devices

cnspec> unifi.siteSettings.mgmt.sshEnabled == false
[ok] value: false

Ensure IPS mode is active (not just IDS)

cnspec> unifi.siteSettings.threatManagement.ipsMode == "ips"
[ok] value: "ips"

Ensure UPnP is disabled on the gateway

cnspec> unifi.siteSettings.gateway.upnpEnabled == false
[ok] value: false

Ensure DHCP snooping is enabled on switches

cnspec> unifi.siteSettings.globalSwitch.dhcpSnoop == true
[ok] value: true

Ensure automatic backups are enabled

cnspec> unifi.controllerSettings.autobackupEnabled == true
[ok] value: true

Ensure analytics collection is disabled

cnspec> unifi.controllerSettings.enableAnalytics == false
[ok] value: false

Learn more

To learn about all the UniFi resources and properties you can query, read the Ubiquiti UniFi Resource Pack Reference.
To learn more about how the MQL query language works, read Write Effective MQL.
For more information about UniFi, see the Ubiquiti documentation.

Assess Ubiquiti UniFi Security with cnspec

On this page