Security
What Modbot protects, how, and where the limits are, from passwords and sessions to stored secrets, API keys, webhooks, evidence and the companion.
This page says plainly what Modbot protects, how it does it, and what it does not protect against. If you are deciding whether Modbot is safe enough for your group, or you run a Modbot for one, this is the page to read.
Staff passwords
- Passwords are never stored. Modbot stores a hash: a one-way scramble made with PBKDF2 and a random salt per password, using ASP.NET Core's standard password hasher. A copy of the database does not reveal anybody's password. When the hasher's settings are strengthened in a newer version, a password's hash is upgraded the next time that person signs in.
- A password must be at least 12 characters.
- Changing your username or password needs your current password, so a browser left signed in cannot be used to take over the account.
- Signing in with a username that does not exist takes the same work as a wrong password, so timing does not reveal which usernames are real.
See Staff accounts for how people are added and how resets work.
Signing in
Slowdown, not lockout
Each failed sign-in makes the next attempt wait longer: 1 second, then 2, 4, 8, 16, and at most 20 seconds. Failures are counted per username and per address over 15 minutes, and the wait happens before the password is even checked.
There is no lockout. A correct password always works after the wait, so an attacker hammering the administrator's username cannot keep the administrator out; the worst they can do is make them wait 20 seconds. The sign-in page gives the same answer for a wrong password, an unknown username and a disabled account.
Every failed attempt is recorded in the operational log with the username tried and the address it came from, never the password.
Sessions and cookies
A session is a cookie named modbot.session. It is:
HttpOnly: scripts on the page cannot read it,Secure: browsers only send it over HTTPS, so run Modbot behind HTTPS,SameSite=Lax: other websites cannot make your browser send it along with their own requests.
How long it lasts depends on the Keep me signed in box on the sign-in page:
- Left unticked, the cookie is thrown away when the browser closes. While the browser stays open, using Modbot keeps the session going, and 14 days without using it ends it.
- Ticked, the session survives closing the browser, for 30 days from when you signed in. Those 30 days never stretch, however much you use Modbot.
The 30 days are counted on Modbot's own clock and checked on the server on every request, not written into the cookie, so nothing that arrives with the password can buy a longer session.
Every request checks the account before the cookie is trusted. That is what makes these take effect on the very next click:
- disabling an account ends all its sessions,
- using a reset link ends all the account's sessions,
- changing your own password ends all your other sessions,
- Sign out everywhere ends all your sessions, including the current one,
- a change to somebody's roles, or to a role they hold.
The keys that sign session cookies are kept in Modbot's database (the data_protection_keys table),
so restarting or updating Modbot does not sign anybody out. If you ever need to end every session
for every account at once, delete the rows in that table and restart Modbot. Normally you do not
need to: disabling an account or Sign out everywhere does the job for one account.
Those keys are stored unencrypted. Encrypting them would need another key, and the only place to keep it would be the same database. Anybody who can read that table can already read everything else Modbot holds, so it would not change what an attacker gets.
Every account is tied to a real VRChat account
Before an account can do anything other than finish the link and sign out, the person must prove they control a VRChat account by putting a code in its bio, which Modbot reads back through its own VRChat connection. One VRChat account can be linked to only one Modbot account. This is what lets Modbot say which person did something, not just which username. See Linking a VRChat account.
Invite and reset links
- Each link carries 32 random bytes. Modbot stores only a SHA-256 hash of it, so a copy of the database contains no working links.
- Invite links last 72 hours and reset links 24 hours. Both work once.
- A reset link that Modbot sends by email or Discord is built only from the Public address saved under Settings, Server. It is never built from the address a request came in on, or from forwarding headers. Anybody can ask for a reset link for somebody else's username; if Modbot built the link from that request, an attacker could make a genuine reset message point at their own server. Until a public address is saved, nothing is sent.
- The forgot-password page gives the same answer whether or not the username exists.
Permissions
Every request is checked on the server against the permissions of the person (or API key) making it. Hiding a page in the sidebar is only for tidiness. People can only hand out permissions they hold themselves, and at least one enabled administrator always remains. See Roles and permissions.
Secrets stored in the database
Modbot stores several secrets for you so it can do its job:
- your VRChat service account's password and two-factor (TOTP) secret,
- the VRChat sign-in cookies it keeps between logins,
- your proxy password, if you use a proxy,
- your Discord bot token and Discord sign-in (OAuth) client secret,
- your SMTP password,
- your AI provider's API key,
- your S3 bucket's secret access key, if evidence is stored in a bucket,
- each webhook's signing secret,
- the private key from your Google Calendar key file, if you gave Modbot one,
- your Bluesky app password, or the sign-in with Bluesky that replaces it, with the access and refresh tokens Modbot keeps for that account, and Modbot's own Bluesky signing keys (see Sign in with Bluesky).
- your Twitch app's client secret. It only asks Twitch for an app token, with no sign-in and no account behind it, and the secret is never shown again once saved.
These are encrypted with AES-256-GCM before they are written to the database.
The encryption key is created the first time Modbot starts and is stored in the same database,
in the protector_key table. There is no environment variable or file to keep it in.
What that protects against
One thing: somebody casually reading a copy of the database. If a backup, an export or a stray
pg_dump ends up somewhere it should not, the secret columns are unreadable rather than your VRChat
password in plain view.
What it does not protect against
Anyone who can read your whole database can decrypt your secrets, because the key is in that same database. This is the design, not a shortcut to be fixed later. It does not protect against:
- somebody who gets into your PostgreSQL server,
- your hosting provider, or anyone who works there,
- somebody who takes over the running Modbot server, which holds the key in memory,
- a Modbot administrator, who can change settings through the web app.
Why the key lives in the database
Modbot is run by community groups on hosted platforms, not by security teams with a key vault. The alternative, a key you must supply in an environment variable, would be worse in practice:
- On platforms like Railway, environment variables sit in the same project dashboard as the database password. Whoever can see one can see the other.
- A key you have to keep is a key people lose: a fresh redeploy, a project recreated after a billing problem, a handover to the next volunteer. Losing it would not just weaken Modbot; every stored secret would become unreadable for good, including the VRChat session your moderation depends on.
If you need real encryption at rest
Encrypt the database itself. Every managed PostgreSQL provider offers this, and disk encryption does the same job on your own server. Restrict who can reach the database. Modbot's own encryption is a second, weaker layer on top and was never meant to replace that. See PostgreSQL.
DATABASE_URL contains your database password, so treat it as carefully as the database. See
Environment variables.
The Google Calendar key
The Google Calendar key file is a key for a Google service account.
Modbot keeps the private key from it, encrypted like every secret above, and the service account's
address, the key's id and the project's id, which are not secret. The rest of the file is dropped.
The private key is never shown again and never leaves the server: Google gets only signatures made
with it. Modbot sends them only to oauth2.googleapis.com, whatever address the file names.
Whoever has the key can change every calendar shared with that service account. So it is as safe as your database, and no safer: anyone who can read your whole database can use it.
To remove it:
- In Modbot, Settings, Google Calendar, Forget. Modbot no longer has it.
- In Google Cloud, IAM & Admin, Service accounts, open the account, go to Keys and delete the key. It stops working everywhere, including any copy you or someone else kept.
- In Google Calendar, remove the service account's address from the calendar's Share with specific people or groups.
If you think the key leaked, do step 2 first: it is the one that makes every copy useless. Then make a new key and choose it in Modbot.
The Bluesky app password and sign-in
The Bluesky app password lets whoever has it post and delete posts as your group's Bluesky account. Modbot takes only an app password: anything not shaped like one (four groups of four letters or digits) is refused with "Use an app password.", so the account's main password, which can change its email and its password, is never stored.
Modbot keeps the app password and its sign-in (an access token that lasts about two hours and a
refresh token that renews it) encrypted like every secret above. Neither is ever shown again or
sent to the browser. They go only to the account's own server, the one the account's public record
names, and only over https:// to a public address. When Modbot renews the sign-in, the new tokens
are written to the database before they are used, because the old refresh token stops working.
Modbot keeps secrets out of its log, and the words token, password, jwt, dpop, verifier
and jwk in a log field's name are enough for it to be blanked, as is a Bearer or DPoP value.
To remove them:
- In Modbot, Settings, Bluesky, Remove. Modbot forgets the app password and its sign-in.
- In the Bluesky app, Settings, Privacy and security, App passwords, delete Modbot's. That ends the sign-in too, everywhere, including any copy someone else kept.
If you think it leaked, do step 2 first, then make a new app password and save it in Modbot.
Sign in with Bluesky: Modbot's signing key and the tokens
With a public https:// address, Modbot can sign in with Bluesky
instead of using an app password. Modbot never sees the account's password then. Three things are
kept, all encrypted like every secret above, never shown and never sent to the browser:
- Modbot's own signing key (an ES256 key), made the first time it is needed. Bluesky's sign-in
server reads its public half from Modbot's client document at
/oauth/bluesky/client-metadata.jsonon your public address; the private half never leaves your server. Modbot signs each request to Bluesky's sign-in server with it, so nobody else can renew Modbot's sign-in, even with its tokens. - The sign-in's tokens: a short access token and a refresh token, renewed as they run out. As with an app password, the new pair is written to the database before it is used.
- The sign-in's own key (DPoP). Every request with the tokens carries a proof signed with it, so a token copied off the server is no use without the key.
While a sign-in is under way, Modbot also keeps what it needs to finish it for ten minutes: the values it checks when Bluesky sends you back, and that key. Only the person who started the sign-in, still signed in to Modbot with Change settings, can finish it, and only for the account the handle names.
Modbot asks Bluesky only for what posting needs (making and deleting posts, setting who can reply to a post and whether it can be quoted, pinning one on the account's profile, changing the profile's name, bio, picture and banner, uploading pictures, and reading the account's replies, mentions and quotes). When Bluesky does not offer that, it asks for what an app password can do.
Remove forgets the sign-in, its tokens and its key. Modbot's own signing key stays: it belongs to your server, not to the account, and a later sign-in uses it again.
API keys
- A key is 32 random bytes with an
mbk_prefix. Modbot stores a SHA-256 hash of the key and its first 12 characters (so you can tell keys apart), never the whole key. It is shown once, when it is made. - A key can only be given permissions its maker holds, and it can never do more than its maker can do right now. If the maker loses a permission or is disabled, the key loses it too.
- A revoked or expired key, or a key whose maker is disabled, stops working on its next request.
See API keys.
Webhooks
- Every delivery is signed: the
Modbot-Signatureheader is an HMAC-SHA256 of the timestamp and the body, made with that webhook's own secret. Check it before trusting a delivery. See Webhooks and signatures. - The secret is encrypted in the database like the other secrets above, because Modbot has to read it back to sign each delivery.
- A webhook address must start with
https://and may not point at a private or local network address, unless somebody holding Change settings allows private addresses. - A webhook only sends events its owner is allowed to see.
Evidence
- Opening evidence needs View evidence, uploading or taking it off a case file needs Upload evidence, and destroying it needs Destroy evidence. They are three separate permissions on purpose.
- Attaching a file needs a case file that exists, has not been withdrawn, and that you wrote or may ban for.
- Evidence is downloaded as an attachment, with a content type Modbot works out from the file itself. When the file is sent through Modbot, it also carries headers that stop the browser guessing a different type or running anything inside it.
- Each file is stored under the SHA-256 hash of its contents. When a file is sent through Modbot, it is hashed again on the way out, and the download is cut off if the file no longer matches.
- When a bucket sends a file straight to the browser instead, the link it uses lasts five minutes.
- Destroying a file keeps a record of what it was, who destroyed it, when and why.
- Who attached, took off, viewed, downloaded or destroyed a file is written to the audit log, with the case file and the file's name. Downloads are written every time, but a request that says it is only showing the file is written as a look, at most once per person per file every 10 minutes, so somebody calling the API by hand can make a download read as a look. Reading these entries needs View evidence as well as See the audit log, and they are kept when a person is purged.
See Evidence and Storage buckets.
The companion
The companion pairs with your server through the pairing page. See Pairing.
- The pairing code is single-use and expires after 5 minutes, so a code left in a browser history, a screenshot or a stream is useless by the time anyone sees it.
- Pairing gives the client a long, random device token that nobody ever sees or types. The server stores only a SHA-256 hash of it and compares tokens in a way that does not leak how much of a guess was right.
- On the moderator's PC, the token is encrypted with Windows' own data protection for that Windows user, so copying the file to another machine or user account does not give a working token.
- A device token identifies a client, not a person. It can send what the client observes, read the context the overlay needs, and ask AI Chat a question as the person who paired it (Dictate does this), under that person's own permission to use AI Chat and their spending limit, and nothing else: it cannot ban, kick, read the member list or reach any other part of Modbot.
- A pairing code can only be made by a signed-in person, never by a device, so one compromised client cannot create more.
- The companion can record VRChat's window and VRChat's sound on that person's PC if they switch Clips on, and a device token reaches none of it. The evidence endpoints need a signed-in person holding the Upload evidence permission, which no device token has. The one file a device can send is the answer to a clip request the server sent to that device for a ban, kick or warning its moderator made, and only if the moderator ticked Send clips for my actions automatically: the server takes it once, within 15 minutes of the request, up to 100 MB, and refuses anything else. A stolen device token can answer a request the server already sent it, with a file. It cannot start a recording, cannot read one, cannot hear anything, cannot upload anything nobody asked for, cannot ask for a clip, and cannot attach one to a case of its own choosing. The sound in a clip is VRChat's own, with Discord's on a switch of its own that is off; nothing else the PC plays can be recorded by anybody, including whoever holds the token. If the moderator ticks Tell the group's Modbot when I save a clip, the token sends one more kind of event: that a clip was saved in the group's instance, with the file's SHA-256 and size. The server only takes it when it names the VRChat account linked to the person the device was paired to, and credits it to that person's Modbot account from the pairing, never from the event; a device whose owner has no VRChat account linked cannot report a clip at all. So a stolen device token can announce "clips" credited to that one moderator, in that group's instances, with any fingerprint — including the fingerprint of a file the thief holds. Those show on the case files of people who were in those instances, as clips saved on that moderator's PC. It cannot credit a clip to anybody else, upload anything unasked, or read any evidence: a file chosen in the browser is attached only by a signed-in person with Upload evidence who may change that case file, and only if its bytes match the fingerprint. A thief who also holds such an account could attach their own file and have it shown as that moderator's clip, which is why revoking a stolen token matters here as it does for presence, and why the audit log records both the device and the account that attached it.
- The companion can open that person's microphone if they switch Listening on, and a device token reaches none of that either. Nothing the microphone hears is recorded, kept or sent anywhere by anybody: the sound is checked against a short list of phrases and thrown away, the files allowed to open a microphone cannot write a file or reach the network, and the build fails if that changes. Dictate opens it too, on a tap, and only the words it writes out are sent, to AI Chat; the sound is not. A stolen device token cannot switch listening on, cannot hear anything, cannot learn that it is on, and cannot learn which microphones that PC has — the list behind the Microphone picker is asked for only while listening is on, is never sent anywhere, and no endpoint returns it.
What Modbot tells VRChat about you
Modbot talks to VRChat's API with your VRChat service account, through a single connection that follows VRChat's rate limits and never retries after VRChat says to slow down.
Every request carries a descriptive User-Agent, because VRChat asks for one and would rather contact an operator than block them. It contains:
- the name Modbot and its version,
- the email address of whoever runs this Modbot: the oldest enabled account holding Administrator that has an email address. The first administrator gives one during the setup wizard. Changing that account's email changes the address Modbot sends from then on.
Two more headers name the Modbot project itself (its contact email and
https://github.com/Modbot/Modbot), so VRChat can reach somebody who can explain the traffic even if
your address stops working.
If you set up a proxy for VRChat traffic in Settings, Modbot's VRChat login, Outgoing address, those requests go through it.
Logs
Modbot's logs contain VRChat user ids, display names and moderation actions: they are a record of
what your moderators did and to whom. If you send them to Seq with SEQ_URL, point it somewhere you
control. See Environment variables.
Reporting a security problem
Please do not open a public issue. Open a private security advisory on the repository at github.com/Modbot/Modbot. Modbot is run by volunteer groups who cannot patch on the same day a problem is made public.
Update world list PUT
Rename a world list or change its worlds and their players; a list cannot be left with no worlds. The Seen list cannot be changed. A world taken out is never picked again; a world added joins the current round of each event's shuffle. A world added must be one Modbot knows and VRChat has not refused; a world that is not is named in the 400. Worlds already on the list stay. Needs the `ManageCalendar` permission.
Privacy
Where Modbot's privacy policy lives, and what a self-hosted Modbot sends to Modbot Cloud and how to turn each part off.