# Security

> Contextator's threat model — MCP access is token required by default and can be set to open or account required — and the operator checklist for locking it down.

- Updated: 2026-11-04
- Source: https://contextator.com/en/docs/security/
- Language: en-US
- Author: Muhammet Şafak

---
Contextator is built for a specific deployment: **a trusted team, on a private network or behind a
reverse proxy.** The dashboard has accounts and roles; the MCP endpoints have one door per project.
Read this page before exposing it anywhere else.

---

## The one thing to know

:::danger
A project's MCP endpoint **can be open**. If it is, anyone who can reach `/mcp/<project-name>` can
search and read every document indexed in that project — no account, no token.
:::

A new project is born **token required**: creating it mints a first token and shows the secret once, in
the creation dialog, so its endpoint is closed from the first second. A project created before that
became the default keeps whatever mode it already had — upgrading does not retroactively close or open
an existing project. Either way, the **MCP access** panel on the project page is where the mode is set,
and there are three of them: **open**, where the endpoint answers anyone; **token required**, after
which a client must send `Authorization: Bearer ctxm_…` or be answered `401`; or **account required**,
where the project's own memberships reach the endpoint through OAuth 2.1 and are checked on every
request. See
[Projects](/en/docs/projects/) for the switch and [Connecting AI Clients](/en/docs/connecting-ai-clients/) for
the client side.

**A token is a credential for the endpoint, not an account.** It carries no identity and no
per-document rules, so whoever holds it reads everything indexed in that project, and dashboard roles
do not reach `/mcp/*` through it. A role reaches `/mcp/*` only through a credential that names an account: it is
checked against that account's membership in every mode, and in `account` mode the connector signs in as a
person and the person's membership decides — see below.

So network position still decides most of it. An instance that leaves its projects open is readable by
anyone who can reach it, whatever the dashboard says about who may see what: keep the port private, or
put authentication in front of it.

The dashboard and the admin API are a separate door, and that one is always locked: they require a
personal account. `ADMIN_TOKEN` is not that lock — it is machine access to `/api/*` for scripts — and
neither of them protects `/mcp/*`. A project's own tokens, or in `account` mode a project member's sign-in, are what do. See
[Accounts and Permissions](/en/docs/accounts-and-permissions/).

## Operator checklist

1. **Give each person their own account**, and none to anyone who does not need one. The first is
   created at `/setup` with a one-time code; the rest come from **Users** in the top-right menu. A
   `member` account reaches only the projects you add it to — see
   [Accounts and Permissions](/en/docs/accounts-and-permissions/). On a plain-HTTP LAN address set
   `AUTH_COOKIE_SECURE=0`, or the browser drops the session cookie and nobody can sign in at all.
2. **Keep `ADMIN_TOKEN` out of browsers**, and unset it if nothing scripted needs the API. It acts with
   root permissions on every endpoint; treat it like a root password.
3. **Set `SECRET_KEY`** to 32+ random characters (`openssl rand -hex 32`) before adding a private git
   repository, a Notion integration or a Confluence connection. Store it somewhere other than your database backup.
4. **Close the projects that should not be public.** **MCP access** on the project page: **token
   required**, then **New token** once per client, or **account required** if the people who may read it
   already have accounts here. A project left open is readable by anyone who can reach its URL — see
   [Projects](/en/docs/projects/).
