Securing Your Home Assistant Instance

Community Guides
,
1

I was reading a post about a security issue on another home automation platform and was going to provide a few links in the thread as people often read these threads and look for advice on how to ensure they are secure. I found my own past post on the issue lacking and the HA docs somewhat lacking or the information was really dispersed. This is my attempt to put a guide together and collect the information in one location.

Note: I am far from a security expert and I have no formal training in this area. The information in this guide is what I have gathered from my own use of Home Assistant and my research to secure it and other web services on my network. I am expecting the community to correct me where I am wrong or where the guide could be improved and will do my best to keep it up to date.

Scope and Directory of Contents

This guide will focus on securing a Home Assistant (HA) installation exposed to the greater internet. There are a number of ways to accomplish this but they all expose your HA front end/User Interface (UI) to anyone with an internet connection.

This guide will cover the core of HA and access to the HA Frontend/User Interface. There are other areas to be considered but I have a feeling this guide is going to be big enough as is without going into securing other services that can be exposed via HA.

I don’t intend this to be a how-to guide on every item discussed, for the most part there are really good guides developed on most of these topics by the community. I will link to them where I am aware of them and encourage you to share a link for a guide you find useful.

This guide will also primarily focus on providing remote access via what I believe are the most commonly used methods Nabu Casa’s Remote UI, and opening/forwarding a port and utilizing duckDNS and Let’s Encrypt. I know there are a ton of other options, including alternate DNS providers, utilizing a reverse proxy and using CloudFlare. I just don’t have experience with those personally to provide the input. I would love if someone could add that content and I will link to it in the directory below.

No single item in this guide will secure your instance. Security requires layers of security tools and methodologies to prevent a security breach. The Swiss Cheese Model is a good example. Every layer of security can have a hole (vulnerability) but when stacked and utilized together most issues are stopped and hopefully their are still layers of prevention left. As an example, if you encrypt your traffic, try to hide your instance from searches and always install the latest security patches on your systems but don’t set a password for your HA instance, all the other layers put in place are negated as the instant someone locates your instance they are let right in. Thanks Finity

logo
logo1347×744 76.8 KB

13 Likes
2

Why Do I Need To Secure My Home Assistant Instance?

This should be obvious, however, anyone with a connection to your instance can control your lights (low risk/annoyance) or change your Heating/Cooling settings (higher risk) or depending on your setup, unlock doors or open a garage door (high risk). Furthermore, with some of the addons and the option to use Ingress someone could have access to your HA configuration files or shell access and therefore access to your entire network. Given that HA requires storing of a number of passwords or other security keys to interface with other services, you could easily expose a number of your passwords very quickly.

Besides the obvious risk of freezing your house or opening a door, the access to information is likely more valuable to someone with bad intent and not in your local area. If you don’t practice good Password Hygene getting access to the passwords/secrets on your HA instance could allow a bad actor access to a number of accounts and allow them to take over access to important accounts. Furthermore, with full network access deploying ransomware would be a breeze and your information could be locked up until you pay up to unlock it.

How Would Anyone Ever Find My Instance?

Your HA instance, when exposed to the greater internet is one of billions of web pages, how would someone find it? There are services that crawl the web to see what is out there. Some of these are for research purposes and are for all intents and purposes ‘good guys’. There are also a lot of bad guys out there, anyone with an internet connection can scan the entire web.

I currently use Nabu Casa’s Remote UI and don’t have any ports open. However, if I review my firewall logs, I see constant attempts at different ports on my network. Its constant, 24/7/365 and completely normal. Some of these attempted connections are the aforementioned services which crawl the web looking for what is currently ‘out there’. Your instance exposed to the internet is not hidden in any way and will be found.

One of the better known services is Shodan. Shodan has a fleet of scanners that collect data about what is ‘out there’ and provides a search engine to allow anyone to search their database of what is ‘out there’ on the internet. Run a search for Home Assistant and as of writing this you will have the information needed to connect to over 80,000 HA instances.

Even if you use Nabu Casa’s Remote UI, your not as hidden as one might think. If a vulnerability was discovered in HA, a bad actor could easily retrieve a list of each Nabu Casa Connection and each instance is a click away.

4 Likes
3

Securing Your Home Assistant Instance (Basics)

Passwords

Home Assistant requires a password be setup upon installation. Practice good Password Hygene.

Using strong and unique passwords goes for each user that has access to your HA instance. You are only as secure as yoru weakest password.

Multi-Factor Authentication (MFA)

Should your password or another user on your HA instance have a weak or comprimised password, MFA will provide another layer of security to stop a bad actor from accessing your HA instance. See the link to the HA docs below on setting up MFA.

