This guide puts Healthcare Threat Monitor on one computer inside your hospital network, watching your hospital’s own systems. It is free and stays on your own computer: nothing is sent to us or to anyone else.
You do not need to program, and you do not need to type commands. You need someone who can import a virtual machine or start a computer from a USB stick, and, for the patient records connection, someone who looks after your patient record system.
Download one file from the project’s GitHub page, under Releases, for the version you want. Each release lists a SHA256 checksum for every file, so you can check the download is complete and unchanged.
.ova file).ova file and accept the settings.-hyperv.zip file).vhdx disk. Move it to where your virtual machine disks are kept..vhdx file.-usb.img.xz file)The stick can be used again for other computers. The computer must allow starting from USB; if Secure Boot refuses the stick, see the computer’s firmware settings.
If you already run Docker on a Linux server and prefer it, see Installing with Docker at the end of this guide.
The first start takes a few minutes while the platform prepares itself. Then the installation’s own screen shows:
https://10.0.0.5On another computer, open that address in a web browser. Use the address exactly as shown: a name for the computer, such as one added to your hospital’s DNS, shows a blank page unless the HTTPS settings are changed to that name. The browser warns about the certificate the first time; choose Advanced, then Continue (the wording differs between browsers). See The certificate warning.
The page asks for the setup code, your name and your email. Then choose a password and connect an authenticator app such as Google Authenticator or Microsoft Authenticator. Every account needs both. The password must be at least 12 characters and must not contain the name part of your email.
The setup code works only until the first administrator is set up. After that, the page is closed and the screen stops showing the code. Anyone who can see the installation’s screen can see the code, so set up the administrator straight after installing.
If the screen warns that the address looks like VirtualBox’s private network, the virtual machine’s network is not Bridged: shut it down, change it as in 1A, and start it again. If the screen says the address changed, give the computer an address that does not change, as in A fixed network address; Windows computers set up before must be set up again.
The console is served over HTTPS with a certificate made by the installation, so browsers warn the first time. Two choices:
If you have your own certificate or a hospital domain name, the HTTPS settings are in docker/Caddyfile. See caddyserver.com/docs.
The screen shows the address and whether the platform is running, and refreshes by itself. You do not need to sign in to it for day to day use.
Nothing needs to be typed on it for day to day use. Two things can be done on it: pressing N sets a fixed network address (below), and for maintenance only, press Alt and F2 on the installation’s keyboard (in VirtualBox, Right Ctrl and F2, because VirtualBox catches Alt and F2) and sign in as htm. The first password is shown at the bottom of the screen from the very first start; type it without the space. It must be changed at first sign in, and the screen stops showing it once it has been. Keep the new password with your other administrator passwords.
The installation asks the network for its address (DHCP). If the network cannot keep the same address for it, set one on the installation’s own screen:
/24), the router’s address (the gateway) and the DNS servers.192.168.1.50/24, the router, such as 192.168.1.1, and the DNS servers separated by spaces (press Enter to use the router). Each is checked before anything changes: the router must be on the same network as the address.The new address takes effect straight away, and the platform starts again at it with a certificate made for it, which takes a minute or two. The screen then shows the new address and says it was set there. Windows computers set up at an earlier address must be set up again.
To go back to an address from the network, press N, then 2, then Y. Pressing N with nothing else changes nothing.
The first start loads the platform’s software in five parts, and the screen says which part it is on and how long it has been going. On a normal computer it takes 5 to 15 minutes. It is safe to switch the installation off at any point: on the next start it carries on from where it was, and a part that failed to load is tried again.
If it takes much longer, the computer is running it slowly. The screen says so after 25 minutes.
https://.192.168.56. address it shows.To send a log to whoever supports you: in VirtualBox, with the appliance switched off, open Settings, Serial Ports, Port 1, tick Enable Serial Port, choose Raw File, type a path such as C:\Users\Public\htm-log.txt, start the appliance, and send that file.
Sign in and open Setup in the console. Each step takes a spreadsheet (CSV, which Excel and Google Sheets can save) or a short form. Every step can be skipped and finished later.
| Step | What it is for |
|---|---|
| Hospital details | The name shown in the console and the time zone your records use. |
| Departments | So alerts can say which ward something happened in. |
| Staff | So an alert names a person and their role. Accepts columns such as staff_id, full_name, role, department_code. |
| Computers and devices | So an alert can say a machine is a nurses’ station, a server or an infusion pump. Types such as computer, PC or laptop are understood. |
| Patients | Optional. Mark patients who need extra protection, such as staff who are also patients or public figures. |
| Connect patient records | Opens the connection page, step 4 below. |
Each step has a template to download, and the wizard understands common column names, so an export from your HR or asset system often works without changes. If anything in a file is wrong, nothing from that file is imported, and every problem is listed with its row number so you can fix it and upload again.
The platform’s most valuable signal is who opened which patient record, and when. There are three ways to give it that.
The platform reads the access log table straight from your patient record system’s database, every 30 seconds. It only ever reads, and only the table you choose.
Supported: PostgreSQL, and MySQL or MariaDB. Microsoft SQL Server and Oracle are not supported yet; use FHIR or the report upload below.
Ask for a read only account. The connection page has a ready made request you can send to your vendor or database owner. They will need to create an account that can read the access log table and nothing else. For example:
PostgreSQL:
CREATE ROLE htm_reader LOGIN PASSWORD 'a long random password';
GRANT CONNECT ON DATABASE ehr TO htm_reader;
GRANT USAGE ON SCHEMA public TO htm_reader;
GRANT SELECT ON public.access_log TO htm_reader;
MySQL or MariaDB:
CREATE USER 'htm_reader'@'10.0.0.5' IDENTIFIED BY 'a long random password';
GRANT SELECT ON ehr.access_log TO 'htm_reader'@'10.0.0.5';
The table and database names are examples; your vendor knows the real ones.
The Sources page then shows, for each connection, whether it is working, when it last read, and how many entries it has read. If something goes wrong it says what, in a plain sentence, such as “The database refused the user name or password.”
Even if the account were allowed to write, the platform opens every session as read only, so the database refuses any change. The password is stored encrypted, and removing a connection deletes it.
Many record systems offer FHIR, the standard for sharing health data. Its AuditEvent records say who opened which patient record, and when. Under Sources, choose Connect a FHIR server and enter the FHIR base address the vendor gave you.
How the platform signs in depends on the vendor:
| Choice | When to use it |
|---|---|
| Key pair (SMART Backend Services) | What most record systems use for system to system access. The platform makes a key pair. You download its public key as a JWKS file and send it to the vendor to register with your client ID. The private key never leaves the installation. |
| Client ID and secret | The vendor gives you both. |
| An access token | The vendor gives you a fixed token. |
| No sign in | Test servers only. |
Leave the token address empty and the platform finds it in the server’s SMART configuration. If the server’s certificate comes from your hospital’s own certificate authority, paste that authority’s certificate into the connection, so the platform trusts it for this connection only.
Then press Check the connection. The platform signs in, checks the server offers AuditEvent, and shows a few recent records so you can see who, which patient and when look right. Choose where to start reading, and it reads new records every 30 seconds.
The platform only ever reads AuditEvent, and only from the address you entered: if the server points to another server for the next page of results, the platform refuses and says so.
If you cannot get database or FHIR access, export the audit or access report from your patient record system as a spreadsheet and upload it under Sources, Upload a report. You match the columns once; the platform remembers the matching for the next file with the same columns. Uploading the same report twice does not store anything twice. The file itself is deleted once it is imported.
Uploads are a good start, but they are only as current as the last upload. A database or FHIR connection watches continuously.
Most routers, firewalls and servers can send their logs to another computer, a setting usually called syslog or remote logging. Nothing is installed on them.
Only logs from accepted devices are kept, because anyone on the network can send syslog. Logs a device sent before you accepted it are not kept. If a device sends something the platform cannot read, the page shows its last such message, so you can see what it sends.
The platform reads connections that were blocked or allowed (FortiGate, pfSense and OPNsense, Cisco ASA, MikroTik, OpenWrt and other Linux based routers, Ubiquiti, Sophos and other key and value formats), VPN sign ins from FortiGate, and secure shell, sudo and scheduled job messages from Linux servers. It works out from the inventory whether an address is a server, a medical device or a ward computer, so the network rules apply, such as a scan of internal addresses or a medical device talking to the internet.
Docker must pass on each device’s own address. The standard Docker Engine on Linux does. Docker Desktop and rootless Docker do not, and the page warns you if every device seems to come from one address.
A small collector on each Windows computer sends its security events: sign ins and failed sign ins, accounts created and added to groups, special privileges, programs started with their command lines, scheduled tasks created, services stopped or installed, and the security log being cleared. It is a PowerShell script and a C# file that Windows compiles itself. Nothing else is installed.
On each computer, open PowerShell with Run as administrator in the folder with the installer and run:
powershell -ExecutionPolicy Bypass -File .\install_healthcare_threat_monitor_<group>.ps1
For many computers, your IT team can run the same file through Group Policy, Intune or any tool that runs a script as administrator.
The installer copies the collector to C:\ProgramData\HealthcareThreatMonitor, which only SYSTEM and administrators can open. It turns on the Windows auditing the platform reads, including the command line of new processes. Add -SkipAuditPolicy if Group Policy already sets auditing. It registers a scheduled task that runs every minute as SYSTEM, runs it once, and shows the result.
On the first run the collector sends the last day of events, then only what is new. If the network is down, nothing is lost: the next run sends it. Each computer trusts only this installation’s own certificate authority for this connection, and nothing is added to the computer’s list of trusted authorities.
Name computers in your inventory exactly as Windows names them, so alerts can say what each computer is for. The Windows computers page lists computers that are not in the inventory. To remove the collector from a computer, run C:\ProgramData\HealthcareThreatMonitor\uninstall.ps1 as administrator.
Every hospital is different. For the first 7 days after each kind of log starts arriving, the platform learns what is normal in your hospital: which addresses and domains are usual, and how much each person and computer normally does. During that time it reports clear signs of attack straight away, such as backups being deleted, a ransom note, a cleared security log, a port scan or a flagged patient’s record being opened. Activity that is only unusual is reported once learning ends.
Sources shows each kind of log’s learning, with Finish now to end it early and Learn again after a big change. The overview says when learning is under way. Change the length under Settings, Learning. Zero switches learning off.
If an intruder is already inside during the learning period, what they do may be learned as normal. Clear signs of attack are still reported, and you can Learn again once the hospital is clean.
This installation has no simulated hospital, no test attacks and no public demo login. The console requires everyone to sign in.
A backup holds everything: incidents, sources, settings, accounts, connections, the keys that unlock stored passwords and authenticators, and the installation’s certificate authority. Restored onto a new installation, every account, connection and Windows computer keeps working.
To make one, sign in as an administrator, open Settings, Backups, choose a passphrase and press Make the backup. Then press Download the backup and copy the file somewhere off the installation, such as a USB stick or the hospital’s file server.
The backup is locked with its passphrase (AES 256 GCM, with a key made from the passphrase by scrypt). Nobody can open it without the passphrase, and the passphrase is not kept anywhere, so keep it with your other administrator passwords. A finished backup waits on the installation for 24 hours to be downloaded, then is removed; change this with the backups.keep_hours setting. Every backup made, downloaded and restored is in the audit log.
To restore one, open Settings, Backups, Restore a backup, choose the file, type its passphrase and type RESTORE to confirm. Everything on the installation is replaced by the backup, everyone is signed out, and the installation starts again with the backup’s keys, which takes a minute. Then sign in with an account from the backup.
On a new installation nobody has set up yet, the first visit page offers Restore its backup instead, which asks for the setup code from the screen. This is how an installation moves to a new version or a new computer, below.
A backup made by a newer version cannot be restored onto an older one: update the installation first. A backup made by an older version is brought up to date as it is restored.
If the console cannot start, a backup can still be made with commands. These copy the database and the secrets only, not the certificate authority. On the appliance, sign in for maintenance (Alt and F2, user htm), go to /opt/htm and put sudo before each command; on Docker, run them in the repository folder.
docker compose exec -T db pg_dump -U htm -d htm --format=custom > htm-database.dump
docker compose run --rm --no-deps -T secrets tar -C /secrets -cf - . > htm-secrets.tar
Copy both files off the computer and delete them from it. To restore them onto a fresh installation, restore the secrets first, then the database. The first command removes everything the fresh installation made, so only use this on a new installation.
docker compose down --volumes
docker compose run --rm --no-deps -T secrets tar -C /secrets -xf - < htm-secrets.tar
docker compose up -d db
docker compose exec -T db pg_restore -U htm -d htm --clean --if-exists --no-owner < htm-database.dump
docker compose up -d
On Docker, put HTM_HOSTNAME=10.0.0.5 before the last command, as when installing.
To move an appliance to a new version:
RESTORE.Because the backup carries the certificate authority and the keys, Windows computers and browsers that trusted the old installation trust the new one, once it has the old address.
On a Docker installation, in the repository folder:
git pull
HTM_HOSTNAME=10.0.0.5 docker compose up -d --build
Your data, secrets, settings and connections are kept. Take a backup first.
docker compose down stops it and keeps the data. docker compose down --volumes removes everything, including all data and secrets, and cannot be undone.Each of these is tested end to end:
scripts/backup_smoke.sh, on every pull request): a backup made through the console and downloaded, refused from another site, without signing in and with a short passphrase; the whole installation removed and a new one started with new keys and a new certificate authority; a wrong setup code and a wrong passphrase refused with nothing changed; the restore from the new installation’s first visit page; and then the setting, the account, the keys and the certificate authority back, everyone signed out, the audit log verifying, the console and background service started again with the restored keys, and a computer that trusted the old certificate authority trusting the new installation with no warning.scripts/zap_scan.sh). It fails on any alert of medium risk or higher that is not accepted, with a reason proven on every run, in security/zap_accepted.tsv..ova for VirtualBox and VMware, .vhdx for Hyper-V. The USB installer starts any standard computer with BIOS, or with UEFI and Secure Boot on. Every release is built from the official images and tested before it is published, as a virtual machine and installed from a USB stick.Found something that does not work with your systems? Open an issue on GitHub, or report a security problem privately as SECURITY.md describes.
For hospitals that already run Docker with the Compose plugin on a Linux server. Download the code from the project’s GitHub page, then start it. Replace 10.0.0.5 with the address or name staff will type to reach this computer.
git clone <the repository address from the GitHub page>
cd <the folder it creates>
export COMPOSE_FILE=docker-compose.hospital.yml
HTM_HOSTNAME=10.0.0.5 docker compose up -d
docker compose logs setup
The first start builds everything and takes a few minutes. It makes its own secrets and keeps them in a private storage area on this computer. The last command prints the address to open and the setup code; continue at step 2. It also prints a one time link that skips the setup code, for the email in HTM_ADMIN_EMAIL (left out, admin@hospital.local).
Docker hides the addresses of devices sending logs on some setups, such as Docker Desktop. The receiver page warns when it sees this.