Hardening and threat model

Hardening and threat model

This page is the short version of Security, written for the person who has to say yes to running BxLens on a server. It says what the console can do, what it never does, what leaves the machine, and what you should still do yourself.

What BxLens is, security wise

BxLens shows the inside of a running application. That is its job, and it is also the risk. Someone who gets into the console sees SQL text, URLs, error messages, thread stacks, settings, and (on a full collect level) headers and the callers of queries. So the console is built like an admin tool: off by default, closed to everyone but allowed addresses, behind a password, and quiet about itself.

What the console can do

console.readOnly removes every change. console.actions: false removes the actions on the server. Both are in boxlang.json only.

There are no user names. The password decides the role, so two admins share one password, and the audit log names the role and the address, not the person.

What the console can never do

• Reach another site. The console and the bar load nothing from outside: scripts, styles, fonts and icons come from your own server. See what leaves the server for the few calls the server makes.
• Change who can reach it. The Settings page and Lensy cannot change console.*, access.*, bar.access, store.* or secrets.dir. The server refuses those keys.
• Show a secret. No route, answer, audit line, log line, bundle, prompt or Lensy tool returns a stored password, hash, key, API key, SMTP password or channel address. Pages show set, not set or the host.
• Run SQL. Lensy's database tools read JDBC metadata only. No tool takes SQL text.
• Stop or restart the server. There is no such tool or button. (An application can be restarted by name, with BoxLang+ and a typed confirmation, and not the one that serves the console.)
• Read arbitrary files. The Logs page reads the BoxLang logs directory only, and refuses names outside it and links that point outside.
• Act on another server. The pages of another server are read only, and the server refuses a change aimed at one.
• Keep bound query values unless you ask. Statement text is kept with literals masked. Bound values need collectors.queries.includeParams, and are never kept at collect.level light.

What leaves the server

BxLens makes no call for telemetry or for licensing. The license is checked inside the runtime through bx-plus. These are the only outgoing connections, and each one needs somebody to switch it on:

The buttons Ask ChatGPT and Ask Claude send nothing from the server: your browser opens the site and you paste.

How data and secrets are protected

• Redaction before storing. Values under keys such as password, token, secret, apikey, authorization, cookie and credential are masked on the server before they reach a page or a store. Add your own names to redact.keys. Query strings, URL credentials and -Dname=value pairs are masked too. See Redaction.
• Not redacted: the Logs page shows lines as written, exception messages are kept as the application produced them, and the Environment page hides by name only (a secret under a harmless name shows). Treat the console like the log files.
• Passwords set in the console are salted PBKDF2-HMAC-SHA256 hashes (310000 rounds), compared in constant time. Failed logins are counted per address (and per proxy connection), with a lockout. Sessions are in memory, with an idle and a 12 hour limit.
• The Secret Store seals the secrets BxLens keeps (the SMTP password, the AI key, channel addresses and tokens, password hashes) with AES-256-GCM. By default the key sits beside the data. That protects against a copied secrets.json and a backup that holds only the data. It does not protect against someone who has the whole folder or runs as the same user. Set LENS_SECRETS_KEY from your platform's secret store to keep the key off the volume.
• The store holds redacted data. See The store and Backup, retention and disk usage.
• The audit log records logins, denials and every change, with the role and address, never a password or key.

The threat model in one table

A hardening list

In order of value:

1. Put the console behind your VPN or an authenticating proxy. Then BxLens is the second lock, not the only one.
2. console.access to the VPN range. access.allowedHosts to your name. access.requireHeader if the proxy can add a secret header.
3. console.requireHttps: true, and access.proxyPeers to your proxy addresses only.
4. A long random admin password, kept out of files you commit (${env.NAME}, bxsecret: or set in Settings, Security). A viewer password for everyone who only looks. Change them when someone leaves.
5. console.sessionMinutes at 15 or less. console.readOnly: true and console.actions: false where nobody needs to act.
6. collect.level: "light". bar.enabled: false. Keep collectors.queries.includeParams off.
7. console.allowHeapDump: false. ai.enabled: false or a local provider.
8. LENS_SECRETS_KEY from your secret manager, and a note in your restore procedure about where the key is.
9. Permissions on store.dir, secrets.dir and the logs directory: the user that runs BoxLang, and your backup, and nobody else.
10. Read bxlens-audit.log or ship it. With BoxLang+ switch on the Security alert.
11. Upgrade. See Upgrading.

Known limits

• The Content-Security-Policy needs unsafe-eval (the Alpine.js build evaluates expressions) and unsafe-inline for styles. A move to the Alpine CSP build is planned.
• Shared passwords, no single sign on, no per person accounts, no second factor. Use your proxy for that.
• Sessions are in memory: a restart signs everyone out.
• Anything an application puts into a log line or an error message is shown as it was written.
• The check between a name lookup and the connection for channels and MCP servers is very short but not zero, see Channels.

To report a problem, see Troubleshooting.