The same controls should be employed for MFA as for passwords. You and any user on your instance should have MFA setup. Again, your security is only as strong as your weakest link.

Visiblity / User Access

As of writing this, restricting views and changing admin rights doesn’t provide a lot of added security. Limiting views is more security through obscurity but it can’t hurt.

User Levels

HA currently offers three User Account levels. Owner, Admin and general user. As noted above and in the docs, this currently doesn’t provide any real added security but it is a good thing to have setup. Any user that isn’t required to be an admin, remove that privilege by visiting their user account page and clicking the toggle for admin to off.

View Access

Anyone who knows what they are doing with HA can bypass this easily, however changing the Visibility will stop a layman. This just limits what a specific user can see and can allow you to restrict visibility of certain views on your HA instance to only those who need them.

Limit Access Attempts

Home Assistant, by default, will let someone pound on the proverbial front door until they give up or gain access. Failed login attempts are documented on the HA frontend via persistent notification, however, unless you are looking at your instance regularly someone could be making attempts for a long time before it gets noticed.

IP filtering and banning

Setup the IP filtering and banning tool in HA, this will block someone from making further attempts after a set number of failed logins.

Note1: Make sure you have another way in should you accidently ban yourself through this method. As someone who may have done this before, ensure you have another way in. You will need to access HA from another IP address or modify the ‘’‘ip_bans.yaml’‘’ file and restart to remove the restriction.

Note2: The Nabu Casa Remote UI and possibly other configurations (Reverse Proxies) may not pass the unique IP of the computer trying gain access through to your HA instance. This means if you are away and get banned you will be banned from using that connection regardless of the IP you are accessing from as the same IP address is always presented to HA.

Get Notified of Failed Login Attempts

As noted above, by default, HA presents failed login attempts as a persistent notification on the frontend. My preference is to have these automatically sent to me so I am aware immediately that they are happening. Adding the following automation to your instance will notify you of any failed attempts and remote the persistent notification.

- alias: "Send notification upon failed login attempt"
  id: 04e7a1c2-5c61-47d7-9731-afa883742c09
  trigger:
    - platform: state
      entity_id: persistent_notification.http_login
  condition:
    - condition: template
      value_template: "{{ trigger.to_state.state != 'None' }}"
  action:
    - service: notify.home_assistant
      data_template:
        title: "{{ states.persistent_notification.http_login.attributes.message }}"
        message: 'url: https://whatismyipaddress.com/ip/{{ states.persistent_notification.http_login.attributes.message.split ("from ") [1]}}'
    - service: persistent_notification.dismiss
      data:
        notification_id: "http_login"

Hosting Files

This is covered in the Home Assistant HTTP docs but is often overlooked and I have seen a number of people post about it on the forum as a concern when they discover it.

Files included in the www folder in your main configuration directory are available to anyone to view. Anyone with a web connection can view these files even without being logged in or otherwise authenticated. Don’t put anything in this folder you don’t want anyone in the world to see.

Keep Everything Up To Date

Keep your Operating System, Home Assistant, Add-Ons and anything else associated with your instance or network up to date. A lot of security vulnerabilities are discovered on all kinds of devices every day, an equal amount of fixes are rolled out on a frequent basis.

To my knowledge, there have only been two direct security vulnerabilities for Home Assistant (these have been patched a long time ago) However, Home Assistant uses a lot of other sources of code/packages/etc. which are also updated and may be patching a security hole. Keep it all up to date and you will have the latest fixes for any security issues.

Check your router/firewall/modem (box witch connects you to the internet) for updates also.

Avoid Exposing Personal Information

Don’t set the Name/Location of your home assistant instance to include any Personal Identifiable Information. See this thread for more information.

Additionally, don’t use any personally identifiable information for your domain name.

3 Likes
4

Securing Your Home Assistant Instance (Remote Access)

The Home Assistant Docs provide some basic information on securing your instance. The goal of this section is to expand on that information.

A Note On DuckDNS
DuckDNS is a service that turns a IP address that is hard to remember (eg. 95.214.19.127) into something simple to remember like quackquack.duckdns.org and if setup properly can be automatically updated to always send quackquack.duckdns.org to your HA instance even when your IP address changes.
Using DuckDNS or any other dynamic DNS provider does not add a lick of security. I have often seen DuckDNS credited when people discuss securing their instance and just want to ensure people understand what these dynamicDNS services do and that they do not add to your security.

Opening/Forwarding A Port

Opening and Forwarding a port are used interchangeably in this guide. To allow access from outside your home network you forward a port and tell your router/firewall to forward anyone who knocks on that door to wherever you prescribe within your network. This can be seen as the equivalent as leaving a door/window open on your house as anyone can come in.

