Security review brief¶
The 1.0 exit criteria include a security review by someone outside the project. This page gives a reviewer what they need to start: what OunceMCP protects, where each control lives, how it is tested, and what has already been checked automatically. Findings go to the maintainer privately, as SECURITY.md describes.
What OunceMCP is¶
OunceMCP is a Python framework on FastMCP for building MCP servers, and it includes a client (Broker) that connects to many servers. Its security job is to keep an MCP server safe when:
- the model calling it is wrong or manipulated (prompt injection), or
- the network caller is hostile.
It does not authenticate users itself: FastMCP's auth providers verify tokens, and OunceMCP enforces what follows from the verified identity.
Assets and trust boundaries¶
| Asset | Threat |
|---|---|
| One tenant's data (catalog, caches, handles, jobs, cursors) | Read or changed by another tenant |
| Writes to upstream systems | Made without a person's approval, made twice, or made on the model's say-so alone |
| The caller's access token | Forwarded to an upstream service (token passthrough) |
| Internal network | Reached through a URL the model chose (SSRF, DNS rebinding, redirects) |
| Server internals | Leaked through error messages, traces or results |
A host using the Broker |
One server's output steering a write on another server |
Boundaries: model → server (arguments are untrusted), network client → server (HTTP, Host/Origin), server → upstream (outbound requests), server → server (through the broker).
Controls and where to look¶
| Control | Requirement | Code | Tests |
|---|---|---|---|
Identity only from the verified token; audience check |
SEC-1, SEC-4 | security/identity.py, core/server.py (audience=) |
tests/test_sec_security.py |
| One policy decides listing, search and calls; guessed names get the same answer | SEC-2, SEC-3, DISC-3 | security/policy.py, discovery/ |
tests/test_sec_security.py, tests/test_eval2_security_catalog.py |
Policies over stdio (stdio_policy) |
Proposal 0010 | security/stdio.py |
tests/test_sec_security.py |
| No token passthrough | SEC-4 | security/passthrough.py |
tests/test_sec_security.py, security catalog TokenPassthrough |
| Caches partitioned by caller | SEC-5 | security/cache.py |
tests/test_sec_security.py |
| Signed, caller-bound, expiring state (cursors, handles, approval receipts) | SEC-6, SEC-12 | security/state.py, core/ cursors |
tests/test_sec12_cursors.py, tests/test_res5_handles_jobs.py |
| No input request after an effect | SEC-7 | security/replay.py, ToolContext.require_input |
tests/test_sec_security.py |
HTTP: loopback by default, Host and Origin checks |
SEC-8 | security/http.py |
tests/test_sec_security.py |
| Safe outbound fetch: private, metadata and link-local addresses refused, connection pinned to the checked address, redirects re-checked | SEC-9 | security/urls.py, security/fetch.py |
tests/test_sec9_urls.py, tests/test_sec9_fetch.py |
| OAuth client registration order | SEC-10 | client/oauth.py |
tests/test_sec10_oauth.py |
| Trace redaction | SEC-11 | trace/ |
tests/test_sec_security.py |
| Approvals before writes; the model cannot approve | Gate 4 | execution/approval.py, core/server.py (_approval_gate) |
tests/test_sec_security.py, ticketing pilot tests |
| Idempotent writes; ambiguous writes are never retried | Gate 3, EXE-4 | execution/idempotency.py, execution/retry.py |
tests/test_exe4_idempotency.py |
| Error redaction | ERR-3 | core/errors.py |
error tests |
| Request limits (size, depth, concurrency) | EXE-6 | execution/limits.py |
limits tests |
| Cross-server writes need a person | CLI-6 | client/broker.py |
tests/test_client_broker.py |
Design records: proposals 0008 (security and policy), 0011, 0012, 0013, 0016, 0023 and 0025.
Already checked automatically¶
The pre-review results below, from 15 November 2026, are a starting point for the reviewer and not a substitute for the review.
- CodeQL (Python, JavaScript/TypeScript, Actions) runs on every pull request and push to
main, and its checks pass. Open alerts, if any, are listed under Security → Code scanning. - The security catalog (
ouncemcp.eval.run_security_suite) runs in the test suite against the ticketing and markitdown pilots and the Book's Shelf server. It probes guessed tool names, cross-tenant reads, cursor and handle reuse, SSRF targets and token passthrough. - Bandit (
bandit -r src -l) reports 1 medium and 14 low findings, and none is a vulnerability:- B104 (
security/urls.py):0.0.0.0is a placeholder address for a lookup that is skipped, not a server binding. - B101: each
assertnarrows a type. The one in the approval gate is behind anif spec.approval not in (None, "never")check at its only call site, so removing asserts with-Odoes not skip an approval. - B603, B607 and B404: the
subprocesscalls rungitwith fixed arguments and the server command the developer typed forouncemcp dev, never model input. - B105: the canary token that the security catalog plants on purpose.
- B311: retry jitter, not a security use.
- B104 (
- pip-audit over every locked dependency, all extras included, finds no known vulnerabilities.
- zizmor checks the GitHub Actions workflows on every pull request (the
workflowsCI job). Every action is pinned to a commit, checkouts do not keep the token, and the release workflow never restores a cache, so a poisoned cache cannot reach a published package. - Dependabot alerts and security updates are on. The report UI's dev-only
shadcnCLI carries a low-severitydeepmergeadvisory that has no patched release; it is not in the shipped bundle.
Internal audit, 16 November 2026¶
A full read of the security code, with attacks run against a live server, found one high-severity bug and several smaller ones. All are fixed and each has a regression test in tests/test_security_hardening.py. The details are in the audit report.
Known limits, stated in the docs¶
- Over stdio, policies are trusted by default (
stdio_policy="trust"), because the local user started the server.ouncemcp checkwarns about this, andstdio_policy="enforce"turns policies on. - Hiding a tool from a caller is not access control by itself; the same policy runs on every call.
safe_clientdefends against DNS rebinding by pinning the connection. Plaincheck_urlalone cannot, as the docs say.- The in-memory store is for one process. Several replicas must share Redis and the same
OUNCEMCP_CURSOR_KEYS.
What we ask the reviewer to look at first¶
- Tenant isolation end to end: catalog, search, caches, cursors, handles, jobs and approval receipts, for one tenant attacking another.
- The approval and idempotency paths under concurrency and retries, including a client that answers an approval for different arguments.
- SSRF defences in
security/urls.pyandsecurity/fetch.py: IPv6 and encoded forms, redirects, and proxies set in the environment. - Signed state: key handling and rotation, expiry, and binding in
security/state.py. - Broker cross-server rules against prompt injection carried in tool results.
Deliverable¶
A short report with each finding's severity, the affected code and a suggested fix. Findings go to GitHub private vulnerability reporting. Fixes ship in a patch release, and the reviewer and report are named in docs/m4-report.md when the review is complete.