Streamable HTTP transport and threat model
Status: local-first, serving MCP 2026-07-28 and the deprecated 2025-11-25. The existing stdio transport remains the recommended default.
The implementation exposes one /mcp endpoint through PHP's HTTP router and reuses the same ToolService and JSON-RPC dispatch as stdio. POST responses use application/json; server-sent event streams and server-initiated requests are not implemented. GET therefore returns 405.
Which revision a request belongs to is decided by its MCP-Protocol-Version header, and the two differ in ways that matter to this threat model:
2026-07-28has no sessions.Mcp-Session-Idis ignored rather than minted or echoed, and both GET and DELETE answer 405. The session-fixation and replay surface below does not exist for these clients.2025-11-25keeps sessions, server-minted, stored only as SHA-256 hashes in SQLite, expiring after 30 minutes, capped at 1,000, and closable with authenticated DELETE. This path is retained only for clients that have not migrated and is scheduled for removal once the specification's twelve-month deprecation window closes (no earlier than 2027-07).
2026-07-28 also requires each POST to mirror selected body fields into headers (MCP-Protocol-Version, Mcp-Method, and Mcp-Name for tools/call, resources/read, and prompts/get) and requires the server to reject any disagreement with 400 and JSON-RPC -32020. Knossos validates all three, decoding the =?base64?…?= sentinel before comparing. This closes a confused-deputy: an intermediary that routes or rate-limits on the header while the server acts on the body would otherwise apply policy to one tool while a different one executes.
A 2025-11-25 request inside a session mirrors only MCP-Protocol-Version. The session runs under the revision that header names, and a body whose _meta declares a different revision is refused with 400 and -32020 rather than silently winning.
On both revisions, and over stdio, a request id must be an integer or a string. A request whose id is anything else (null, a fraction, an array or an object) is answered with -32600 "Invalid Request" and id: null, over HTTP with status 400. Notifications carry no id and are not affected.
That mirroring is also a control for operators. A reverse proxy in front of Knossos can allow-list read-only tools by Mcp-Name, or deny scan_project, remove_project and move_project outright, without parsing request bodies. The server's own validation is what makes those header values trustworthy. Note the specification's caveat: an intermediary enforcing policy this way should first confirm that MCP-Protocol-Version names a revision that requires header/body validation, and reject the request otherwise, rather than trusting unvalidated headers from an older client.
The protocol requires Origin validation to mitigate DNS rebinding and advises local servers to bind only to loopback with authentication. See the official transport security requirements and HTTP authorization specification.
Threats and controls
| Threat | Control | Residual limitation |
|---|---|---|
| DNS rebinding / hostile browser | Exact Host and Origin allowlists on POST and DELETE; no wildcard or suffix matching. | Non-browser clients may omit Origin, so Host/auth remain mandatory controls. |
| Accidental network exposure | Documented/default bind is 127.0.0.1; default hosts/origins are loopback only. | PHP's router bind is operator-controlled; do not use 0.0.0.0 casually. |
| Unauthorized model/tool access | Optional constant-time pre-shared Bearer check on every request. Non-loopback deployment requires a token and TLS proxy policy. | This local profile is not an OAuth authorization server and exposes no OAuth discovery metadata. Use a conforming gateway for multi-user/Internet deployment. |
| CSRF | Origin rejection plus Authorization header; JSON content type only. | A compromised allowed client retains its granted tool authority. |
| Host/proxy confusion | Exact single Host value; comma-combined/forwarded host values are rejected. Proxy must rewrite Host to an explicitly configured value. | Forwarded headers are intentionally not trusted. |
| Session fixation/replay | Not applicable under 2026-07-28, which has no sessions. Under 2025-11-25, initialization rejects client-supplied session IDs; 256-bit random IDs are hashed at rest, expire, and are capacity-limited. | Bearer/session theft within the TTL enables replay on the legacy path; terminate TLS at a trusted local proxy. |
| Header/body confusion | 2026-07-28 requests must mirror MCP-Protocol-Version, Mcp-Method, and Mcp-Name into headers; each is validated against the body (Base64 sentinel decoded first) and any mismatch or omission returns 400 with -32020. | Legacy 2025-11-25 requests mirror no method or name, so header policy cannot apply to them; a contradicting body _meta version gets 400 -32020. |
| Request/response flood | 1 MiB request and response caps, strict JSON object framing, schema limits, scan/query/worker caps, no-store responses. | PHP/web-server limits should be set at least as strictly upstream. |
| Slow/idle clients | Web server handles socket timeouts; MCP sessions have fixed idle expiry. | PHP's development server is single-process and unsuitable for hostile production traffic. |
| Concurrent scans | Existing per-project SQLite writer leases serialize mutation while WAL readers keep the active snapshot available. | PHP development server itself serializes requests; use a controlled multi-worker proxy/runtime for concurrency. |
| Cancellation | Cancellation notifications receive 202 and do not corrupt state. Scan transactions remain atomic and worker timeouts apply. | The stateless PHP request profile cannot interrupt an already-running request; clients must rely on configured timeouts. |
| SSE/session stream abuse | SSE and GET streams are unsupported and return 405; sessions carry lifecycle only. | Clients requiring server notifications, resumability, or SSE must use another compliant deployment adapter. |
| Path/project-code attack | Existing allowed-root canonicalization, read-only mounts, no target execution, worker isolation, and stable diagnostics apply unchanged. | Git history may expose author emails in results to an already authorized client. |
Allowed roots bound what the server reads from disk as well as what it scans. file_context, change_impact, changed_files_impact, test_impact, review_diff and architecture_context with include_source refuse a project whose root lies outside them with KNOSSOS_UNSAFE_PATH. Tools that answer from the graph alone still answer for every project in the database, and the staleness attached to their results reports unverified for a project outside the roots rather than reading its files or running git in it.
Running locally
Native:
KNOSSOS_ALLOWED_ROOTS=/absolute/project \
KNOSSOS_HTTP_BEARER_TOKEN='replace-with-a-random-secret' \
php -S 127.0.0.1:8080 bin/http-router.phpDocker (source remains read-only and data remains separate):
docker run --rm -p 127.0.0.1:8080:8080 \
--entrypoint php \
-e KNOSSOS_ALLOWED_ROOTS=/workspace \
-e KNOSSOS_HTTP_BEARER_TOKEN='replace-with-a-random-secret' \
--mount type=bind,source=/absolute/project,target=/workspace,readonly \
--mount type=volume,source=knossos-data,target=/data \
knossos:dev -S 0.0.0.0:8080 /opt/knossos/bin/http-router.phpThe loopback-only published port limits exposure; Docker's bridge is required for host access to that port. For custom ports/hosts, set KNOSSOS_HTTP_ALLOWED_HOSTS and KNOSSOS_HTTP_ALLOWED_ORIGINS to exact comma-separated values. Never place the token in a URL. For non-loopback or multi-user access, put a TLS/OAuth-capable gateway in front, restrict the upstream network, and keep exact Host/Origin values rather than broad wildcards.
Web pane token
knossos web and the terminal pane serve one project's pane on 127.0.0.1. Their address carries a random token, and every request without it is refused. The token is what lets a request read the pane and act on the project. It is kept in the data directory, readable by you alone, and no probe or reconnect sends it to a port that has not proven it is this project's server.
A probe asks without the token, with a fresh random challenge. Probes run when a start finds the project's lock, when a server checks whether another took the lock over, when a server looks at the port of a holder it replaced, and when the terminal pane or a browser page is about to open an event stream. The project's server answers on its refusal with an HMAC of the challenge and the port, keyed with the token. Only a process that knows the token can make that answer, a fresh challenge cannot be answered from an old one, and the port in the answer stops a listener elsewhere from passing the challenge on to the real server and handing its answer back. The terminal pane and the page send the token in an event stream only after the answer holds, prove the server again before every new stream, and send their input only while a proven stream holds. A page that is told the pane moved to another port proves that port across origins before it goes there. Only a page on 127.0.0.1 or localhost may ask across origins.
Another user on the same machine can:
- connect to a pane server's port and be refused, as any request without the token is;
- listen on a port the pane used once its server is gone, and receive the probes: a challenge, never the token;
- see that a pane server listens on a port, from the marker header it sends;
- name their process in the lock's place only by a process id used again, and then a pane names that process, its port and the lock file instead of attaching to it.
They cannot get the token from a probe, a reconnect or a new start, and cannot pass a probe by sending the marker, by replaying an answer, or by relaying the challenge to the real server.
The known limits:
- The address you open or reload, and the files the page loads with it, go where the address points, with no proof first: the page's code comes from whoever answers there.
- A page that moves to a server that proved itself sends the token once more, in the address of that page load. After a takeover from a pane that was suspended or stuck, the server that took over listens on the old port with directions once that port is free. A reload of the old address then reaches it, and its redirect to its own address carries the token as the reload did. Either page proves its server before it opens its stream.
- A browser without WebCrypto cannot check the proof. It connects without it, as before the proof, and follows a move to another port unproven. Current browsers provide it on
127.0.0.1. - The proof is made on one connection and the token sent on the next. A server that ends in the milliseconds between, with another user's process binding its port in that moment, would receive the token. The same holds between the
/proc/net/tcpcheck below and the request after it.
Out of scope: anyone who can read or change traffic on loopback, which needs root on this machine.
A server from Knossos 0.49.1 or before cannot answer the challenge. A new pane or start still knows it (by the marker on its refusal, or by the refusal itself) without sending it the token, and uses it only when /proc/net/tcp shows its listening socket is yours, which another user cannot fake. Where the system cannot show that, the new pane does not attach to it. It names the process and port in the lock and the lock file, and says to stop the process if it is yours, or to remove the lock file if it is not.
Git subprocesses
Every query that reads a project's git state runs git inside the scanned project: changed_files_impact, test_impact, review_diff and change_impact, and also churn, branch and session diffs, file context, drift detection and doctor. All of them go through GitProcessRunner.
Git reads that repository's .git/config (and, for filters, its .gitattributes), either of which can name commands Git executes: core.fsmonitor during any index refresh, core.hooksPath for its hook scripts, diff.external during diff generation, and a .gitattributes-routed filter.<name>.clean/.process/.smudge or diff.<name>.textconv driver while git diff reads a changed path. The runner closes each of them.
- Fixed overrides.
core.fsmonitor=false,core.hooksPath=/dev/nonexistentanddiff.external=are passed as-coptions on every call. - Drivers, per repository. The runner first runs
git config --list --includes --name-only -z, which refreshes nothing and invokes no filter, so it runs with only the restricted environment below and not the-coverrides. For every filter and diff driver name it finds, it appends an override that blanks the driver. The query followsincludeandincludeIfdirectives and does not restrict itself to--local, so it also seesextensions.worktreeConfigsettings. Either can define a driver a narrower query would miss, whilegit diffitself still resolves them. required=false. Each filter also getsrequired=falseforced.required=trueis how Git-LFS's owngit lfs install --localmarks its filter, and how a hostile repository could otherwise turn a neutralised filter into a fatal error. Without this, a blanked but required filter fails the whole command instead of being skipped.- Fail closed. A driver name containing
=cannot be expressed as a-coverride, because Git's own parser splits on the first=, so the command is refused rather than run un-neutralised. A repository with more thanGitProcessRunner::MAX_DRIVER_NAMES(1,000) drivers is refused the same way, rather than building an argv long enough to makeproc_open()fail. - Pager.
core.pageris neutralised by--no-pagerat each call site, not by an override. - Environment. The child runs under an explicit environment:
GIT_CONFIG_NOSYSTEM=1,GIT_CONFIG_GLOBAL=/dev/null, andHOMEandGIT_ASKPASSpointed at a nonexistent path. The only value carried over from the parent isPATH, which Git needs to find its helper binaries, with/usr/bin:/binas the fallback.
A container's user is usually not the owner of the mounted project, and Git refuses a repository another user owns. Git reads safe.directory only from the system or global config, which the runner never reads, or from the command line. So the container wrapper sets KNOSSOS_GIT_SAFE_DIRECTORY to the absolute path of the project it mounted, and the runner passes it as -c safe.directory=.... A value that is not one absolute path, * included, adds nothing.
This matters whenever a repository directory arrives with its own .git/ rather than from a fresh clone: CI artifacts, extracted archives, container volumes, restored backups.