The security model
A tool that watches a network gets close to everything on it: it holds logins to your routers and servers, and it runs a language model that reads text strangers wrote (a device's DHCP name, a failed login's user name, a log line). lanowl is built so that this closeness cannot turn into damage on its own. This page is how.
The model is not trusted
The owl is useful, and treated as if anything it reads could steer it.
- It can look; a change waits for you. Its own tools are read-only. An address that is not in your inventory is refused, whatever the model asks.
- An action's command is lanowl's. An action from the catalog is filled by the model with a device and a reason; lanowl builds the command from validated data: nmap runs without a shell, a service restart takes a unit from that device's allow-list, a Shelly reboot is one request to its own endpoint. The model's words are only ever shown.
- A command the owl writes runs only if it reads, or if you approve it. In your own questions, never in the audit or a log check, it can read a device lanowl has a login for: a fixed read picked by name, or a command of its own. Its own command runs at once only when it is on the device kind's read-only list (a print, a status, a log with a filter): one program in a known form, plain words that are quoted again before they are sent, so no shell syntax reaches the device. Anything else (a change, a pipe, a program not on the list) waits for your button, showing the exact command, and runs as written only if you approve it. What comes back is masked: passwords, keys, tokens and password hashes never reach the model.
- Every change waits for a person. A proposal is checked against the rules and the device itself before you see it, and again when you approve. Approval is a Telegram button from an allowed user, or the dashboard behind its login, after a sheet that says what runs.
- It never sees a password. Logins reach ssh through
SSH_ASKPASSand sudo through standard input, and command output is scrubbed of them. - Its shell is a sandbox. A separate container with no key, no config and no state of lanowl's, reaching the LAN only for handshakes and scans and never lanowl's dashboard. Its walls are proven from inside before the tool is offered, and every morning. The hourly audit's sandbox has no internet and no DNS at all.
- Its memory is written in your conversations only. Never by the audit or a log check, the runs that read strangers' text with nobody watching, and every note it saves is printed under its answer by lanowl itself.
- Detection does not depend on it. What is down, what pages and what is told are decided by code. A model that says nonsense can make a bad diagnosis; it cannot hide an outage.
Secrets
- One file,
secrets.yaml, mode 600.config.yamlandinventory.yamlhold none and can be shared. The config folder is mounted read-write, so lanowl can write its own files at a first start and the dashboard can set what is in them. - Secrets are write-only from the dashboard: a password or a token goes in, behind the login, and no page, answer, diff, log line or Telegram message carries one out. A save says which login changed, on Telegram too. The versions kept for undo are mode 600, in lanowl's state.
- A typed password crosses the network once, from the browser to lanowl: plain HTTP unless an HTTPS proxy sits in front of lanowl, as the dashboard password does.
lanowl --checkreports where each secret comes from, never its value, and refuses a file or a key that others can read.- The router is read with a user whose group can only read; lanowl reports any change to that group that grants more than you gave it on purpose.
The dashboard
The dashboard is closed until you log in, and it relies on these:
- One password, kept as a scrypt hash: in
config.yaml, or set with/passwordon Telegram, whose message is deleted. Without one the page asks for a one-time setup code that only lanowl's machine shows (lanowl --setup-code), then for the password: whoever sets it must reach the machine, not only the page. - A login is a random token in an HttpOnly cookie, of which lanowl keeps only a hash. It lasts 30 days after the last visit. A new password, or Log out everywhere, ends every one.
- Five wrong passwords (or setup codes) lock the login for 15 minutes and tell you on Telegram, with the address the last try came from. The lock survives a restart.
- It accepts only JSON for anything that does something, so another web page cannot submit a form to it (a cross-origin JSON request needs a permission it never grants).
- It answers only requests that reached it by IP address or by a name you listed, which defeats DNS rebinding.
- It cannot be framed by another site.
- Approving anything is a second step: a sheet that names what runs, where, and the risk.
- A save in Settings, from a logged-in browser, says what it changes first, keeps the file as
it was, and is announced on
Telegram (to the chat lanowl runs with, so moving the alerts elsewhere is still heard).
lanowl --check's rules run on the new file, and a new problem stops the save. Values the environment sets cannot be changed from the page. - Pausing a device is announced on Telegram, so nobody on the LAN can quietly stop lanowl watching the alarm.
Telegram
The bot answers only the chats you allow, ignores everyone else (logged, never answered), and acts on a button only when it comes from an allowed person in an allowed chat.
What is not protected
- Backups are not encrypted. They hold your network's passwords and keys. Keep the
store's path as private as
secrets.yaml. - The dashboard's password over plain HTTP. It crosses your LAN unencrypted when you log in. Put lanowl behind a reverse proxy with HTTPS if anyone you do not trust can watch your network's traffic.
- A host that is already compromised. If someone is root on lanowl's own machine, they have its secrets.
Edit this page on GitHub.