{"id":15136296,"url":"https://gitlab.com/cyber5k/mistborn","last_synced_at":"2025-05-15T12:07:03.856Z","repository":{"id":50507513,"uuid":"17334238","full_name":"cyber5k/mistborn","owner":"cyber5k","description":"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, +","archived":false,"fork":false,"pushed_at":null,"size":null,"stargazers_count":692,"open_issues_count":140,"forks_count":107,"subscribers_count":null,"default_branch":"master","last_synced_at":"2025-04-14T20:57:39.498Z","etag":null,"topics":["Syncthing","bitwarden","dnscrypt","home assistant","jellyfin","jitsi","multi-factor authentication","nextcloud","onlyoffice","pihole","raspberry pi","rocket.chat","siem","tor","wazuh","wireguard"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://gitlab.com/uploads/-/system/project/avatar/17334238/green_shield.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-06T19:06:31.425Z","updated_at":"2025-03-27T19:07:58.772Z","dependencies_parsed_at":"2022-08-20T06:10:52.895Z","dependency_job_id":null,"html_url":"https://gitlab.com/cyber5k/mistborn","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/cyber5k%2Fmistborn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/cyber5k%2Fmistborn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/cyber5k%2Fmistborn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/cyber5k%2Fmistborn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners/cyber5k","download_url":"https://gitlab.com/cyber5k/mistborn/-/archive/master/mistborn-master.zip","host":{"name":"gitlab.com","url":"https://gitlab.com","kind":"gitlab","repositories_count":4518952,"owners_count":6979,"icon_url":"https://github.com/gitlab.png","version":null,"created_at":"2022-05-30T11:31:42.605Z","updated_at":"2024-07-18T11:24:13.055Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners"}},"keywords":["Syncthing","bitwarden","dnscrypt","home assistant","jellyfin","jitsi","multi-factor authentication","nextcloud","onlyoffice","pihole","raspberry pi","rocket.chat","siem","tor","wazuh","wireguard"],"created_at":"2024-09-26T06:20:23.457Z","updated_at":"2025-05-15T12:06:58.839Z","avatar_url":"https://gitlab.com/uploads/-/system/project/avatar/17334238/green_shield.png","language":null,"funding_links":[],"categories":["Install from Source","Software"],"sub_categories":["Home Server","Self-hosting Solutions"],"readme":"# Mistborn\nA secure platform for easily standing up and managing your own cloud services: including firewall, ad-blocking, and multi-factor WireGuard VPN access\n\n![Mistborn WireGuard](https://gitlab.com/cyber5k/public/-/raw/master/graphics/home.mistborn_wireguard_.png)*WireGuard Management in Mistborn*\n\nAs featured in [Linux Magazine](https://www.linux-magazine.com/Issues/2020/240/Mistborn/(language)/eng-US) (Linux Pro Magazine in North America) in November 2020\n\n![Mistborn Featured in Linux Magazine](https://gitlab.com/cyber5k/public/-/raw/master/graphics/linux-magazine-cover-nov-2020.jpg \"Mistborn featured in Linux Magazine November 2020\")\n\n# Table of Contents\n[[_TOC_]]\n\n# What is Mistborn\nThe term [Mistborn](http://www.brandonsanderson.com/the-mistborn-saga-the-original-trilogy) is inspired by Brandon Sanderson's Cosmere.\n\nMistborn 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.\n\nAs a [Certified Information Systems Security Professional (CISSP)](https://www.credly.com/badges/ebcb76f2-1e82-4079-9ea3-b507ffbd1d15/public_url) and an [Offensive Security Certified Professional (OSCP)](https://www.credly.com/badges/b93c44ec-3af5-48e8-9a33-b64365b70c61/public_url), 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](#technical-and-security-insights).\n\nIdeal for teams who:\n- hate internet ads\n- need to be protected from malicious internet domains\n- need to collaborate securely\n- need multi-factor authentication for WireGuard\n- want to retain sole ownership of their data\n- want to easily grant and revoke access to people and devices via a simple web interface\n- want secure internet access wherever they are\n- want to limit or stop data collecting services\n- want to prevent being detected/blocked for using a proxy or VPN service\n\nSee the [Mistborn Network Security](https://gitlab.com/cyber5k/mistborn/-/wikis/Mistborn-Network-Security) wiki page to see the network scan results for Mistborn.\n\nMistborn depends on these core open source technologies:\n- [Docker](https://www.docker.com/why-docker): containerization\n- [WireGuard](https://www.wireguard.com): secure VPN access\n- [SSH](https://www.openssh.com): secure remote management\n\nThese tools are not vital to Mistborn itself but are integrated to enhance security, ease, and features:\n- [iptables](https://www.netfilter.org): The powerful Linux netfilter firewall tool\n- [cockpit](https://cockpit-project.org): A Graphical User Interface for system management, including container management\n- [Pi-hole](https://pi-hole.net): A DNS server for network-wide ad blocking, etc\n- [DNScrypt](https://www.dnscrypt.org): prevents DNS spoofing via cryptographic signatures to verify that responses originate from the chosen DNS resolver and haven't been tampered\n- [Traefik](https://docs.traefik.io): A modern, efficient reverse-proxy\n\nThese tools can be turned on from the Mistborn Security Operations Center:\n- [Wazuh](https://wazuh.com/): Wazuh is a free, open source and enterprise-ready security monitoring solution for threat detection, integrity monitoring, incident response and compliance.\n- [Suricata](https://suricata-ids.org/): Suricata is a free and open source, mature, fast and robust network threat detection engine. The Suricata engine is capable of real time intrusion detection (IDS), inline intrusion prevention (IPS), network security monitoring (NSM) and offline pcap processing. Suricata inspects the network traffic using a powerful and extensive rules and signature language, and has powerful Lua scripting support for detection of complex threats.\n\nWithin Mistborn is a panel to enable and manage these free extra services (off by default), locally hosted in Docker containers:\n- [Home Assistant](https://www.home-assistant.io): Open source home automation that puts local control and privacy first\n- [Nextcloud](https://nextcloud.com): Nextcloud offers the industry-leading, on-premises content collaboration platform. It combines the convenience and ease of use of consumer-grade solutions like Dropbox and Google Drive with the security, privacy and control business needs.\n- [Vaultwarden](https://github.com/dani-garcia/vaultwarden): Password manager. An unofficial Bitwarden server implementation written in Rust. It is compatible with the official Bitwarden clients, and is ideal for self-hosted deployments where running the official resource-heavy service is undesirable.\n- [Syncthing](https://syncthing.net): Syncthing is a continuous file synchronization program. It synchronizes files between two or more computers in real time, safely protected from prying eyes.\n- [OnlyOffice](https://www.onlyoffice.com): Cloud office suite. ONLYOFFICE provides you with the most secure way to create, edit and collaborate on business documents online.\n- [Rocket.Chat](https://rocket.chat): Free, Open Source, Enterprise Team Chat.\n- [Jellyfin](https://jellyfin.org): The Free Media Software System.\n- [Tor](https://www.torproject.org): The Onion Router. One tool in the arsenal of online security and privacy.\n- [Jitsi](https://jitsi.org): Multi-platform open-source video conferencing\n- [Guacamole](https://guacamole.apache.org): A clientless remote desktop gateway that supports standard protocols like VNC, RDP, and SSH.\n- [RaspAP](https://raspap.com/): The easiest, full-featured wireless router setup for Debian-based devices. Period. (Mistborn integration in alpha testing).\n\n# Quickstart\nTested Operating Systems (in order of thoroughness):\n- Debian 12 (Bookworm)\n  \nFormerly supported Operating Systems (your mileage may vary):\n- Ubuntu 20.04 LTS\n- Ubuntu 22.04 LTS\n- Debian 11 (Bullseye)\n- Raspberry Pi OS (formerly Raspbian) Buster\n- Ubuntu 18.04 LTS\n- Debian 10 (Buster)\n\n**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).\n\nTested Browsers:\n- Firefox\n\nThe default tests are run on DigitalOcean Droplets: 2GB RAM, 1 CPU, 50GB hard disk.\n\nThe Mistborn docker images exist for these architectures:\n\n| Mistborn Docker Images (hub.docker.com)        | Architectures       |\n|------------------------------------------------|---------------------|\n| mistborn (django, celery{worker,beat})         | amd64, arm64, arm/v7 |\n| dnscrypt-proxy                                 | amd64, arm64, arm/v7 |\n\nRecommended System Specifications:\n\n| Use Case               | Description                                                                   | RAM   | Hard Disk |\n|------------------------|-------------------------------------------------------------------------------|-------|-----------|\n| Bare bones             | WireGuard, Pihole (no Cockpit, no extra services)                             | 2 GB  | 15 GB     |\n| Default                | Bare bones + Cockpit                                                          | 2 GB+ | 15 GB     |\n| Low-resource services  | Default + Vaultwarden, Tor, Syncthing                                         | 4 GB  | 20 GB     |\n| High-resource services | Default + Jitsi, Nextcloud, Jellyfin, Rocket.Chat, Home Assistant, OnlyOffice | 6 GB+ | 25 GB+    |\n| SIEM                   | Default + Wazuh + Extras                                                      | 16 GB+ | 100 GB+   |\n\nOne line direct installation\n```\nwget -O install.sh https://gitlab.com/cyber5k/mistborn/-/raw/master/scripts/install.sh \u0026\u0026 sudo -E bash ./install.sh\n```\n\n**OR**\n\nClone repository and examine files first\n```\ngit clone https://gitlab.com/cyber5k/mistborn.git\n# Examine files if desired\nsudo -E bash ./mistborn/scripts/install.sh\n```\n\nGet default admin WireGuard profile\n*wait 1 minute after \"Mistborn Installed\" message*\n```\nsudo mistborn-cli getconf \n```\n\nConnect via WireGuard then visit `http://home.mistborn`\n\nFor more information, see the [Installation](#installation) section below.\n\n# Network Diagram\n![Mistborn Network Diagram](https://gitlab.com/cyber5k/public/-/raw/master/graphics/mistborn_network.png)\n\nMistborn protects your data in a variety of ways:\n- All of your devices are protected wherever they go with the WireGuard VPN protocol\n- The Mistborn firewall blocks unsolicited incoming internet packets\n- Pi-hole running on Mistborn blocks outgoing internet requests to configurable blocked domains (ads, malicious/phishing domains, etc.) \n\nSee the [Mistborn Network Security](https://gitlab.com/cyber5k/mistborn/-/wikis/Mistborn-Network-Security) wiki page to see more network diagrams and the network scan results for Mistborn.\n\n# Status\n![Mistborn Home](https://gitlab.com/cyber5k/public/-/raw/master/graphics/home_status.png)\n\nThe 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.\n\n# Security Information \u0026 Event Management (SIEM)\n\n![Mistborn Security Center](https://gitlab.com/cyber5k/public/-/raw/master/graphics/home.mistborn_soc.png)\n\nThe Mistborn Security Operations Center provides SIEM services with Wazuh. The Wazuh Manager requires an Open Distro for Elasticsearch backend. When the Mistborn host has \u003e8 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.\n\nMistborn's Wazuh installs and integrates with Suricata running on Mistborn with logs ingested into Wazuh.\n\n![Mistborn Security Center: Wazuh Modules](https://gitlab.com/cyber5k/public/-/raw/master/graphics/wazuh_modules.png)\n\nThe Wazuh Kibana plugin leverages the power of Elasticsearch:\n\n![Mistborn Security Center: Wazuh Dashboard](https://gitlab.com/cyber5k/public/-/raw/master/graphics/wazuh_se_dashboard.png)\n\n# Coppercloud\nPihole 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.\n\n![Mistborn Coppercloud IP Filtering](https://gitlab.com/cyber5k/public/-/raw/master/graphics/home.mistborn_coppercloud_.png)\n\nThis example shows Coppercloud blocking a list of Microsoft IP addresses on a network with Windows 10 clients.\n\n# Gateways [deprecated]\n\n**Gateways have been deprecated in Mistborn 2+**\n\n*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.\n\nFormer documentation:\n\nWe were getting frustrated at being forced to choose between being connected to our VPN and using streaming services that we have paid for.\n\n![Netflix blocked](https://gitlab.com/cyber5k/public/-/raw/master/graphics/netflix_blocked.png)\n\n*Netflix blocking my connections that it sees coming from a DigitalOcean droplet*\n\nIn 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).\n\n![Mistborn Gateway Diagram](https://gitlab.com/cyber5k/public/-/raw/master/graphics/gateway_network.png)\n\nThe Gateway adds an extra network hop. DNS is still resolved in Mistborn so pihole is still blocking ads.\n\n# Remote Desktop\nRemote 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).\n\nMistborn enables remote desktop access via the Apache Guacamole extra service, which supports VNC, RDP, SSH, and other protocols. \n\n![Guacamole Recent Connections](https://gitlab.com/cyber5k/public/-/raw/master/graphics/guacamole_connections.png)\n\nGuacamole 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.\n\n# Client to client communication\nBy 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.\n\n![System Settings](https://gitlab.com/cyber5k/public/-/raw/master/graphics/system_settings_dropdown.png)\n\n# Installation\nMistborn 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).\n\nClone the git repository and run the install script:\n```\ngit clone https://gitlab.com/cyber5k/mistborn.git\nsudo -E bash ./mistborn/scripts/install.sh\n```\n\nRunning `install.sh` will do the following:\n- create a `mistborn` system user\n- clone the mistborn repo to `/opt/mistborn`\n- setup iptables and ip6tables rules and chains\n- install iptables-persistent\n- install Docker\n- install OpenSSH\n- install WireGuard\n- install Cockpit (optional)\n- create a `cockpit` system user (if Cockpit is installed)\n- configure unattended-upgrades\n- generate a self-signed TLS certificate/key (WebRTC functionality requires TLS)\n- create and populate traefik.toml\n- create `/opt/mistborn_volumes` and setup folders for services that will be mounted within\n- backup original contents of `/opt/mistborn_volumes` in `/opt/mistborn_backup`\n- Pull docker images for base.yml\n- Build docker images for base.yml\n- Disable competing DNS services (systemd-resolved and dnsmasq)\n- copy Mistborn systemd service files to `/etc/systemd/system`\n- start and enable Mistborn-base\n\n# Non-Interactive Installation\nIn order to install without interaction some environment variables need to be pre-set. \n\n## Environment Variables\nSee the environment variables needed in `./scripts/noninteractive/.install_barebones`\n\n## Example Noninteractive Install\nThis will perform a noninteractive install with the default environment variables set in `.install_barebones`.\n```\ngit clone https://gitlab.com/cyber5k/mistborn.git\nsudo -E bash -c \"source ./mistborn/scripts/noninteractive/.install_barebones \u0026\u0026 ./mistborn/scripts/install.sh\"\n```\n\n# Post-Installation\nWhen 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:\n```\nsudo journalctl -xfu Mistborn-base\n```\n\nThe default WireGuard configuration file for `admin` may be obtained via:\n```\nsudo mistborn-cli getconf \n```\nPlease notice that the following lines are **NOT** part of the WireGuard config:\n```\nStarting mistborn_production_postgres ... done\nStarting mistborn_production_redis    ... done\nPostgreSQL is available\n```\n\nThe WireGuard config will look like this:\n```\n# \"10.15.91.2\" - WireGuard Client Profile\n[Interface]\nAddress = 10.15.91.2/32\n# The use of DNS below effectively expands to:\n#   PostUp = echo nameserver 10.15.91.1 | resolvconf -a tun.%i -m 0 -x\n#   PostDown = resolvconf -d tun.%i\n# If the use of resolvconf is not desirable, simply remove the DNS line\n# and use a variant of the PostUp/PostDown lines above.\n# The IP address of the DNS server that is available via the encrypted\n# WireGuard interface is 10.15.91.1.\nDNS = 10.15.91.1\nPrivateKey = cPPflVGsxVFw2/lMmhiFTXMmH345bGqoqArD/NgjiXU=\n\n[Peer]\nPublicKey = DfIV1urYZXqXKiU4rOSfO0Iu589pEO+59dHV5w5N0mU=\nPresharedKey = Z1SO5NuAnZ7JhzVCuUnYOQLWOQYmMoqG0pG1SNXUlh0=\nAllowedIPs = 0.0.0.0/0,::/0\nEndpoint = \u003cMistborn public IP address\u003e:39207\n```\n\n## Login via WireGuard\n[Install wireguard](https://www.wireguard.com/install/) on your computer. If you get a `resolvconf: command not found` error when starting WireGuard then install openresolv: `sudo apt-get install -y openresolv`\n- Copy the text of the default admin WireGuard config to `/etc/wireguard/wg_admin.conf` on your computer\n- Run `sudo systemctl start wg-quick@wg_admin`\n- Run `sudo systemctl enable wg-quick@wg_admin`\n- Open your browser and go to \"http://home.mistborn\"\n- Browse your Mistborn system!\n**Note:** The home.mistborn server takes a minute to come up after Mistborn is up (collectstatic on all that frontend JavaScript and CSS)\n\n## WireGuard Management\nMistborn 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.\n![Mistborn WireGuard](https://gitlab.com/cyber5k/public/-/raw/master/graphics/home.mistborn_wireguard_.png)*WireGuard Management in Mistborn*\n\n## Extra Services\nMistborn makes extra services available.\n![Mistborn Extra Services](https://gitlab.com/cyber5k/public/-/raw/master/graphics/home.mistborn_extra_.png)*Mistborn Extra Services Available*\n\n## Mistborn Firewall Metrics\nMistborn functions as a network firewall and provides metrics on blocked probes from the internet.\n![Mistborn Metrics](https://gitlab.com/cyber5k/public/-/raw/master/graphics/home.mistborn_metrics.png)*Mistborn Firewall Metrics*\n\n# Authentication\nThere are multiple ways to authenticate and use the system. \n\n![Mistborn Multi Factor Authentication - Authenticator App Setup](https://gitlab.com/cyber5k/public/-/raw/master/graphics/mfa_qr.png)*Mistborn Multi Factor Authentication - Authenticator App Setup*\n\n## Profile: WireGuard Authentication\nMistborn 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.\n\n## Profile: Multi Factor Authentication (MFA)\nIn 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](http://home.mistborn) to complete the authentication process.\n\n![Mistborn Multi Factor Authentication](https://gitlab.com/cyber5k/public/-/raw/master/graphics/mfa1.png)*Mistborn Multi Factor Authentication Prompt*\n\n### MFA Internet Access\nInternet access is blocked via iptables until authentication is completed for an MFA profile. You must go to [http://home.mistborn](http://home.mistborn) to complete the authentication process. Click \"Sign Out\" to re-block internet access until authentication completes again.\n\n![Mistborn Multi Factor Authentication - Token Prompt](https://gitlab.com/cyber5k/public/-/raw/master/graphics/mfa_token_enter.png)*Mistborn Multi Factor Authentication - Token Prompt*\n\n### MFA Mistborn Service Access - Fixed on 4 December 2020\nMistborn 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.\n\n![Mistborn Multi Factor Authentication - Not Authorized](https://gitlab.com/cyber5k/public/-/raw/master/graphics/mfa_not_authorized.png)*Mistborn Multi Factor Authentication - Not Authorized (Login Incomplete)*\n\n### Notes\n- **Sessions**: Traefik checks the authenticated sessions on the server side to determine whether to allow access to the Mistborn service web pages. If an open session exists for your Mistborn IP address then access will be granted. You may close all sessions by clicking \"Sign Out\" on the Mistborn home page. Expired sessions are regularly cleaned by the Mistborn system (celery periodic task).\n\n# Mistborn Subdomains\nMistborn uses the following domains (that can be reached by all WireGuard clients):\n\n| Service | Domain | Default Status |\n| ------- | ------ | -------------- |\n| **Home** | home.mistborn | On |\n| **Pihole** | pihole.mistborn | On |\n| **Cockpit** | cockpit.mistborn | On |\n| Nextcloud | nextcloud.mistborn | Off |\n| Rocket.Chat | chat.mistborn | Off |\n| Home Assistant | homeassistant.mistborn | Off |\n| Vaultwarden | bitwarden.mistborn | Off |\n| Jellyfin | jellyfin.mistborn | Off |\n| Syncthing | syncthing.mistborn | Off |\n| OnlyOffice | onlyoffice.mistborn | Off |\n| Jitsi | jitsi.mistborn | Off |\n| Guacamole | guac.mistborn | Off |\n| RaspAP | raspap.mistborn | Off |\n| Wazuh | wazuh.mistborn | Off |\n\n# Default Credentials\nThese are the default credentials to use in the services you choose to use:\n\n| Service | Username | Password |\n| ------- | -------- | -------- |\n| Pihole |  | {{default mistborn password}} |\n| Cockpit | cockpit | {{default mistborn password}} |\n| Wazuh | mistborn | {{default mistborn password}} |\n| Nextcloud | mistborn | {{default mistborn password}} |\n| Guacamole | mistborn | {{default mistborn password }} |\n| RaspAP | mistborn | {{default mistborn password}} |\n\nYou can find the credentials sent to the Docker containers in: `/opt/mistborn/.envs/.production/`\n\n# Gateway Setup\nMistborn 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:\n\n## Gateway Requirements\n- WireGuard (you can consult the Mistborn WireGuard installer: `mistborn/scripts/subinstallers/wireguard.sh`)\n- Openresolv (a WireGuard dependency that is also installed via the Mistborn WireGuard installer)\n- Fail2ban\n\n## Install Gateway WireGuard config file\nOn Mistborn:\n- Click `View Config` on the Gateways tab in Mistborn\n- Highlight the config\n- Copy (Ctrl-C)\n\nOn Gateway:\n- Paste the config to `/etc/wireguard/gateway.conf`\n- Run `sudo systemctl start wg-quick@gateway`\n- Run `sudo systemctl enable wg-quick@gateway`\n\n# Phones and Mobile Devices\nAll your devices can be connected to Mistborn as WireGuard clients.\n\nFirst steps:\n1. Device: Download the WireGuard app on your device. Links: [Android](https://play.google.com/store/apps/details?id=com.wireguard.android) [Apple](https://apps.apple.com/us/app/wireguard/id1441195209)\n1. Mistborn: Create a WireGuard profile for the device.\n1. Device: Scan WireGuard client QR code in WireGuard app.\n1. Device: Enable WireGuard connection.\n\nAll 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.\n\nBut wait, there's more! You can:\n- visit the [Mistborn web interface](http://home.mistborn) through your phone's browser. \n- download the apps for any extra services you have running and connect them to your Mistborn using the Mistborn domains.\n\n## App Links\n\n|                | Android                                                                                            | Apple                                                                              |\n|----------------|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|\n| Nextcloud      | [Nextcloud](https://play.google.com/store/apps/details?id=com.nextcloud.client)                    | [Nextcloud](https://apps.apple.com/us/app/nextcloud/id1125420102)                  |\n| Syncthing      | [Syncthing](https://play.google.com/store/apps/details?id=com.nutomic.syncthingandroid)            |                                                                                    |\n| Jitsi Meet     | [Jitsi Meet](https://play.google.com/store/apps/details?id=org.jitsi.meet)                         | [Jitsi Meet](https://apps.apple.com/us/app/jitsi-meet/id1165103905)                |\n| Bitwarden      | [Bitwarden](https://play.google.com/store/apps/details?id=com.x8bit.bitwarden)                     | [Bitwarden](https://apps.apple.com/us/app/bitwarden-password-manager/id1137397744) |\n| Jellyfin       | [Jellyfin](https://play.google.com/store/apps/details?id=org.jellyfin.mobile)                      | [Jellyfin](https://apps.apple.com/us/app/jellyfin-mobile/id1480192618)             |\n| Home Assistant | [Home Assistant](https://play.google.com/store/apps/details?id=io.homeassistant.companion.android) | [Home Assistant](https://apps.apple.com/us/app/home-assistant/id1099568401)                                                                                   |\n| Rocket.Chat    | [Rocket.Chat](https://play.google.com/store/apps/details?id=chat.rocket.android)                   | [Rocket.Chat](https://apps.apple.com/us/app/rocket-chat/id1148741252)              |\n\n## TLS Certificate\nSome 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.\n\nThe TLS certificate can be found here:\n```\n/opt/mistborn_volumes/base/tls/cert.crt\n```\n\n# FAQ\nFrequently Asked Questions\n\n## Where is my data?\n\nThe Docker services mount volumes located in:\n```\n/opt/mistborn_volumes\n```\n\nThe core Mistborn services have volumes mounted in `/opt/mistborn_volumes/base`. These should not be modified. The extra services' volumes are mounted in:\n```\n/opt/mistborn_volumes/extra\n```\n\nYour data from Nextcloud, Syncthing, Vaultwarden, etc. will be located there.\n\n## How do I SSH into Mistborn?\nIf 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.\n\nSSH is permitted from any device connected to Mistborn by WireGuard.\n\nPassword authentication in enabled. Fail2ban blocks IPs with excessive failed login attempts.\n\nYou can SSH using the Mistborn domain when connected by WireGuard:\n```\nssh user@home.mistborn\n```\n\n## How do I change the upstream DNSCrypt servers?\nThe upstream servers used by dnscrypt-proxy are set in:  \n\n`base.yml`:\n```\nservices:\n...\n  dnscrypt-proxy:\n  ...\n    environment:\n    ...\n      - DNSCRYPT_SERVER_NAMES=[...]\n```\n\nThe available options are here: https://download.dnscrypt.info/dnscrypt-resolvers/v2/public-resolvers.md\n\n## How do I purge an extra service/start fresh?\n\nThis 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:\n\n- Stop and disable the service\n\nThis can be done from the Mistborn GUI or:\n\n```\nsudo systemctl stop Mistborn-\u003cservice name\u003e\nsudo systemctl disable Mistborn-\u003cservice name\u003e\n```\n\n- Remove the data folder\n\nLocate the correct folder: `sudo ls -ahl /opt/mistborn_volumes/extra/`\n\n**Be careful:**\nNow remove the folder: `sudo rm -r /opt/mistborn_volumes/extra/\u003cservice name\u003e`\n\n- Remove the variables file\n\nLocate the file: `sudo ls -ahl /opt/mistborn/.envs/.production/`\n\n**Be careful:**\nNow remove the file: `sudo rm /opt/mistborn/.envs/.production/.\u003cservice name\u003e`\n\nNow you can restart the service from the GUI or manually and it should be a first run experience.\n\n# Troubleshooting\n\nOnce 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:\n\nCheck if you can ping an external IP address:\n```\nping 1.1.1.1\n```\n\nCheck if you can resolve local DNS queries:\n```\ndig home.mistborn\n```\n\nCheck if you can resolve external DNS queries:\n```\ndig cyber5k.com\n```\n\nSee if any docker containers are stopped:\n```\nsudo docker container ls -a\n```\n\nCheck the running log for Mistborn-base:\n```\nsudo journalctl -xfu Mistborn-base\n```\n\nMistborn-base is a systemd process and at any time restarting it should get you to a working state:\n```\nsudo systemctl restart Mistborn-base\n```\n\nThe WireGuard processes run independently of Mistborn and will still be up if Mistborn is down. You can check running WireGuard interfaces with:\n```\nsudo wg show\n```\nNote the Mistborn naming convention for WireGuard interfaces on the server is wg\u003clistening port\u003e. 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`\n\nThe `dev/` folder contains a script for completing a hard reset: destroying and rebuilding the system from the original backup:\n```\nsudo ./dev/rebuild.sh\n```\n\n## Troubleshooting WireGuard\nEnsure that your public IP address in your client profile (e.g. `Endpoint = \u003cMistborn public IP address\u003e:\u003crandom port\u003e`) 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.\n\n## Troubleshooting Extra Services\nEach extra service has its own systemd process which can be monitored:\n```\nsudo journalctl -xfu Mistborn-homeassistant\nsudo journalctl -xfu Mistborn-bitwarden\nsudo journalctl -xfu Mistborn-syncthing\nsudo journalctl -xfu Mistborn-jellyfin\nsudo journalctl -xfu Mistborn-nextcloud\nsudo journalctl -xfu Mistborn-jitsi\nsudo journalctl -xfu Mistborn-guacamole\nsudo journalctl -xfu Mistborn-rocketchat\nsudo journalctl -xfu Mistborn-onlyoffice\nsudo journalctl -xfu Mistborn-tor\nsudo journalctl -xfu Mistborn-raspap\nsudo journalctl -xfu Mistborn-wazuh\n```\n\n## Troubleshooting Docker\nInstead 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:\n```\nDOCKER_OPTS=\"--dns 192.168.50.1 --dns 1.1.1.1\"\n```\n\nBe sure to restart Docker afterward:\n```\nsudo systemctl restart docker\n```\n\n## Troubleshooting Upgrade from Ubuntu 18.04 to 20.04\nNew 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.\n\nOwing 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.\n\nSolution: Edit the WireGuard client config and set the DNS directive as follows:\n```\nDNS = 10.2.3.1\n```\nClose the config and restart the client WireGuard process.\n\n## Troubleshooting Raspberry Pi OS (Raspbian)\nBe 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`).\n\n**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.\n\n## Troubleshooting Debian 10\nRun updates and restart before installing Mistborn (`sudo apt-get update \u0026\u0026 sudo apt-get -y dist-upgrade \u0026\u0026 sudo shutdown -r now`). Some older Linux kernels will prevent newer WireGuard versions from installing.\n\n## Troubleshooting PostgreSQL 11 to 16\n\nThe update (or update.sh underneath) process will automatically upgrade existing PostgreSQL 11 databases to PostgreSQL 16. This is accomplished by:\n- Dumping the existing PostgreSQL 11 database to a compressed .sql.gz file in `backups`\n- Checking the major version of the dump file\n- If it's a version before 16 then the PostgreSQL data volume is dropped and PostgreSQL 16 recovers the backup\n\nIf 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:\n\n```\ncd /opt/mistborn\n\n# create a backup\nmistborn-cli dbbackup\n\n# identify backup files available\nmistborn-cli dbbackuplist\n\n# build from backup\nmistborn-cli dbupgrade --backup-filename backup_xxxxxx.sql.gz\n```\n\n# Technical and Security Insights\nThese are some notes regarding the technical design and implementations of Mistborn. Feel free to contact me for additional details.\n\n## Attack Surface\n\nSee the [Mistborn Network Security](https://gitlab.com/cyber5k/mistborn/-/wikis/Mistborn-Network-Security) wiki entry.\n\n- **WireGuard**: WireGuard is the only way in to Mistborn. When new WireGuard profiles are generated they are attached to a random UDP port. WireGuard does not respond to unauthenticated traffic. External probes on the active WireGuard listening ports are not logged and do not appear on the Metrics page.\n- **SSH**: If Mistborn is installed over SSH (most common) then an iptables rule is added allowing future SSH connections from the same source IP address. All other external SSH is blocked. Internal SSH (over the WireGuard tunnels) is allowed. Password authentication is allowed. The SSH key for the `mistborn` user is only accepted from internal source IP addresses. Fail2ban is also installed.\n- **Traefik**: Iptables closes web ports (TCP 80 and 443) from external access and additonally all web interfaces are behind the Traefik reverse-proxy. All web requests (e.g. home.mistborn) must be resolved by Mistborn DNS (Pihole/dnsmasq) and originate from a WireGuard tunnel.\n- **Docker**: When Docker exposes a port it creates a PREROUTING rule in the NAT table to catch eligible network requests. This means that even if your INPUT chain policy is DROP, your docker containers with exposed ports can receive and respond to traffic. Whenever Mistborn brings up a docker container with an exposed port it creates an iptables rule to block external traffic to that service. \n\n## Firewall\n- **IPtables**: Iptables rules and chains are manipulated directly. If UFW is present it is disabled. IPtables-persistent is used to save a simple set of secure default rules (most importantly setting the INPUT and FORWARD policies to DROP and allowing ESTABLISHED and RELATED traffic) that will be effective immediately upon system startup. Additional rules and chains are created by Docker on startup. Mistborn also creates some iptables chains during installation that are saved in the persistent rules. Mistborn iptables chains and rules are designed to work with Docker's with logic that is easy to follow. A power cycle will always result in a working state.\n- **PostUp/PostDown**: WireGuard configuration files on Mistborn include PostUp and PostDown directives that set routes and iptables rules for each WireGuard client individually.\n- **WireGuard**: There is a one-to-one mapping between each WireGuard client and server instance listening on Mistborn. By default WireGuard clients cannot talk directly to each other but can use shared services and resources on Mistborn (e.g. Syncthing, Nextcloud, Jitisi, etc). Toggling the \"client-to-client\" option will enable direct client-to-client communication.\n- **Metrics**: In addition to the iptables INPUT policy set to DROP, an iptables chain exists that logs the packet meta data before dropping it. Mistborn redirects packets that will be dropped to this chain instead. A summary of the data about these dropped packets (unsolicited network traffic) can be found on the Metrics page.\n- **Coppercloud**: Coppercloud works by populating ipsets with the ipset module in iptables to DROP (blacklist) or ACCEPT (whitelist) a given set of IP addresses. Upon system startup a celery task will compile the IP addresses, create the ipsets, and iptables rules.\n\n## Additonal Notes\n- Interface names are not hardcoded anywhere in Mistborn. Two commands that are used in different circumstances to determine the default network interface and the interface that would route a public IP address are: `ip -o -4 route show to default` and `ip -o -4 route get 1.1.1.1`.\n- The \"Update\" button will pull updated Docker images for mistborn, postgresql, redis, pihole, and dnscrypt. Those services will then be restarted.\n- The generated TLS certificate has an RSA modulus of 4096 bits, is signed with SHA-256, and is good for 397 days. The certificate is checked daily and will regenerate when expiration is within 30 days.\n- Outbound UDP on port 53 is blocked. All DNS requests should be handled by the dnscrypt_proxy service and if any client, service, etc. tries to circumvent that it is blocked.\n- Unattended upgrades are set to automatically install operating system security updates.\n- Ownership of mistborn files is set to the system mistborn user and access to environment variables is disabled for users other than the owner.\n\n# Firewall Penetration\n\nWireGuard 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:\n\n- **UDP/53**: The domain name system (DNS) protocol commonly uses this port and is essential to internet traffic\n- **UDP/443**: The QUIC protocol uses this port and is becoming more commonly used to make internet traffic more efficient\n\nBy 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. \n\n## UDP 53 example\n\nOriginal (example)\n\n```\n[Peer]\nPublicKey = pt/503ILuzQB4uPbdgdXJ7RoRO+FTff69Gn/vLC4my0=\nPresharedKey = YuAY+0v5/dVeaIVElGdvd/R+nKQP4pa5sG4BwjiSClg=\nAllowedIPs = 0.0.0.0/0,::/0\nEndpoint = 167.71.xxx.xxx:53028\n```\n\nChange the `Endpoint = ` line to attempt to connect on UDP port 53:\n\n```\n[Peer]\nPublicKey = pt/503ILuzQB4uPbdgdXJ7RoRO+FTff69Gn/vLC4my0=\nPresharedKey = YuAY+0v5/dVeaIVElGdvd/R+nKQP4pa5sG4BwjiSClg=\nAllowedIPs = 0.0.0.0/0,::/0\nEndpoint = 167.71.xxx.xxx:53\n```\n\n# Featured In\n\n- [Linux Magazine](https://www.linux-magazine.com/Issues/2020/240/Mistborn/(language)/eng-US) November 2020 (featuring Mistborn version from early May 2020)\n- [Awesome Open Source](https://www.youtube.com/watch?v=hekP0_crotw) July 2020\n- [DB Tech](https://www.youtube.com/watch?v=UE_OuAOgoZI) May 2021\n  \n# Languages\n\nTranslations are planned for:\n\n- `de`: German\n- `pt`: Portuguese\n- `fr`: French\n- `es`: Spanish\n\nIf you would like to assist with these or other languages, please reach out to me at [steven@cyber5k.com](mailto:steven@cyber5k.com)\n\n# Support Mistborn\n\nIf you are enjoying Mistborn please [support the ongoing maintenance and testing effort](https://buy.stripe.com/14k3fH4TBgxp1y05km)\n\n# Reselling Mistborn Enterprise\n\nIf you would like to resell Mistborn Enterprise (includes unlocking the professional features plus branding) send a proposal of terms to me at [steven@cyber5k.com](mailto:steven@cyber5k.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fcyber5k%2Fmistborn","html_url":"https://awesome.ecosyste.ms/projects/gitlab.com%2Fcyber5k%2Fmistborn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fcyber5k%2Fmistborn/lists"}