Mistborn is your own virtual private cloud platform and WebUI that manages self hosted services, and secures them with firewall, Wireguard VPN w/ PiHole-DNSCrypt, and IP filtering. Optional SIEM+IDS. Supports 2FA, Nextcloud, Jitsi, Home Assistant, +
MIT License
A secure platform for easily standing up and managing your own cloud services: including firewall, ad-blocking, and multi-factor WireGuard VPN access
WireGuard Management in Mistborn
As featured in Linux Magazine (Linux Pro Magazine in North America) in November 2020
[[TOC]]
The term Mistborn is inspired by Brandon Sanderson's Cosmere.
Mistborn started as a passion project for a husband and father protecting his family. Certain family members insisted on connecting their devices to free public WiFi networks. We needed a way to secure all family devices with a solid VPN (WireGuard). Once we had that we wanted to control DNS to block ads to all devices and block malicious websites across all family devices. Then we wanted chat, file-sharing, and webchat services that we could use for ourselves without entrusting our data to some big tech company. And then... home automation. I know I'll be adding more services so I made that easy to do.
As a Certified Information Systems Security Professional (CISSP) and an Offensive Security Certified Professional (OSCP), I designed Mistborn thinking about how it would be attacked by both external and internal threats. In making design trade-off decisions I tend to the paranoid. See Technical and Security Insights.
Ideal for teams who:
See the Mistborn Network Security wiki page to see the network scan results for Mistborn.
Mistborn depends on these core open source technologies:
These tools are not vital to Mistborn itself but are integrated to enhance security, ease, and features:
These tools can be turned on from the Mistborn Security Operations Center:
Within Mistborn is a panel to enable and manage these free extra services (off by default), locally hosted in Docker containers:
Tested Operating Systems (in order of thoroughness):
Formerly supported Operating Systems (your mileage may vary):
Note: Install operating system updates and restart. Raspberry Pi OS particularly needs to be restarted after kernel updates (kernel modules for the currently running kernel may be missing).
Tested Browsers:
The default tests are run on DigitalOcean Droplets: 2GB RAM, 1 CPU, 50GB hard disk.
The Mistborn docker images exist for these architectures:
Mistborn Docker Images (hub.docker.com) | Architectures |
---|---|
mistborn (django, celery{worker,beat}) | amd64, arm64, arm/v7 |
dnscrypt-proxy | amd64, arm64, arm/v7 |
Recommended System Specifications:
Use Case | Description | RAM | Hard Disk |
---|---|---|---|
Bare bones | WireGuard, Pihole (no Cockpit, no extra services) | 2 GB | 15 GB |
Default | Bare bones + Cockpit | 2 GB+ | 15 GB |
Low-resource services | Default + Vaultwarden, Tor, Syncthing | 4 GB | 20 GB |
High-resource services | Default + Jitsi, Nextcloud, Jellyfin, Rocket.Chat, Home Assistant, OnlyOffice | 6 GB+ | 25 GB+ |
SIEM | Default + Wazuh + Extras | 16 GB+ | 100 GB+ |
One line direct installation
wget -O install.sh https://gitlab.com/cyber5k/mistborn/-/raw/master/scripts/install.sh && sudo -E bash ./install.sh
OR
Clone repository and examine files first
git clone https://gitlab.com/cyber5k/mistborn.git
# Examine files if desired
sudo -E bash ./mistborn/scripts/install.sh
Get default admin WireGuard profile wait 1 minute after "Mistborn Installed" message
sudo mistborn-cli getconf
Connect via WireGuard then visit http://home.mistborn
For more information, see the Installation section below.
Mistborn protects your data in a variety of ways:
See the Mistborn Network Security wiki page to see more network diagrams and the network scan results for Mistborn.
The home page receives WireGuard status updates from the server via WebSocket connections. Superusers receive detailed updates about all connections and profiles. Regular users see details about their own devices.
The Mistborn Security Operations Center provides SIEM services with Wazuh. The Wazuh Manager requires an Open Distro for Elasticsearch backend. When the Mistborn host has >8 GB RAM the provided Elasticsearch backend can be used. Just click "Start Wazuh" on the Security Center
page and enjoy your Enterprise-grade SIEM. Wazuh agents can be installed on just about any OS and all Wazuh agent traffic is communicated over the WireGuard connections. Instructions for adding endpoint agents can be found within Wazuh itself.
Mistborn's Wazuh installs and integrates with Suricata running on Mistborn with logs ingested into Wazuh.
The Wazuh Kibana plugin leverages the power of Elasticsearch:
Pihole provides a way to block outgoing DNS requests for given lists of blocked domains. Coppercloud provides a way to block outgoing network calls of all types to given lists of IP addresses (IPv4 only for now). This is especially useful for blocking outgoing telemetry (data and state sharing) to owners of software running on all of your devices.
This example shows Coppercloud blocking a list of Microsoft IP addresses on a network with Windows 10 clients.
Gateways have been deprecated in Mistborn 2+
Note: Since in Mistborn 2+ a single (or few) WireGuard ports are exposed, simple router port-forwarding enables the same features formerly allowed by Gateways.
Former documentation:
We were getting frustrated at being forced to choose between being connected to our VPN and using streaming services that we have paid for.
Netflix blocking my connections that it sees coming from a DigitalOcean droplet
In Mistborn, Gateways are upstream from the VPN server so connections to third-party services (e.g. Netflix, Hulu, etc.) will appear to be coming from the public IP address of the Gateway. I setup a Gateway at home (Raspberry Pi with wireguard
and openresolv
installed) and with our Mistborn on DigitalOcean, all WireGuard profiles created with this Gateway will appear to be coming from my house and are not blocked. No port-forwarding required (assuming Mistborn is publicly accessible).
The Gateway adds an extra network hop. DNS is still resolved in Mistborn so pihole is still blocking ads.
Remote desktops enable multiple users to share desktop resources and data. Remote desktops also enable groups to prevent sensitive data from ever entering an endpoint devices such as a smartphone. For reference, some United States Government regulations require controls to protect Controlled Unclassified Information (CUI) that are not feasible to implement on all endpoint devices and remote desktops prevent the data from entering the device (see NIST SP 800-171 3.1.19, CMMC AC.3.022).
Mistborn enables remote desktop access via the Apache Guacamole extra service, which supports VNC, RDP, SSH, and other protocols.
Guacamole implements its own users and groups access controls to manage access to individual desktops. All Mistborn users must be authenticated with Mistborn (via WireGuard only or MFA) to access the Guacamole interface.
By default direct communication between network clients is blocked. Mistborn clients can all talk to Mistborn and communicate via shared services (Jitsi, Nextcloud, etc). Direct client to client communication can be enabled via the "client-to-client" toggle.
Mistborn is regularly tested on Ubuntu 20.04 LTS (DigitalOcean droplet with 2 GB RAM). It has also been successfully used on Debian Buster and Raspbian Buster systems (though not regularly tested). Make sure to install OS updates and restart before installing Mistborn (WireGuard installs differently on recent kernels).
Clone the git repository and run the install script:
git clone https://gitlab.com/cyber5k/mistborn.git
sudo -E bash ./mistborn/scripts/install.sh
Running install.sh
will do the following:
mistborn
system user/opt/mistborn
cockpit
system user (if Cockpit is installed)/opt/mistborn_volumes
and setup folders for services that will be mounted within/opt/mistborn_volumes
in /opt/mistborn_backup
/etc/systemd/system
In order to install without interaction some environment variables need to be pre-set.
See the environment variables needed in ./scripts/noninteractive/.install_barebones
This will perform a noninteractive install with the default environment variables set in .install_barebones
.
git clone https://gitlab.com/cyber5k/mistborn.git
sudo -E bash -c "source ./mistborn/scripts/noninteractive/.install_barebones && ./mistborn/scripts/install.sh"
When Mistborn-base starts up it will create volumes, initialize the PostgreSQL database, start pihole, run Django migrations and then check to see if a Mistborn superuser named admin
exists yet. If not, it will create the superuser admin
along with an accompanying default WireGuard configuration file and start the WireGuard service. You can watch all of this happen with:
sudo journalctl -xfu Mistborn-base
The default WireGuard configuration file for admin
may be obtained via:
sudo mistborn-cli getconf
Please notice that the following lines are NOT part of the WireGuard config:
Starting mistborn_production_postgres ... done
Starting mistborn_production_redis ... done
PostgreSQL is available
The WireGuard config will look like this:
# "10.15.91.2" - WireGuard Client Profile
[Interface]
Address = 10.15.91.2/32
# The use of DNS below effectively expands to:
# PostUp = echo nameserver 10.15.91.1 | resolvconf -a tun.%i -m 0 -x
# PostDown = resolvconf -d tun.%i
# If the use of resolvconf is not desirable, simply remove the DNS line
# and use a variant of the PostUp/PostDown lines above.
# The IP address of the DNS server that is available via the encrypted
# WireGuard interface is 10.15.91.1.
DNS = 10.15.91.1
PrivateKey = cPPflVGsxVFw2/lMmhiFTXMmH345bGqoqArD/NgjiXU=
[Peer]
PublicKey = DfIV1urYZXqXKiU4rOSfO0Iu589pEO+59dHV5w5N0mU=
PresharedKey = Z1SO5NuAnZ7JhzVCuUnYOQLWOQYmMoqG0pG1SNXUlh0=
AllowedIPs = 0.0.0.0/0,::/0
Endpoint = <Mistborn public IP address>:39207
Install wireguard on your computer. If you get a resolvconf: command not found
error when starting WireGuard then install openresolv: sudo apt-get install -y openresolv
/etc/wireguard/wg_admin.conf
on your computersudo systemctl start wg-quick@wg_admin
sudo systemctl enable wg-quick@wg_admin
Mistborn users can be added (non-privileged or superuser) and removed by superusers. Multiple WireGuard profiles can be created for each user. A non-privileged user can create profiles for themselves. WireGuard Management in Mistborn
Mistborn makes extra services available. Mistborn Extra Services Available
Mistborn functions as a network firewall and provides metrics on blocked probes from the internet. Mistborn Firewall Metrics
There are multiple ways to authenticate and use the system.
Mistborn Multi Factor Authentication - Authenticator App Setup
Mistborn always authenticates with WireGuard. You must have a valid WireGuard configuration file associated with the correct internal IP address. A classic Mistborn profile (WireGuard Only) will allow you to access the internet and all services hosted by Mistborn once you have connected via WireGuard. Note: individual services may require passwords or additional authentication.
In addition to WireGuard, you may create a Mistborn profile enabling multi-factor authentication (MFA). You must first connect to Mistborn via WireGuard. Then all internet traffic will route you to the Mistborn webserver where you must first setup and thereafter authenticate with an app (Google Authenticator, Authy, etc.). You must go to http://home.mistborn to complete the authentication process.
Mistborn Multi Factor Authentication Prompt
Internet access is blocked via iptables until authentication is completed for an MFA profile. You must go to http://home.mistborn to complete the authentication process. Click "Sign Out" to re-block internet access until authentication completes again.
Mistborn Multi Factor Authentication - Token Prompt
Mistborn service access is blocked via traefik until Mistborn authentication is complete. You will not be able to access the web pages for pihole, cockpit, or any extra services until authentication is complete for an MFA profile. Attempting to visit one of these pages will produce a "Mistborn: Not authorized" HTTP 403. Click "Sign Out" to re-block access until authentication completes again.
Mistborn Multi Factor Authentication - Not Authorized (Login Incomplete)
Mistborn uses the following domains (that can be reached by all WireGuard clients):
Service | Domain | Default Status |
---|---|---|
Home | home.mistborn | On |
Pihole | pihole.mistborn | On |
Cockpit | cockpit.mistborn | On |
Nextcloud | nextcloud.mistborn | Off |
Rocket.Chat | chat.mistborn | Off |
Home Assistant | homeassistant.mistborn | Off |
Vaultwarden | bitwarden.mistborn | Off |
Jellyfin | jellyfin.mistborn | Off |
Syncthing | syncthing.mistborn | Off |
OnlyOffice | onlyoffice.mistborn | Off |
Jitsi | jitsi.mistborn | Off |
Guacamole | guac.mistborn | Off |
RaspAP | raspap.mistborn | Off |
Wazuh | wazuh.mistborn | Off |
These are the default credentials to use in the services you choose to use:
Service | Username | Password |
---|---|---|
Pihole | {{default mistborn password}} | |
Cockpit | cockpit | {{default mistborn password}} |
Wazuh | mistborn | {{default mistborn password}} |
Nextcloud | mistborn | {{default mistborn password}} |
Guacamole | mistborn | {{default mistborn password }} |
RaspAP | mistborn | {{default mistborn password}} |
You can find the credentials sent to the Docker containers in: /opt/mistborn/.envs/.production/
Mistborn will generate the WireGuard configuration script for the Gateway. From a base Ubuntu/Debian/Raspbian operating system the following packages are recommended to be installed beforehand:
mistborn/scripts/subinstallers/wireguard.sh
)On Mistborn:
View Config
on the Gateways tab in MistbornOn Gateway:
/etc/wireguard/gateway.conf
sudo systemctl start wg-quick@gateway
sudo systemctl enable wg-quick@gateway
All your devices can be connected to Mistborn as WireGuard clients.
First steps:
All of you device network traffic is now being routed through WireGuard. Ads and malicious sites are blocked by pihole. DNS queries are verified via DNScrypt.
But wait, there's more! You can:
Android | Apple | |
---|---|---|
Nextcloud | Nextcloud | Nextcloud |
Syncthing | Syncthing | |
Jitsi Meet | Jitsi Meet | Jitsi Meet |
Bitwarden | Bitwarden | Bitwarden |
Jellyfin | Jellyfin | Jellyfin |
Home Assistant | Home Assistant | Home Assistant |
Rocket.Chat | Rocket.Chat | Rocket.Chat |
Some apps require TLS (HTTPS). All traffic to Mistborn domains already occurs over WireGuard but to keep apps running, a TLS certificate exists for Mistborn and can be imported into your device's trusted credentials in the security settings. This certificate is checked every day and will be re-generated when expiration is less than 30 days away.
The TLS certificate can be found here:
/opt/mistborn_volumes/base/tls/cert.crt
Frequently Asked Questions
The Docker services mount volumes located in:
/opt/mistborn_volumes
The core Mistborn services have volumes mounted in /opt/mistborn_volumes/base
. These should not be modified. The extra services' volumes are mounted in:
/opt/mistborn_volumes/extra
Your data from Nextcloud, Syncthing, Vaultwarden, etc. will be located there.
If Mistborn is installed via SSH then an iptables rule is added allowing external SSH connections from the same source IP address only. If Mistborn was installed locally then no external SSH is permitted.
SSH is permitted from any device connected to Mistborn by WireGuard.
Password authentication in enabled. Fail2ban blocks IPs with excessive failed login attempts.
You can SSH using the Mistborn domain when connected by WireGuard:
ssh [email protected]
The upstream servers used by dnscrypt-proxy are set in:
base.yml
:
services:
...
dnscrypt-proxy:
...
environment:
...
- DNSCRYPT_SERVER_NAMES=[...]
The available options are here: https://download.dnscrypt.info/dnscrypt-resolvers/v2/public-resolvers.md
This is a manual process for the foreseeable future because it is destructive and cannot be undone. In order to purge an extra service do the following:
This can be done from the Mistborn GUI or:
sudo systemctl stop Mistborn-<service name>
sudo systemctl disable Mistborn-<service name>
Locate the correct folder: sudo ls -ahl /opt/mistborn_volumes/extra/
Be careful:
Now remove the folder: sudo rm -r /opt/mistborn_volumes/extra/<service name>
Locate the file: sudo ls -ahl /opt/mistborn/.envs/.production/
Be careful:
Now remove the file: sudo rm /opt/mistborn/.envs/.production/.<service name>
Now you can restart the service from the GUI or manually and it should be a first run experience.
Once you're connected to WireGuard you should see .mistborn domains and the internet should work as expected. Be sure to use http (http://home.mistborn). WireGuard is the encrypted channel so there's usually no need to bother with TLS certs (WebRTC functionality and some mobile apps require TLS so it is available). Here are some things to check if you have issues:
Check if you can ping an external IP address:
ping 1.1.1.1
Check if you can resolve local DNS queries:
dig home.mistborn
Check if you can resolve external DNS queries:
dig cyber5k.com
See if any docker containers are stopped:
sudo docker container ls -a
Check the running log for Mistborn-base:
sudo journalctl -xfu Mistborn-base
Mistborn-base is a systemd process and at any time restarting it should get you to a working state:
sudo systemctl restart Mistborn-base
The WireGuard processes run independently of Mistborn and will still be up if Mistborn is down. You can check running WireGuard interfaces with:
sudo wg show
Note the Mistborn naming convention for WireGuard interfaces on the server is wg. So if the particular WireGuard process is listening on UDP port 56392 then the interface will be named wg56392 and the config will be in /etc/wireguard/wg56392.conf
The dev/
folder contains a script for completing a hard reset: destroying and rebuilding the system from the original backup:
sudo ./dev/rebuild.sh
Ensure that your public IP address in your client profile (e.g. Endpoint = <Mistborn public IP address>:<random port>
) is actually publicly available (not in 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16) if you are attempting to access Mistborn across the internet.
Each extra service has its own systemd process which can be monitored:
sudo journalctl -xfu Mistborn-homeassistant
sudo journalctl -xfu Mistborn-bitwarden
sudo journalctl -xfu Mistborn-syncthing
sudo journalctl -xfu Mistborn-jellyfin
sudo journalctl -xfu Mistborn-nextcloud
sudo journalctl -xfu Mistborn-jitsi
sudo journalctl -xfu Mistborn-guacamole
sudo journalctl -xfu Mistborn-rocketchat
sudo journalctl -xfu Mistborn-onlyoffice
sudo journalctl -xfu Mistborn-tor
sudo journalctl -xfu Mistborn-raspap
sudo journalctl -xfu Mistborn-wazuh
Instead of defaulting to a system DNS server, Docker will try to use a public DNS server (e.g. 8.8.8.8). If you're having issues pulling or building Docker containers with "failure to connect" errors, this is the likely problem. You can manually set the DNS server Docker should use with the DOCKER_OPTS
field in /etc/default/docker
. Example:
DOCKER_OPTS="--dns 192.168.50.1 --dns 1.1.1.1"
Be sure to restart Docker afterward:
sudo systemctl restart docker
New installations of 18.04 and 20.04 after 25 April 2020 don't seem to be having issues. If you installed Mistborn on Ubuntu 18.04 prior to 25 April 2020 and then upgrade to 20.04 you may have one minor issue described below.
Owing to changes in docker NAT rules and container DNS resolution, some WireGuard client configurations generated with Mistborn before 25 April 2020 (be sure to update Mistborn) may experience issues after upgrading to Ubuntu 20.04 LTS. Symptoms: can ping but can't resolve DNS.
Solution: Edit the WireGuard client config and set the DNS directive as follows:
DNS = 10.2.3.1
Close the config and restart the client WireGuard process.
Be sure to always reboot after updating the kernel. When the kernel is updated the kernel modules are deleted (for the currently running kernel) and you will have issues with any function requiring kernel modules (e.g. iptables
or wireguard
).
Note: The Raspberry Pi OS 64-bit BETA (versions from May 2020 and prior) have a bug where the os-release info indicates that it is Debian. Mistborn proceeds to install as though it were Debian. Since it's not Debian there are errors.
Run updates and restart before installing Mistborn (sudo apt-get update && sudo apt-get -y dist-upgrade && sudo shutdown -r now
). Some older Linux kernels will prevent newer WireGuard versions from installing.
The update (or update.sh underneath) process will automatically upgrade existing PostgreSQL 11 databases to PostgreSQL 16. This is accomplished by:
backups
If the initial dump fails then the automatic process will stop. When Mistborn starts up you will see errors indicating that the current Django and PostgreSQL tools cannot connect to PostgreSQL 11. If manual remediation is required these commands may be helpful:
cd /opt/mistborn
# create a backup
mistborn-cli dbbackup
# identify backup files available
mistborn-cli dbbackuplist
# build from backup
mistborn-cli dbupgrade --backup-filename backup_xxxxxx.sql.gz
These are some notes regarding the technical design and implementations of Mistborn. Feel free to contact me for additional details.
See the Mistborn Network Security wiki entry.
mistborn
user is only accepted from internal source IP addresses. Fail2ban is also installed.ip -o -4 route show to default
and ip -o -4 route get 1.1.1.1
.WireGuard runs over UDP. A shortcoming of WireGuard is that there is no simple option for using WireGuard over TCP, which is a slower protocol than UDP. However there are a few UDP ports that are often allowed through firewalls:
By default the WireGuard configs generated in Mistborn use a random UDP port. However, after version v2.3.0, that port can be changed to either 53 or 443 and the server will accept connections to those UDP ports.
Original (example)
[Peer]
PublicKey = pt/503ILuzQB4uPbdgdXJ7RoRO+FTff69Gn/vLC4my0=
PresharedKey = YuAY+0v5/dVeaIVElGdvd/R+nKQP4pa5sG4BwjiSClg=
AllowedIPs = 0.0.0.0/0,::/0
Endpoint = 167.71.xxx.xxx:53028
Change the Endpoint =
line to attempt to connect on UDP port 53:
[Peer]
PublicKey = pt/503ILuzQB4uPbdgdXJ7RoRO+FTff69Gn/vLC4my0=
PresharedKey = YuAY+0v5/dVeaIVElGdvd/R+nKQP4pa5sG4BwjiSClg=
AllowedIPs = 0.0.0.0/0,::/0
Endpoint = 167.71.xxx.xxx:53
Translations are planned for:
de
: Germanpt
: Portuguesefr
: Frenches
: SpanishIf you would like to assist with these or other languages, please reach out to me at [email protected]
If you are enjoying Mistborn please support the ongoing maintenance and testing effort
If you would like to resell Mistborn Enterprise (includes unlocking the professional features plus branding) send a proposal of terms to me at [email protected]