Skip to content

DOCS.md

Latest commit

 

History

History
162 lines (104 loc) · 7.37 KB

DOCS.md

File metadata and controls

162 lines (104 loc) · 7.37 KB

Documentation

Congrats, you have a home Intrusion Detection System!

Installation

🚨 Warning: Home Detector is only support on 64bit processors, i.e. x86_64 (amd64) or ARM64 (aarch64) this is due to modern cryptography libraries (used by Open Canary) requiring rust which is not provided in the base python/alpine 32bit docker images. For Raspberry Pi users, that means Pi 4 or newer.

DNS Anomaly Detection for IoT

Home Detector implements a DNS server, it's not indent to replace complex solutions like PiHole, but rather complement them. It is strongly recommended that you do not point Phones/PCs/Laptops at this DNS server, you won't get much benefit. Where you do benefit is by configuring your Smart-Home or IoT devices as Home Assistant/Detector as a DNS server.

What happens when IoT uses Home Assistant/Detector as a DNS server?

By Default, if you update your local DNS to use Home Detectors DNS server, nothing happens, all requests are passed through and resolved. However if you enable Anomaly Detection, then Home Detector will start creating a baseline of Domains your IoT/Smart-Home devices talk to. The baseline will be learnt over 30days, and after that learning period will become fixed. Any new Domains observed will generate an alert.

Setting up DNS Anomaly Detection

By default DNS inspection is disabled, that is DNS requests pass-through without any anomaly detection, you must designate devices you wish to inspect, below is an example for setting Local IoT Networks:

- address: 192.168.1.10
  type: host
- address: 192.168.1.20-192.168.1.25
  type: range
- address: 192.168.2.0/24
  type: network

Upstream DNS Servers

By default Home Detector will use Home Assistant DNS server, you can change this like so...

- server: 8.8.8.8
  port: 53
- server: 1.1.1.1
  port: 53

If you run another DNS server on Home Assistant, like Pi-hole or DNSguard you need to grab their local name and use that, e.g for my DNSCrypt addon

- server: ba53f40c-dnscrypt-proxy
  port: 53

Custom DNS Host Records (A)

If you need something resolvable, you can avoid it being sent upstream by creating custom A records:

- name: homeassistant.internal
  address: 192.168.1.1

Detect on Host Query

Are you a hard-core paranoid security/privacy nerd, oh boy, you're gonna love this! By Default Home Detector will alert on Domain variations, but if you enable this feature it'll start tracking and alerting on the host level. For nice devices, no drama, but if you have an Amazon Alexa prepared to be spammed as that thing connects to a whole bunch of random hosts all the time!

DNS Firewall (Blocking)

By default nothing is blocked. If you wish to enable DNS Blocking, toggle this to on.

👉🏼 This will change in future versions - blocking will soon be the default.

Unknown IP Action

By default, only configured IPs are subject to inspection. You can enable it for all with this toggle, however IMPORTANT NOTE laptops/phone are incredibly noisy, as soon as 30days (learning mode) is up, an alert will be created for every new site visited, you probably don't want that ;)

Learning Mode Duration & Network Scope TTL (Time to Live)

Anomaly detection works by recording all the DNS requests for a fixed period of time and then once over alerting when there is a deviation from this baseline.

  • Learning Mode Duration -> Default 30days -> How long to create the baseline
  • Network Scope TTL -> How often the Source IP should be re-validated to check it's learning status

Default Behaviours

  • During leaning mode, domains and queires are added to the database, they are allowed an no alerts are generated.
  • After learning mode, any new domain (or query, if enabled), will be blocked and an alert is generated.

Manually Changing the status of a Network/Host scope

To manually update a Scope to toggle between Learning and Blocking

  1. Open the Home Detector Dashboard select Tuning
  2. Toggle the block from Off to On

NOTE: "block" only block if DNS firewalling is enabled.

Manually Changing the status of a Domain (Query)

To manually update a query, i.e. to allow or block

  1. Open the Home Detector Dashboard select DNS
  2. Toggle the block from Off to On for Blocking
  3. Toggle the alert from Off to On for Alerting

NOTE: "block" only block if DNS firewalling is enabled.

Open Canary Honeypot

Home Detector is an implementation of Open Canary, currently it's not configurable but you can enable upto 3x different detection mechanisms:

  1. Telnet
  2. FTP
  3. Web Server

What's a Honeypot, and what can it detect?

A honeypot is a security tool that can help computer systems defend against cyber attacks, a target to lure threat actors away from legitimate targets. By default, only the Telnet honeypot is enabled, what this means is, if you connect (telnet) to your home assistant server, instead of getting a CLI like SSH, it'll generate an alert, for any username/password combination you type.

Can I break into Home Assistant via the Honeypot?

Nope! The open ports are a python process faking a log-in prompt, there's nothing behind them.

Honey Pot Setup

By default, Telnet (TCP/23) is enabled. Under the add-on configuration page, scroll to the bottom where the Network Ports are, toggle Show disabled ports .

  • Enable the HTTP Honeypot by Setting a Port -> 80
  • Enable the FTP Honeypot by Setting a Port -> 21

After the add-on restarts, if you browse to http://homeassistant.local (or whatever) you'll see a fake NAS page, it'll generate an alert, for any username/password combination you type.

Advanced Configuration

As of version 0.0.5, the opencanary.conf file is now stored in the /addon_configs/ba53f40c_homedetector/, see https://opencanary.readthedocs.io for details on what you can do.

Note: Services available will be limited by Port Forwarding configuration in Home Assistant.

Ignoring Hosts/IPs that hit the Honey Pot

OpenCanary supports pattern matching for ignoring Alerts.

Alerts from OpenCanary are sent to Home Assistant via a localhost WebHook, therefore to ignore events from 192.168.1.1 update the existing so that it looks like this:

"Webhook": {
    "class": "opencanary.logger.WebhookHandler",
    "url": "http://localhost:8099/notify",
    "method": "POST",
    "headers": {
        "Content-Type": "application/json"
    },
    "data": {
        "message": "%(message)s",
        "type": "opencanary"
        },
    "status_code": 200,
    "ignore": ["192.168.1.1"]
}

Example Automations

The following automations are available in the docs folder:

Delayed Start

An example automation for starting up Home Detector 30sec after boot: automation_delayed_start.yml

Notify via webhook

Example automation for generating custom alerts via the webhook: automation_webhook_notify.yml