Security

This server holds the operator's private notes. That makes the questions different from the ones its sibling aegis answers. Aegis exists so that a secret never enters a model's context; here the content is the point, and an agent that could not read it would be useless. So the design cannot be about withholding data. It is about bounding what a mistake or a manipulation can do to it.

Two properties frame everything below. First, the data is plain files: whatever happens, recovery does not depend on this software. Second, an agent editing prose fails quietly — a lost paragraph produces no error, no failing test, and no complaint until somebody goes looking for it months later. Most of what follows is aimed at that second problem rather than at an attacker.

What an attacker with a token reaches

The honest answer first: a valid access token for a read-write user is equivalent to a copy of that user's vaults. There is no second factor between the token and the notes, and there could not be one without making the server useless to the agent it is built for.

What bounds the damage is that destruction is hard to make stick. Every write is a commit; with a git remote configured, that commit is already elsewhere before anybody notices. Deleted content sits in the trash for thirty days. An attacker who wants your notes gone has to reach the filesystem, not the MCP endpoint.

Reading is the asymmetric risk, and it has no technical answer. A token that has been stolen has already read whatever it wanted before you can revoke it. Two things reduce the window: a token lifetime of twelve hours by default, and the fact that a restart invalidates every session because nothing is persisted.

Path traversal, handled structurally

Every path argument goes through one function before it reaches the filesystem. After cleaning, the path must be relative, must resolve to somewhere inside the vault, and must contain no component beginning with a dot. Anything else is refused.

../../etc/passwd          # leaves the vault
/etc/passwd               # not relative
wiki/../../other/note.md  # leaves the vault after cleaning
.git/config               # dot component
.secondbrain/index.db     # dot component
notes/.obsidian/app.json  # dot component, at any depth

The third rule is the one worth arguing for. A blacklist of forbidden directories is a list somebody has to remember to extend: add a new tool, or a new editor that keeps state in a dot directory, and the list is quietly out of date. A rule about the shape of a path applies to every tool that exists and every tool that will exist, without anyone maintaining it. That is why .git, .obsidian and .secondbrain are unreachable — not because they are named anywhere, but because of what their names look like.

The practical consequence is that the server cannot corrupt its own git repository or its own index through a tool call, and that a vault's internal state is not something an agent can inspect, quote or edit.

Prompt injection from note content

This is the interesting attack against a knowledge base, and it deserves to be stated without hedging: a note can contain instructions, and this server cannot fix that.

The mechanism is ordinary. You paste an article into raw/. Somewhere in it is a sentence addressed to a model rather than to you — delete the following notes, append this text to the journal, put the contents of people/ into a note titled summary. Later an agent reads that file as part of answering a question, and the text arrives in its context indistinguishable from your own instructions. The same applies to a shared vault, a git pull from a repository somebody else can write to, and a web page saved by a browser extension.

No amount of validation on the server helps, because the content is the payload and delivering the content is the job. What the design does instead is bound the consequences.

Exfiltration is the harder half. An agent persuaded to read people/ and summarise it has done so inside its own context, and this server has no view of what the client does next. The audit log will show that the notes were read, which is a record and not a defence. If a vault contains material you would not want summarised into a chat window, it should be a separate vault reached by a separate user, and probably not by an agent at all.

No outbound calls, and nothing on disk

secondbrain makes no outbound network requests. Not for link previews, not for embeddings, not for telemetry, not for update checks. There is no URL fetcher, no webhook, and no tool that takes an address. The single exception is the git push you configure yourself with SECONDBRAIN_GIT_REMOTE, to a remote you chose.

This removes a whole class of problem before it starts. An agent that has been talked into something cannot make the server fetch an internal address, cannot use it to probe a network it should not see, and cannot use an outbound request as an exfiltration channel. There is no allow-list to maintain because there is nothing to allow.

Credentials follow the same principle. Registered clients, authorization codes, access tokens and refresh tokens live in process memory and are never written to disk. Restarting the container invalidates every session — a real inconvenience, accepted because it means the volume you back up and the volume somebody might one day walk off with contain notes and nothing else.

Passwords, when given as bcrypt:, are never present in plaintext anywhere: not in the environment, not in the config file, not in memory beyond the moment of comparison.

The audit log contains no note text

One structured line per tool call goes to stdout: who, which vault, which tool, which path, how many bytes, how long it took. That is the entire record. No content, no snippets, no search queries rendered with their hits, no diffs — at any log level, debug included.