Typically port 443 or 8123 is forwarded to your HA instance (also on port 8123). This directs anyone from outside your network that specifies your IP address or domain and the proper port to your HA instance.

A Note on Port 443: Port 443 is the default port of HTTPS (encrypted) traffic. Most modern web browsers default to HTTPS and therefore port 443 when you type in a web address or IP address. Port 443 is also heavily scanned by the services previously mentioned in this guide as it is the default port for many websites.

Only open the port(s) you need to and using a less common port will reduce the amount of traffic that open port sees. As mentioned previously port 443 is the default for a HTTPS traffic and is scanned rather heavily. 8123 is likely to be scanned less unless someone is specifically looking for HA instances as that is the primary port opened for HA according to the previously mentioned Shodan Search.

Picking an uncommon port, say something above 20K, provides no actual security. It does however keep you out of view of many scanning tools and most scans. This significantly cuts down on attempts, and noise in the logs. It makes it much easier to see things of concern. Credit: Tinkerer

Ports and their usage are rather well documented if you want to find an uncommon port. Using port 443 is easy as entering https://95.214.19.127 or https://quackquack.duckdns.org defaults to 443 and a port doesn’t need to specified in the browser. Using 8123 or another less common port requires the port to be specified (eg.https://quackquack.duckdns.org:8213)

Encrypting Your Home Assistant Traffic

When accessing any site or your HA instance without encrypting the traffic means that everything is passed in plain text for anyone with access to see. Anything you enter into the browser (passwords for example) are sent in plain text and anyone can view/read it.

Let’s Encrypt (no pun intended) your traffic. As stated previously this is one of many methods available to encrypt your traffic. This method is chosen as I believe its the most commonly used method, its free, and easy to setup. If you don’t have access to the HA add-ons you’ll need to do some searches on the forum for how to accomplish these tasks.

Install the DuckDNS add-on by visiting the Supervisor Page, and then the add-on store. The instructions for configuring the add-on and your HA instance to encrypt the traffic are included in the add-on configuration page for each add-on. Here is a video which provides a walkthrough of setting things up.

Utilizing a VPN

A Virtual Private Network (VPN) is basically your private tunnel back into your home network from anywhere with an internet connection. This is an alternative to opening a port (although some VPN setups need an open port) and can be utilized without the need for a separate encryption setup as all the VPN traffic is encrypted.

Below are some examples of secure and relatively easy to setup VPNs that are available as add-ons. There are a ton of other examples out there and your router/firewall/modem (box that connects you to the internet) may have a built in VPN tool that can be utilized.

3 Likes
5

Security Checkups (Test your security and test it often)

Checking How you Appear to the rest of the Internet

I’m going to copy/paste a Previous Post here and add some additional content.

Sharing a bit of a lessons learned. I test what my external web profile looks like somewhat regularly to ensure I haven’t made any stupid mistakes and opened my self up.

Running a few of my regular searches on Shodan and to my surprise I showed up. Even though I have ports open, they are limited to IP address that I specify. Generally, this means that scanners like Shodan do not see anything active on the open ports as they are not one of the specified IPs.

However, I made a change last week (and only for the week while I was out of town) which opened me up. There is a bug (at least I think its a bug) in my firewall firmware that causes the issue, I knew of the issue but didn’t think about it surfacing in this fashion.

Just a heads up to be testing your security regularly. You may have made a change that impacts your security in ways you didn’t realize.

Since I have gotten questions on what I do to check after these types of posts, here is what I check. I would be interested in seeing what others do also.

  1. From an public computer try accessing your instance from a browser, see what happens, see what the response looks like. Test your passwords (if it connects) and confirm you are getting a failed login notification. If you have a limit on incorrect passwords, confirm you get locked out after the limit.

  2. Periodic checks on Shodan. Check for your domain, IP and look for results under home assistant, homeassistant or any other key words you can think of to see if you show up. Note that this can lag a bit as Shodan has to scan your IP which may not be very frequent.
    https://www.shodan.io/

  3. Run the scans on GRC’s Shields Up.
    GRC | ShieldsUP! — Internet Vulnerability Profiling  

  4. From a public IP (this can’t be done inside your network use a Coffee Shop, Public Wifi etc.) run a scan with Nmap.
    https://nmap.org/

There are phone based apps that can do some of these scans also, however, I have gotten some false positives when on a LTE connection due to the way the connection is made. This seems to be the case for others to with the ports that were showing open.

