Security overview#

A server that holds a household's or an office's files, and that may be reachable from the Internet, has to be safe without its owner becoming a security expert. This page explains how OSM is built for that, what it does by default, and where the limits are. Security in the guide covers the settings you control.

Safe by default#

A new OSM server:

• has no default password, and no account until you make the first Administrator. The installer and the first setup need a one-time code shown on the server's own screen, so nobody else on the network can take them over;
• answers only over HTTPS (plain HTTP is sent to HTTPS) with its own certificate, made at the first start;
• turns its firewall on: only the services and apps you run answer. While it is on, services meant for your network alone (the monitoring exporters, SNMP, the syslog server, the domain controller, a shared UPS) answer only to your local network;
• installs security updates by itself every day in its maintenance window, each with a restore point and a watch that undoes an update that breaks a service (critical ones at once), and never goes back to an older version;
• runs no app until you install one.

How OSM is built#

Two halves, one of them without privileges. The web desktop is served by a process that has no privileges and cannot change the system. Every change goes through a small root process, the agent, over a local socket. The agent accepts only a fixed list of operations, checks every argument of each one, and runs programs without a shell. A bug in the part that faces the network therefore does not give root.

The browser side. Sign-in cookies are HttpOnly and SameSite=Strict, and a session also needs a key that only the page's own scripts hold. Every change carries a CSRF token and must come from the server's own page (its Origin). The pages run under a strict Content Security Policy, cannot be framed by other sites, and the server answers only to IP addresses and to its own names, which stops DNS rebinding. With a trusted certificate, browsers are told to use HTTPS only (HSTS).

People's folders cannot lead root elsewhere. Backups and restores, cloud tasks, permission changes and the recycle bins work as root in folders that people and apps write. A symbolic link put there, before or during that work, never leads it out: those programs run where no link is followed at all, and the agent opens files one folder at a time without following one. A file of a shared folder that a virtual machine is given (an ISO, an installer image) must be a plain file with no link on its way: OSM checks it when it is chosen and again at every start.

Each app at an address of its own. An app's web page is served on a port (or a name) of its own, never on the web desktop's origin, so an app cannot read the desktop's sign-in. Apps run in containers, each with network rules of its own. The firewall's Never let in list and its countries apply to the ports apps publish, as to the server's own. An app's internal ports (Frigate's API, for one) are never published, and other apps and the server's accounts cannot reach them. Mosquitto, the App Catalog's MQTT broker, refuses connections without a password: OSM makes its login at install (user osm, shown on the app's page), and the app's settings can allow connections without one.

Apps from other catalogs are signed by their publisher. CasaOS app stores and compose files you import are not signed: OSM takes them only when you say so. Such an app that asks for more than a plain container (privileges, devices, the server's own network) is installed only once you have seen what it asks for and agreed.

Updates that cannot be swapped. Every update comes from OSM's update service, signed by OSM: a server checks OSM's signatures, checks Debian's own signature on every Debian package as well, and refuses anything older than what it installed, even when signed. OSM's installation images are signed, reproducible (the same sources give the same image, byte for byte), and come with a list of every package they hold (an SBOM) for vulnerability scanners.

Signing in#

• Two-step sign-in (an authenticator app's codes, with recovery codes) and passkeys or hardware security keys.
• Lockout: an address is paused for 15 minutes after 10 failed sign-ins, and wrong API tokens count too. Locking an account after repeated failures is off by default: turn it on in Settings > Security > Account (5 failures in a row then lock the account for 30 minutes, and you can change both).
• Sessions end after 30 minutes without use, and after 12 hours in any case (both can be changed).
• An expired password is changed at the sign-in only after the code of two-step sign-in, so the old password alone cannot choose a new one.
• Through OSM Connect (the desktop from anywhere, on servers that have it), the rules are stricter: only Administrators may sign in unless you allow more accounts, two-step sign-in or a passkey is asked every time (no browser is trusted), 20 failed sign-ins within an hour pause sign-ins through OSM Connect for an hour, a sign-in from a new browser or place is told to the Administrators and to the account, and changes such as deleting data, accounts, passwords or security settings ask for your code again ("Confirm it is you"). A sign-in at home and one through OSM Connect are separate: neither works at the other's address.
• API tokens for scripts: shown once, stored only as a hash, read-only if you choose, and named in the audit log. A locked or expired account's tokens stop working, and no token is given an operation whose answer is a password (API).
• A renamed account keeps its passkeys and API tokens: a new account given the old name starts with none.
• Saved passwords stay with their server. A password left empty in a setting (email, a remote folder, a cloud, a UPS, another OSM server's tokens...) keeps the saved one only while the setting points to the same server and account. Give it another server and it asks for the password again, so nobody who can change a setting can have its password sent to a server of theirs.
• Logs, source Administrator actions, records every change made in the web desktop, with an API token or with the osm command, and never writes a password or another secret. Settings > Security > Signed in lists every sign-in and ends any of them.

Encryption#

Finding problems before an attacker does#

• Security Check looks at the settings that matter most and fixes what it can with one click, on a schedule if you want, with a report by email.
• It also lists the known vulnerabilities (CVEs) of the installed software, from Debian's security tracker, and which ones an available update fixes.
• Antivirus (ClamAV) scans the shared folders you choose.
• Restore points before every update, automatic or not, with a 15-minute watch that goes back by itself if a service fails; nothing older than what OSM installed ever comes back.
• Backups that prove themselves.

Limits#

• Someone with the server in hand can give an Administrator a new password at its screen (key R), and start it in recovery mode, a root shell that asks for no password. That is by design, as on any computer, so that you can always get back in. Keep the server where strangers cannot reach it.
• Encrypting the system protects OSM, not your volumes. It keeps OSM, its settings and the kept passwords of encrypted shared folders from whoever takes the disks out of the server. Files on the volumes are protected only in encrypted shared folders. With the TPM, the server unlocks itself at every start, so a stolen server starts too, reset menu included, and its encrypted shared folders unlock by themselves if they use Unlock at start-up. If the whole server could be stolen, unlock the system with a passphrase typed at every start, or do not use Unlock at start-up.
• An Administrator can become root (with sudo, over SSH or in the Terminal app). Protect every Administrator account with two-step sign-in, and give people Standard accounts unless they need more. What an Administrator does in a shell is not in the audit log: the journal shows only the commands given to sudo.
• Apps are other people's software. OSM isolates them and tells you when a newer version is out (it installs it by itself only if you choose so, and a security fix while security updates install by themselves), but a flaw in an app is fixed by its publisher. Install the apps you need, and keep their network rules tight.
• Apps and virtual machines with an address of their own are separate devices on your network: neither the firewall nor network rules stand in front of them. Set their rules on your router.
• Exposing the web desktop to the Internet adds risk however well it is built. Prefer the VPN or remote access (Network).

Reporting a vulnerability#

Please report a vulnerability privately, as SECURITY.md explains. Every OSM server publishes the same contact at https://<server>:5001/.well-known/security.txt.