Security
Reporting Vulnerabilities
If you discover a security issue in ModusBrain, please report it privately by opening a private security advisory on GitHub. Do not open a public issue for security vulnerabilities.Remote MCP Security
⚠️ Do NOT use open OAuth client registration for remote MCP
If you deploy ModusBrain’s MCP server behind an HTTP wrapper with OAuth 2.1 support, never allow unauthenticated client registration. An attacker who discovers your server URL can:- Register a new OAuth client via
POST /register - Use
client_credentialsgrant to obtain a bearer token - Access all brain data via the MCP tools
Recommended: modusbrain serve --http
As of v0.22.7, ModusBrain ships a built-in HTTP transport that uses the
existing access_tokens table for authentication:
modusbrain auth create/list/revoke.
If you must use a custom HTTP wrapper
- Require a secret for client registration — check a header or body parameter before creating new OAuth clients
- Disable
client_credentialsgrant — only allowauthorization_codewith browser-based approval - Restrict scopes — never issue tokens with unlimited scope
- Log all token issuance — alert on unexpected registrations
- Rate-limit registration and token endpoints
Pre-registering claude.ai / ChatGPT clients without DCR (v0.41.3+)
The recommended hardening posture above is: shipmodusbrain serve --http
without --enable-dcr and pre-register every client manually. As of
v0.41.3, modusbrain auth register-client accepts the OAuth fields
browser-based clients need:
--token-endpoint-auth-method):
client_secret_post(default) — confidential client, secret in bodyclient_secret_basic— confidential client, secret inAuthorizationheadernone— public PKCE-only client (no secret minted; ChatGPT custom connector, Claude Code, Cursor)
POST /admin/api/register-client
and the DCR POST /register path. Pre-v0.41.3 the CLI hard-coded
redirect_uris = [] and token_endpoint_auth_method = NULL, forcing
operators to UPDATE oauth_clients rows by hand to make claude.ai work
without --enable-dcr. That footgun is gone.
DCR consent default (v0.42.55+)
The “disableclient_credentials, only allow authorization_code” guidance
above is now the built-in default for the DCR path, not just advice for custom
wrappers. With --enable-dcr on, a self-registered client defaults to the
authorization_code (browser-approval) grant, and an explicit
client_credentials request is rejected with invalid_client_metadata.
Operators who genuinely need the machine-to-machine grant on the registration
endpoint opt in with --enable-dcr-insecure (which implies --enable-dcr); a
startup WARNING prints whenever DCR is enabled, and a second when the insecure
grant is allowed. Pre-registering clients via the CLI / admin API is unchanged.
Token Management
access_tokens table. The
plaintext token is shown once at creation and never stored.
modusbrain serve --http hardening (v0.22.7+)
The built-in HTTP transport ships with several layers of hardening on by
default. All env vars below are optional; the defaults are intentionally
conservative.
Bind address (v0.34: loopback by default)
modusbrain serve --http listens on 127.0.0.1 by default. Personal-laptop
installs cannot accidentally publish the brain to the LAN. Self-hosted
deployments that need remote access pass --bind 0.0.0.0 (all
interfaces) or --bind <interface-ip> (specific NIC). A stderr WARN
fires when --public-url is set without --bind so the operator sees
the binding before the first request — common cause of “ngrok forwards
to me but the agent can’t reach the upstream” misconfigurations.
Postgres-only
modusbrain serve --http requires a Postgres engine. PGLite is local-only by
design and the access_tokens / mcp_request_log tables don’t exist in
the PGLite schema. Local agents continue to use stdio (modusbrain serve).
Running --http against a PGLite-backed install fails fast with a clear
error message at startup.
CORS
Default-deny: noAccess-Control-Allow-Origin header is sent unless an
allowlist is configured. To allow browser-based MCP clients:
Origin matches the allowlist, the server echoes it
back in Access-Control-Allow-Origin (with Vary: Origin). Otherwise no
CORS header is sent and the browser blocks the request.
v0.41.3: the same allowlist now gates every OAuth endpoint (/mcp,
/token, /authorize, /register, /revoke). Pre-v0.41.3 these used
default-wide-open cors() middleware, leaking
Access-Control-Allow-Origin: * on every response — any web origin could
complete a token exchange from a logged-in operator’s browser. The CORS
preflight handler in the legacy bearer transport was also asymmetric
(actual-request path correctly default-deny, but OPTIONS preflight leaked
Access-Control-Allow-Methods + Access-Control-Allow-Headers to every
Origin); both are now consolidated through a single allowlist-gated path.
A startup stderr WARN fires when --bind 0.0.0.0 is set without
MODUSBRAIN_HTTP_CORS_ORIGIN, surfacing the default-deny posture before the
first request.
Rate limiting
Two buckets, both stored in a bounded LRU map (default 10K keys, evicts least-recently-used on overflow, prunes entries older than 2× the window):
On exhaustion the server returns
429 Too Many Requests with a
Retry-After header.
Caveat for tunneled deployments (ngrok, Tailscale Funnel, Cloudflare
Tunnel): all requests share one egress IP, so the pre-auth IP bucket
becomes effectively shared by all clients on that tunnel. The
post-auth token-id bucket is the load-bearing limiter for tunnel-fronted
deployments.
Reverse-proxy trust
Loopback-only by default (v0.41.3+ Express server agrees with the legacy transport; pre-v0.41.3 the Express server hardcoded'loopback'
while docs claimed “disabled by default” — that disagreement is gone).
The default trusts only same-host proxies (127.0.0.1, ::1, fc00::/7);
external forwarded-for headers are ignored regardless. To widen or
narrow trust:
src/commands/serve-http.ts and
the legacy bearer transport in src/mcp/http-transport.ts) read the same
env var, so single source of truth.
Critical safety contract: only widen past 'loopback' when both
of these are true:
- modusbrain is reachable only via a trusted reverse proxy (not directly
exposed to the internet on the configured port). As of v0.34
modusbrain serve --httpbinds127.0.0.1by default, so the reverse-proxy-only posture is the out-of-the-box shape; only override with--bind 0.0.0.0(or a specific interface IP) when modusbrain itself needs to accept remote connections directly. - The proxy strips any client-supplied
X-Forwarded-ForandX-Real-IPheaders, then sets them itself. (nginx withproxy_set_header X-Forwarded-For $remote_addrdoes this; Cloudflare and most cloud load balancers handle it automatically.)
MODUSBRAIN_HTTP_TRUST_PROXY=1 (or any
non-loopback value) is set, clients can spoof their IP by sending
arbitrary X-Forwarded-For headers, defeating the pre-auth IP rate
limit. The 'loopback' default protects against this by ignoring all
forwarded-for headers and using the socket peer address.
Body size cap
Default 1 MiB, stream-counted (chunked transfers withoutContent-Length are still capped). Override:
413 Payload Too Large immediately, before any
body is materialized in memory.
Audit log
Every/mcp request writes one row to mcp_request_log:
status is one of: success, error, auth_failed, rate_limited,
body_too_large, parse_error, unknown_method. Failed-auth rows have
token_name = NULL. Inserts are fire-and-forget so audit failures
never block requests.
v0.26.9 redaction default. The params column now stores
{redacted, kind, declared_keys, unknown_key_count, approx_bytes} instead
of raw JSON-RPC payloads. Declared keys (intersected against the operation’s
spec) preserve for debug visibility; unknown keys are counted but never
named so attackers can’t probe key existence; byte sizes bucket to 1KB so
content sizes can’t be binary-searched. The same shape is broadcast on the
admin SSE feed at /admin/events. Operators on a personal laptop who want
raw payloads back can pass modusbrain serve --http --log-full-params (loud
stderr warning at startup). Multi-tenant deployments should leave it
on the redacted default.