If shodan, the shields up test or nmap show an open port, there are two things to think about. First did you intend to have that port open? If not, then that needs to be addressed. If you did intend to have it open the test is just confirming that. What this means is anyone in the world with an internet connection can see that open port to. Whatever service you have running on that port better be secure as anyone can access it. Test that security, use strong passwords and 2 factor authentication when possible.

Confirming Your Security Settings

Basically, you can go through this guide again and confirm that each step is still setup in the manner you intended. We all make changes to our configuration, sometimes in making those changes, we forget to apply the security rules we have in place. Its a good idea to periodically check up on everything.

  • Are passwords for all users still strong and not reused?
  • Is MFA setup for all users
  • Is everything up to date (OS, HA, Add-ons)
  • etc.
2 Likes
6

Securing Your Network

Content to Be added at a later date.

7

Useful Links

Dynamic DNS Setup

  • DuckDNS Setup Video (add-on) - Link

Encrytion Setup

  • Setup Video (via DuckDNS add-on) - Link

Remote Access Setup

Security Vulnerabilities

  • Home Assistant - Link

VPN Setup

8

What is usually missing in most of the information like the HA docs and even this guide is to point out the interaction between the different “security” layers and what each provides and what they don’t.

Such as the recommendation for Letsencrypt.

It does what it’s designed to do very well - it encrypts traffic between you and your HA instance so that others can’t snoop in on it.

But what is doesn’t do is provide any extra “first level” security - if you have open ports and weak passwords then no amount of encryption will prevent someone from accessing your HA instance.

I liken it to a steel pipe with one end connected to you and the other connected to your HA. Using Letsencrypt another person looking onto the side of the pipe can’t see the data flowing thru the pipe. But if they got to the open end of the pipe they could easily see your HA at the other end.

There are even people who think that having their own DuckDNS domain provides extra security and have no idea that isn’t remotely true. they have no idea what it actually is doing. All DuckDNS does is adds a friendly easy to remember name to the open end of the pipe.

They see it bundled along with Letsencrypt and assume that it adds some more security somehow.

9

Some additional thoughts:

  1. Running a proxy server means you can have limited remote access to Home Assistant. For instance, I allow remote access to a handful of webhooks, and nothing else. If I want access to the UI then I use a VPN.
  2. Running a proxy server also makes it easy to use tools like fail2ban, or a web app firewall. With those you can automatically lock out sources of probes.
  3. Picking an uncommon port, say something above 20K, provides no actual security. It does however keep you out of view of many scanning tools and most scans. This significantly cuts down on attempts, and noise in the logs. It makes it much easier to see things of concern.
1 Like
10

Good point, I wonder if I can find a good swiss cheese model graphic. No single item prevents access by a ‘bad actor’ you need all the layers of security working together.

I thought I covered that here. Is something else needed?

11

Ive dabbled with proxies but cannot write anything worthwhile as I lack the experience. I would happily accept any write-ups or links on the subject to add.

Thanks, added.

12

That is not correct, people can snoop even when https/ssl is used. This is why it is so important to not use free public wifi for example, just because you see a lock icon and https does not mean you are safe.
GRC | SSL TLS HTTPS Web Server Certificate Fingerprints

Also if you wish to scan to check if your port 8123 is open, see this page.
GRC | ShieldsUP! — Single Port Probe

13

Well, technically yes, but it’s a lot more challenging. It’s explained here and here for those who want to know more. The short version is that you need to get the device to trust the CA issuing certificates for the SSL proxy/intercept host.

For most people the risks of this are pretty low.

14

On the VPN section, do we want to mention other alternatives for readers to decide which works best for his/her situation? I can think of a couple: ZeroTier One, Tailscale, or Tor, even. All three of those are part of the Community Add-ons, just like WireGuard.

15

Nope sorry.

I somehow completely missed that note.

16

Good point, I added the Wireguard one out of convenience while I was writing but there are other options that fit the same parameters of secure, easy to setup, and available via an add-on. I revised the VPN Section to provide a list of all three.

I haven’t used TOR and from my understanding its not really a VPN per se and therefore would go into its own category. If you have experience with it and want to provide some content please do so. Otherwise I think there used to be some info in the docs that I could link to or steal from.

Thanks for the feedback.

17

Although not truly a form of intrusion, a Distributed Denial of Service (DDOS) attack is yet another ‘hack’. One can consider it to be a spiteful reaction to the inability to penetrate a system: if we can’t get in, we can prevent you from getting in too.

CloudFlare provides free protection from DDOS and can become yet another slice in your Swiss Cheese model.

2 Likes
18

@silvrr

I’m not sure if you realize or not but as a wiki we can only edit the first post in the thread.

All of the other posts afterward are only editable by their author.

If you knew that then…nevermind.