5. **Keep the port off the public internet**, or terminate authentication in a reverse proxy — including
   for the projects you deliberately leave open. The default (`CONTEXTATOR_BIND=127.0.0.1`) already
   publishes the port on this machine only; `0.0.0.0` is the one setting that changes that, and is the
   moment to put a reverse proxy or a VPN in front. See
   [Configuration](/en/docs/configuration/#server).
6. **Keep `ALLOWED_DOC_ROOTS` narrow.** It is the boundary that decides which directories can be indexed.
7. **Mount documentation read-only** (`:ro`), as the shipped compose file does.
8. **Scope source tokens tightly.** A git token needs read access to the documentation repositories, nothing more.
9. **Keep the `*_ALLOWED_HOSTS` lists narrow.** List only the exact internal hosts a source needs; every host listed is one the instance can reach from inside your network.
10. **Do not index secrets.** Everything indexed is readable by every agent that can reach the endpoint —
   and by every holder of that project's MCP tokens, which carry no per-document rules.

## What is protected, and how

| Area | Control |
|------|---------|
| Dashboard and API | A personal account, or `ADMIN_TOKEN` for scripts. Every rule — instance role, per-project membership — is decided server-side from one policy table, so a route is protected the moment it is registered and a button restored in the browser still answers `403`. `/api/health` is exempt, and says less to a caller it does not know. The last active `root` account can never be deleted, demoted or disabled, and an `admin` cannot touch a `root` account or hand out the `root` role — see [Accounts and permissions](/en/docs/accounts-and-permissions/) for the full role model |
| Passwords | Salted `scrypt` (`node:crypto`, N=2¹⁵), never logged, never returned, not reversible. An unknown username is refused with the same message, and after the same work, as a wrong password |
| Sign-in attempts | Rate limited per IP address, and per account with a lockout that doubles from `AUTH_LOGIN_WINDOW_MIN` up to an hour |
| Dashboard sessions | A row in the database, not a signed cookie: only a hash of the token is stored, and the cookie is `HttpOnly`, `SameSite=Lax` and `Secure` over HTTPS. Bounded by `AUTH_SESSION_IDLE_MS` and `AUTH_SESSION_TTL_DAYS`, and revocable — changing a password ends that account's other sessions, and disabling, deleting or resetting an account ends all of them |
| Requests that change something | A cookie-authenticated write must come from this site (`Sec-Fetch-Site`, falling back to `Origin`/`Referer`) or it is refused `403`. CORS is deliberately left without credentials, so `ALLOWED_ORIGINS` cannot be used to read the API as a signed-in user |
| Projects you cannot see | A project a member has no access to answers `404`, the same as one that does not exist, so project ids cannot be probed |
| Webhook endpoint | Each git source has its own secret; the provider's signature is verified against the raw body **before** anything is queued |
| Stored source tokens | Git, Notion (an integration token or the access and refresh token of an OAuth connection), Confluence and GitHub credentials, S3 key pairs and Google Drive service-account keys are encrypted with AES-256-GCM under `SECRET_KEY`; never returned by the API, never shown again. Since 0.6.0, an edit that moves the host of a source's address (a Confluence `baseUrl`, a git `url`, an S3 `endpoint`, a GitHub `apiBaseUrl`) while a credential is stored is refused unless the same request supplies the credential again, so an editor, who cannot read it, cannot redirect it to a host of their own; a Google Drive source has no such setting, because its hosts are pinned to Google's. A credential pasted into a repository URL (`https://user:token@host/…`) is not used and, since 0.3.1, is stripped before the URL is stored (migration `0020` cleaned up older rows); the token field is the only place a token is read from |
| Outbound requests | Web sources, git sources, Confluence, S3, GitHub, Google Drive and OAuth client metadata fetches go through an egress guard; web and git sources have been guarded since 0.3.1. It checks every redirect hop and refuses loopback, link-local (which covers the cloud metadata address), unspecified, multicast and reserved addresses outright, and private ranges (including carrier-grade NAT `100.64.0.0/10`) unless the host is listed; nothing is sent to a refused address, so no token reaches it. A host on an internal network is admitted by listing it in `WEB_ALLOWED_HOSTS`, `GIT_ALLOWED_HOSTS` or, for Confluence, S3 and GitHub Enterprise Server, `SOURCE_ALLOWED_HOSTS` (the older `CONFLUENCE_ALLOWED_HOSTS` was removed in 1.0.0; separate lists, lifting the private-range rule only; the client metadata fetch has no list). A git remote response is also capped by `GIT_MAX_PACK_BYTES` (0.3.2) |
| Filesystem access | Local source directories must resolve inside `ALLOWED_DOC_ROOTS`; `..`, a symlink that resolves outside them and non-directories are rejected, and a scan skips every symlink inside a source. Git subdirectories are resolved inside the checkout |
| Secrets and personal data in documents | Since 0.6.0 a scan looks through stored documents for AWS access keys, GitHub tokens, PEM private key headers, JWTs, Turkish citizen numbers and IBANs. It **only reports**: nothing is masked or skipped and search is unchanged. Findings show a masked preview, never the value, to a project `editor` and above, and nothing is on the MCP surface. See [Configuration](/en/docs/configuration/#scanning-documents-for-secrets-and-personal-numbers) |
| Limiting what one MCP token reads | A static `ctxm_…` token can be bound to some of a project's sources; a source outside the scope does not exist for it, and the filter is applied in SQL. On an `open` project a scope is not a boundary. See [Connecting AI Clients](/en/docs/connecting-ai-clients/#limiting-a-token-to-some-sources) |
| `read_document` | Serves only paths that were indexed for that project — never an arbitrary filesystem path — capped at `max_tokens` (200–20000, default 4000) |
| Uploads and archives | Extracted into a scratch directory first, then copied with traversal rejection, dot-directory removal, portable-name checks, an extension filter and entry/size caps against decompression bombs |
| MCP endpoints | Per project: **token required** (the default for a new project), **open** or **account required**. In `token` mode a request without a live `ctxm_…` bearer is answered `401` with `www-authenticate: Bearer realm="<project>"`; in `account` mode a static token names nobody and is refused, and the client signs in over OAuth 2.1 instead. A credential that names an account is checked against that account's membership on **every** request in **every** mode, `open` included, and a non-member is answered `403` |
| OAuth discovery and registration | `/.well-known/oauth-*` and `/oauth/*` are reachable with no credential **by design** — the two discovery documents exist to be fetched by a client that has none yet, and registering a client grants that client nothing on its own. Approving a client is a signed-in, same-site-checked browser action, same as any other write in the dashboard |
| MCP tokens | 256 bits of randomness, stored only as a sha256 hash — shown once when minted and never recoverable. Scoped to one project, revocable, and the list keeps only the name, the leading characters and a last-used time |
| Browser requests to `/mcp/*` | `Origin` validated in **every** mode (DNS-rebinding protection). Command-line clients send no `Origin` and are always allowed |
| Project isolation | Every query is scoped by project; a session issued for one project is rejected on another. Deleting a project, revoking one of its tokens, or closing it to **token required** or **account required** closes its open sessions at once, rather than at the client's next request |
| Database | The embedded PostgreSQL listens on `127.0.0.1` inside the container and is not published |
| Process | The application runs as an unprivileged user; the entrypoint is root only long enough to fix volume ownership |
| The `/about`, `/privacy`, `/cookies`, `/terms` and `/license` pages | **Deliberately open.** They are static, read nothing from the database and carry no secret: a legal notice only the operator can read is not a notice. The dashboard itself is not among them — an anonymous visitor to `/` is redirected to `/login` and is never sent the application at all |

## Putting authentication in front

Example with nginx Basic authentication, leaving the streaming transports intact:

```nginx
location / {
    auth_basic           "Contextator";
    auth_basic_user_file /etc/nginx/.htpasswd;

    proxy_pass         http://127.0.0.1:3444;
    proxy_http_version 1.1;
    proxy_set_header   Host $host;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_buffering    off;
    proxy_read_timeout 1h;
}

# the webhook endpoint must stay reachable by the git host
location /api/webhooks/ {
    auth_basic off;
    proxy_pass http://127.0.0.1:3444;
}
```

Note that most MCP clients cannot send Basic credentials, so a proxy like this serves the dashboard
more than it serves agents — and the dashboard already asks for an account, so a second prompt in
front of it buys little. For `/mcp/*` itself a project token is the better fit, because it is an
ordinary `Authorization` header that MCP clients do know how to set. Keep the proxy, or a mutual-TLS
or VPN boundary, for the projects you deliberately leave open.

Behind a terminating proxy, set `AUTH_COOKIE_SECURE=1` rather than relying on `X-Forwarded-Proto`, and set
`TRUST_PROXY` and `PUBLIC_BASE_URL` with it: left at their defaults, the per-IP sign-in limit becomes
instance-wide and MCP connectors cannot authorize. Set `TRUST_PROXY` to the proxy's own address, CIDR or
`loopback` — not to `1` or `true`, which trusted whoever wrote `X-Forwarded-For` and are refused at startup since 0.5.0, not to a hop count, which is refused too,
and not to the network your clients are on: a caller inside the trusted range can put any address into
the per-IP limits and the audit log. See
[Running behind a reverse proxy](/en/docs/configuration/#running-behind-a-reverse-proxy).

## Rotating things

| What | How |
|------|-----|
| Your own password | Account menu → **Change password**. It ends every other session of your account and leaves the one you are using |
| Someone else's password | Users page → **Reset password**. It hands out a temporary one, shown once, and signs that account out everywhere; they must replace it at their next sign-in |
| `ADMIN_TOKEN` | Change it in `.env` and restart. Update the scripts that carry it; dashboard sign-ins are unaffected, because they never used it |
| The setup code | Nothing to rotate. It stops working the moment the first account is created. While no account exists, a generated one is replaced on every restart |
| A git, Notion, Confluence or GitHub token, an S3 key pair or a Google Drive key | Edit the source and paste the new token; the old ciphertext is overwritten |
| A webhook secret | Git: **Regenerate** in the source dialog, then update the repository settings. Confluence: **New secret** in the source dialog, then paste it into the existing webhook under Confluence Administration → Webhooks. Notion: nothing to regenerate — Notion mints that secret, so open a fresh verification window in the source dialog and have Notion send its token again |
| An MCP token | Mint a new one, move the client onto it, then **Revoke** the old one. Revoking closes that project's live MCP sessions immediately |
| `SECRET_KEY` | A four-step rotation, not a single edit: set `SECRET_KEY_PREVIOUS` to the key you are retiring, set `SECRET_KEY` to the new one and restart, run `npm run rotate-secret` (`docker exec contextator npm run rotate-secret` for a Docker install) to re-encrypt stored tokens under the new key, then remove `SECRET_KEY_PREVIOUS` and restart once it reports nothing left under it. No stored token needs re-entering |
| `POSTGRES_PASSWORD` | Applied only at cluster creation; change it later with `ALTER USER` and update `.env` — see [Backup and Data](/en/docs/backup-and-data/) |

## Sensitive material: give it a project of its own

**Source permissions are not mirrored.** When Contextator indexes a Confluence space, a Notion workspace, a
git repository or a folder, it reads what its credential can read and keeps no record of who was allowed
to see which page at the source. A page restricted to three people in Confluence is, once indexed, a
document like any other in the project that holds it. Access is decided by the project, and by nothing
finer: whoever can open the project's MCP endpoint (anyone for `open`, a token holder for `token`, a
member or any administrator for `account`) reads every document in it, and a `viewer` reads every document in it in the
dashboard too. See [Projects](/en/docs/projects/#mcp-access) for what each mode does.

So material that not everyone with access to the rest of the documentation may read — HR policies, security
runbooks, customer contracts, anything with its own audience — belongs in **a project of its own**, with
its own sources, its own memberships and its own tokens. Projects are isolated from each other: each has its
own documents and embeddings, and a client connected to one never sees another. Do not point a source whose
pages have different audiences at one shared project and expect the audience to survive the indexing; it
does not. Use a source credential that can read only what the project's audience may read, and put
`account required` on the project so that its readers are its members, plus every `root` and `admin`
account of the instance and anyone holding `ADMIN_TOKEN`, which reach every project whatever its
memberships say. For a project like this, keep the number of those accounts small.

## Prompt injection: what is in place and the residual risk

Indexed text can contain instructions, and an agent that reads it may follow them. Contextator limits what it
can, and does not claim more than that:

- Every `search_docs` excerpt and every `read_document` body arrives between `<<<BEGIN DOCUMENT TEXT>>>` and
  `<<<END DOCUMENT TEXT>>>` markers. A document that contains a marker does not close the fence early:
  the fence is widened by one angle bracket at each end until the text cannot close it. The text itself is
  returned byte for byte, never rewritten.
- The server's instructions to the client say that what arrives between the markers is data and not
  instructions, and ask the agent to quote and cite it rather than act on it.
- Documents are chunked and returned as text. They are never rendered, evaluated or executed by this server.

**Residual risk.** The fence is a mark an agent can see, not a barrier it has to respect. Whether a model
treats fenced text as data is the model's behaviour, and nothing in this server can force it. An indexed
document that tells an agent to do something is still a document that tells an agent to do something, and
an agent with write or network tools connected next to Contextator can be steered by it. The text of a
`contextator://` resource is one whole document and carries no markers. The mitigation that works
regardless of the model is upstream: index only text whose authors you trust, keep the agent's other tools
to what it needs, and require a human to approve actions with side effects.

## Things Contextator does not defend against

- **Prompt injection through documentation.** If a document says *"ignore your instructions and…"*,
  the agent may read it. Contextator returns text faithfully; it does not sanitise intent. Treat your
  indexed corpus as trusted input. What is in place, and what is not, is under
  [Prompt injection](#prompt-injection-what-is-in-place-and-the-residual-risk).
- **Rate limiting.** Signing in is limited, per IP address and per account, and so is OAuth client
  registration (`/oauth/register`: 60 per hour per host, then `429`). Nothing else is: not the
  rest of `/api/*`, and not `/mcp/*`, where a token-protected project is no exception — a client
  holding a token can ask as often as it likes. The network boundary is the control.
- **Two-factor authentication.** There is none; a local account is a username and a password. Single
  sign-on is separate — an instance with an OIDC provider configured offers it alongside a password —
  and the record of who did what is the audit log at `#/~audit` in the dashboard, root and admin only,
  not just the server log.
- **Per-user or per-document rules on `/mcp/*`.** A project token is a credential for the whole
  endpoint, not an identity. It grants every document in the project, to whoever holds it, with no
  audit trail beyond *this token was last used at*; minting and revoking one is recorded, using it is not.
  A static token carries no dashboard role — a `viewer` membership grants nothing through it — and nothing
  narrows it to part of a project. Give each client its own token and revoke the ones you no longer
  recognise. A credential that names an account is the exception, in every mode: the person's membership
  decides, and in `account` mode the connector signs in as that person and the grant is recorded in the audit log.
- **Hiding which projects exist.** A token-protected project answers `401` where an unknown name
  answers `404`, so anyone who can reach the server can still learn a project name.

## Reporting a vulnerability

Do not report it in a public issue. There are two private channels, and the first is the one to use:

1. **GitHub private vulnerability reporting.** On the repository, open the Security tab and choose
   Report a vulnerability.
2. **Email**, if you cannot use GitHub or prefer e-mail: `security@contextator.com`.