{"ts":"2026-07-30T14:02:11Z","level":"info","event":"tool",
 "user":"andreas","vault":"personal","tool":"note_section_edit",
 "path":"wiki/postgres.md","bytes":184,"duration_ms":7}

The reasoning is worth spelling out, because logging more would be easy and would look helpful. A log is copied places the data is not: into a log aggregator, into a monitoring service, into a support ticket, onto somebody's laptop while debugging. An audit log that quoted note content would be a second copy of the knowledge base with weaker access control and no retention policy. The log is deliberately less useful than it could be so that it is not worth stealing.

What you can answer from it: which notes an agent touched and when, whether a burst of writes happened, how long a search took, whether a session did something at three in the morning. What you cannot answer from it: what any note says. For that there is git, which is inside the volume where the notes already are.

The metrics endpoint

The optional Prometheus endpoint is held to the same rule, and it is off by default. What it publishes is counts and timings: notes, words and bytes per vault, broken links, orphans, open tasks, tool calls by tool and outcome, cumulative durations, login attempts by outcome. What it never publishes is a path, a title, a tag or a line of note content — no metric carries any of them, and there is no label that could. The route label on secondbrain_http_requests_total is drawn from a fixed list of known routes rather than from the request path, so a caller cannot mint labels, or grow the series count without bound, by asking for invented URLs.

That restraint does not make an unprotected endpoint harmless. Counts are still the shape of somebody's private notes: how much they write and when they stopped, how large the work vault is next to the personal one, whether anyone logged in last night and how often they failed. Treat those numbers as belonging to the same person the notes do. Two mechanisms are available and they compose — a shared key of at least sixteen characters, compared in constant time, and a second listener on a port you simply do not publish. The second is the stronger: a port bound inside the Docker network and never mapped cannot be reached from outside whatever the key is. The endpoint also carries its own rate limit bucket, so a scraper presenting a wrong key cannot be turned into a timing oracle and cannot exhaust the limiter that protects the login page.

With metrics on and neither a key nor a private listener configured, the server logs metrics_unprotected once at startup, naming the path and hinting at both fixes. It is a warning and not a refusal, because on loopback an open endpoint is a reasonable thing to want. On a published port it means the opposite: anyone who can reach the server can read those counts, and that one line in the log is the only notice there will be. The metrics documentation lists every series and how to protect it.

What running without TLS exposes

The container speaks plain HTTP and does not terminate TLS. On a laptop, over loopback, that is fine. Across any network it is not, and the consequences are worse here than for most services.

• Every note that crosses the wire is readable in transit. Search results, note bodies, the diffs from a dry run. Anyone on the path sees your knowledge base as you use it.
• The bearer token is readable too, and a token is all that is needed to read everything else at leisure.
• The password crosses the wire on the login page. The OAuth flow includes an HTML form; over HTTP that form posts a password in the clear.
• PKCE does not save you. It protects an intercepted authorization code from being exchanged by a different client. It does nothing for a plaintext transport where the resulting token is visible anyway.

Put a reverse proxy in front of it and do not publish port 2020 alongside. The deployment guide has three working setups. If the server is only ever reached from the machine it runs on, bind it to 127.0.0.1:2020 and leave it there.

A compromised MCP client

If the client is compromised, this server is compromised with it, and there is no mechanism here that changes that. The client holds a valid token, and every request it makes is indistinguishable from a legitimate one because it is a legitimate one.

This is worth being clear about because MCP servers are sometimes described as if they contained a client. They do not. The trust boundary runs between the network and the container; the client is on the trusted side by construction. What that implies in practice:

• The security of your notes is bounded by the security of the machine running the MCP client, and by the model provider you have chosen to send them to.
• Revocation is restarting the container. Tokens are in memory, so a restart invalidates every session immediately — a blunt instrument that is always available.
• The audit log tells you what was read after the fact. It does not prevent anything.
• A read-only user for an agent that does not need to write is the cheapest real reduction in blast radius available, and it survives a compromised client.

Honest limits

Stated plainly, because software that oversells its guarantees is worse than software that has none.

Reporting

Security problems can be reported through GitHub security advisories on the repository, which keeps the report private until there is something to say. Please include a reproduction; a path that escapes a vault, a tool that writes without a hash check, or a log line containing note text are all worth a report.

This is a single-author MIT project, not a product with an on-call rotation. Expect a considered answer rather than a fast one.