Skip to content

Audit 2026-11-08: findings #16

Closed
Closed

Description

@SDNick484

Audit of main @ 3ccb5f1e1139abb708c113f6663e64eb953cb702 (43 commits, full history read), all 9 consumers full-cloned and compared byte-for-byte. Baseline: 252 tests pass, 98.9 % branch coverage, ruff/mypy clean. This follows the earlier P0–P3 remediation (#12, #13) and does not re-list what those fixed.

Consumer state at audit time: all 9 mcp-server-* repos consume shared; all copies are byte-identical to main. Six pin 73e65ec9; three (batocera, pixelcade, misterfpga) pin 769702a0 — see F1.

Severity: high = exploitable or data-leaking in the deployed setup; med = correctness/robustness bug reachable in practice; low = hardening, hygiene, docs.


Correctness & operations

F1 · med · Three consumers pin a commit that no longer exists on any branch — non-breaking

Evidence: batocera, pixelcade, misterfpga shared.lock → commit = "769702a01a28a175286a7e94ee5d264f635e8c3d". That SHA was the head of PR #14's mask-ip-url-helpers branch, squash-merged as 73e65ec9 and deleted. git cat-file -t 769702a in a fresh clone of this repo: not found. It resolves only because GitHub still serves the dangling object through raw.githubusercontent.com; a server-side GC breaks sync_shared.py --check in those three repos' CI with an opaque HTTP 404.
Why it happened: scripts/sync_shared.py only ever writes main's SHA (resolve_main), but never validates that the SHA it reads from a lock is reachable from main. A lock hand-edited (or synced from a branch checkout) is accepted silently.
Fix: in --check/--update, one GET /repos/{repo}/compare/main...{commit} call; warn (not fail) when status is ahead/diverged, with the squash-merge explanation and the fix (--update). Siblings: re-run --update (moves the lock to 3ccb5f1; no file changes).

F2 · low (corrected from med) · serve_http has no graceful-shutdown bound — non-breaking

Evidence: src/mcp_shared/remote.py:460-462 calls uvicorn.run(...) without timeout_graceful_shutdown, so uvicorn's default is to wait for every open connection before running lifespan shutdown. Every sibling's deploy/alpine/*.initd uses supervisor="supervise-daemon" with the default stop schedule SIGTERM/5 (man page); a SIGKILL after 5 s skips the siblings' lifespan teardown (device/MQTT disconnects).
Correction after measuring (2026-11-08): in the current stack (mcp 2.3, sse-starlette 3.7, uvicorn 0.54) this does not reproduce: the SDK's responses, including a tool call stuck on an unresponsive device, are SSE streams that sse-starlette closes ~1 s after it sees Server.should_exit, so lifespan shutdown ran in 1.1 s with or without the bound. The remaining risk is that sse-starlette finds uvicorn's exit flag by monkey-patch/introspection, which has broken before across versions (its own #132 and #211). So: defense in depth, not a live hang — severity lowered to low.
Fix: a fixed SHUTDOWN_TIMEOUT = 2 passed as timeout_graceful_shutdown (no new flag/env: the number only has to fit inside the supervisor's 5 s), uvicorn_settings(cfg) so a test runs the exact server configuration, and an end-to-end test that shuts down with a stuck tool call in flight and asserts lifespan shutdown runs inside the budget — a regression guard if the sse-starlette hook breaks. (Sibling-side, separately: siblings' stop_task(..., 5.0, …) timeouts equal the supervisor's whole budget; consider retry="SIGTERM/15" in the initd files.)

F3 · med · stop_tasks re-cancels every 250 ms, which interrupts a task's own finally: cleanup — non-breaking (behavior change)

Evidence: src/mcp_shared/tasks.py:92-94: every loop round calls task.cancel() on each pending task, then asyncio.wait(..., timeout=0.25). A task whose cleanup awaits anything >250 ms (MQTT DISCONNECT + close, a websocket close frame, await client.aclose()) gets a second CancelledError inside its finally. Reproduced: a worker with a 0.6 s awaited cleanup ends with cleanup_interrupted=True under stop_task(timeout=5).
History: the re-cancel exists for the Python 3.11 wait_for dropped-cancel bug (commit 4f4d397, CPython #28149, fixed in 3.12); sofabaton's mqtt.py:105 depends on it. The intent is sound; the period is the problem.
Fix: add grace: float = 1.0 to stop_task/stop_tasks/stop_background_tasks: cancel once, re-cancel only if still pending after grace, repeat. Keeps the 3.11 safety net, gives cleanups a full second. Tests that exercise the dropped-cancel path pass grace=0.25 explicitly; new test asserts a 0.6 s cleanup completes.

F4 · med · logsafe.redact_secrets misses several secret shapes that occur in this stack — non-breaking

Evidence (all verified against main; SECRET survives redact_secrets):

  • ?access_token=SECRET, ?refresh_token=, ?id_token=, ?client_secret=, ?sig=/?signature=, ?auth=, ?code= — _QUERY_SECRET (logsafe.py:61) only matches a bare token=/key= right after ?/&, so the OAuth names are not covered.
  • Authorization: Basic dXNlcjpwYXNz…, Authorization: Token … — only Bearer is handled (logsafe.py:67).
  • CF-Access-Client-Secret: <64 hex> (Cloudflare service tokens) and header/dict keys x-api-key, token, pairing_key, client_key, pin, psk in repr() of a headers dict — _JSON_SECRET key list (logsafe.py:62-64) lacks them.
  • Cookie: CF_Authorization=SECRET / Set-Cookie: CF_Authorization=… — Access's cookie name isn't covered when the value isn't JWT-shaped.
  • MQTT_PASSWORD=SECRET / *_SECRET= / *_TOKEN= env-style lines (e.g. a sibling logging its env at debug).
  • repr(HttpConfig)/repr(AccessPolicy) prints the full MCP_ALLOWED_EMAILS set.
    Property-based fuzzing (3 000 cases each) of redact() found no idempotence failures and no surviving non-loopback IPv4/IPv6 — the address rules are solid; the gaps are all in the secret-key vocabulary.
    Fix: extend the key vocabularies, add a generic Authorization: <scheme> <creds> rule, a header-line rule (Name: value for the sensitive names), a cookie rule for CF_Authorization, and an env-style NAME_(PASSWORD|SECRET|TOKEN)= rule; add property tests under pytest.importorskip("hypothesis") so siblings without hypothesis still pass; AccessPolicy.emails gets field(repr=False).

F5 · low · mask_ip leaks an IPv4-mapped address; mask_url raises on a bad port — non-breaking

Evidence: mask_ip("::ffff:192.168.1.5") → "x:x::192.168.1.5" (logsafe.py:130-131 takes the text after the last :; for mapped/embedded-v4 forms that is the whole IPv4). mask_url("http://192.168.1.5:abc/") raises ValueError from parsed.port (logsafe.py:172) — a helper meant for log paths must not raise. Found by property tests.
Fix: use ipaddress to detect ipv4_mapped/embedded v4 and mask that tail; wrap parsed.port and fall back to the raw netloc port text.

F6 · low · remote.py denial log and /healthz details

Evidence: remote.py:281 logs the rejected identity's e-mail verbatim ("{email} is not in MCP_ALLOWED_EMAILS"); logsafe has no e-mail rule, so a pasted log carries third-party PII. AccessVerifier holds anyio.Lock across the blocking JWKS fetch (:241-258), serialising all verifications for up to timeout=10 s during a refetch — acceptable but worth a comment. last_fetch is updated on every resolve, not only on network fetches (:257-258), so the variable name over-promises (behaviour is fine: it rate-limits unknown-kid probes).
Fix: mask the local part (u***@example.com) in the denial message (part of F4 PR); comment the two subtleties. Non-breaking.

scripts/sync_shared.py

F7 · med · Writes are not atomic — non-breaking

Evidence: write_files (:355) does path.write_bytes(...) in place; --update writes the lock with write_text (:530). A crash/SIGINT mid-write leaves a truncated module in src/<pkg>/, and nothing flags it until --check. The docstring's "a network failure halfway leaves the repo as it was" is true only for fetch failures.
Fix: write to <target>.tmp-<pid> in the same directory, os.replace(); same for the lock.

F8 · med · --update silently overwrites uncommitted hand-edits to synced copies — breaking (CLI behaviour)

Evidence: run() (:523-535) fetches and writes with no look at the working tree. A developer who edited src/<pkg>/remote.py locally (against the rule, but to debug) and then runs --update loses the edit with no message; git diff afterwards shows only upstream's change. sync_all_siblings.py update makes this fleet-wide.
Fix: when the sibling is a git repo, refuse to overwrite a target that git status --porcelain -- <target> reports modified, naming the files and suggesting git stash/git diff; --force overrides. Draft PR, labelled breaking: scripts that relied on silent overwrite need --force.

F9 · low · Lock parsing ignores unknown keys; repo regex allows ./.. segments — non-breaking

Evidence: read_lock (:124-144) reads exclude and ignores anything else, so excludes = ["remote"] (typo) silently excludes nothing and the next --update pulls remote.py into a stdio-only server. _REPO = r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+" (:82) accepts ../x, which becomes part of a raw.githubusercontent.com URL.
Fix: warn on unknown lock keys (list the known ones); reject repo segments that are ./...

CI & tooling

F10 · med · Workflow runs with default token permissions and tag-pinned actions — non-breaking

Evidence: .github/workflows/ci.yml has no permissions: block (the token gets the repo default, which may be write), actions/checkout@v7 / actions/setup-python@v7 are mutable tags, no timeout-minutes, no concurrency group, no Dependabot config (pip or github-actions). Python matrix 3.11–3.14 does cover what Alpine ships (3.12 on 3.20–3.22, 3.13 on edge) — fine.
Fix: permissions: contents: read, pin both actions to their v7 commit SHAs (3d3c42e5…, 6d4fd22b…) with a version comment, timeout-minutes: 15, concurrency: ${{ github.workflow }}-${{ github.ref }} with cancel-in-progress, .github/dependabot.yml for github-actions + pip (weekly). Siblings have the same gaps (6 of 9 lack permissions:); their copies of the pattern are out of scope here but worth a round.

F11 · low · No pre-commit; test templates excluded from lint — non-breaking

Evidence: pyproject.toml excludes templates/ from ruff/mypy (unavoidable: __PKG__), and there is no .pre-commit-config.yaml, so a template that fails lint is only caught after render in CI.
Fix: .pre-commit-config.yaml with ruff + a local hook that renders (sync_shared.py --source . --package mcp_shared) and lints tests/. Not addressed in this round.

Repo hygiene (public repo; code, docs, tests, history)

F12 · low · Room names and RFC 1918 addresses used as examples — non-breaking

Evidence: ratelimit.py:211 docstring example "Rate limit on Den: …"; templates/tests/test_ratelimit.py:84-85, 293-373 use "den", "office", "living room" as bucket keys. 192.168.1.{5,9,10,20,60,147} appear in logsafe.py:11, test_logsafe.py:42,104,151, test_remote.py:99,321-322,371. The portfolio convention is placeholders only; TEST-NET-1 (192.0.2.0/24) exists for exactly this.
Fix: "tv-1"/"tv-2"-style keys; 192.0.2.x everywhere (behaviour identical: only the last octet matters to the tests).
Secret scan of every blob in history (detect-secrets, plus a targeted PII pattern scan): no credentials, tokens, keys or hostnames found. Already-fixed history items are noted in the session report only, per the audit brief.

F13 · low · Docs: sibling list out of date — non-breaking

Evidence: CLAUDE.md:5-7 and README.md:16-24 list 8 siblings; mcp-server-misterfpga consumes shared (all 7 modules) and is missing. README should also say what a lock SHA must be (a main commit, not a PR-branch head) — the root cause of F1.

Architecture (RFC, not a PR)

F14 · RFC · copy-and-sync vs. a versioned package

Covered in the session report. Short version: keep copy-and-sync for now (zero-dependency Alpine LXC installs, byte-identical test templates, one SHA per sibling are real advantages at 9 consumers), but (a) make the lock point only at main commits (F1), (b) start tagging main (v0.x) so shared.lock can carry a human-readable version next to the SHA, and (c) revisit publishing mcp-server-shared to PyPI once the siblings themselves are on PyPI, because then pip install mcp-server-webos would need the shared package as a dependency anyway and the sync step becomes the odd one out.


PRs (all open 2026-11-08; CI green on Python 3.11–3.14)

PR Branch Findings Breaking Consumers affected
#17 audit/logsafe-secret-coverage F4, F6 no all 9 (logsafe, remote)
#18 audit/logsafe-mask-helpers F5 no all 9 (logsafe)
#19 audit/remote-graceful-shutdown F2 no all 9 (remote)
#20 audit/tasks-recancel-grace F3 no (default behaviour change) all 9 (tasks)
#21 audit/sync-atomic-and-lock-checks F1, F7, F9 no all 9 (sync script)
#22 audit/sync-dirty-tree F8 yes → draft, breaking; builds on #21 all 9 (sync script)
#23 audit/ci-hardening F10 no none (this repo's workflow)
#24 audit/hygiene-and-docs F12, F13 no all 9 (test templates, one docstring)

Not yet addressed: nothing; all closed in the second round (2026-11-10, details in the closing comment): F11 pre-commit (#29); F14 (b) tags and lock version (#31, v0.1.0/v0.1.1), (c) PyPI won't fix; initd retry and sibling CI permissions: (sibling PRs, item C); e-mail masking in redact() (#28); a shared shared-drift workflow, reusable rather than synced (#30). Shutdown paths that can still exceed 15 s are tracked in their own repos (sofabaton#27, webos#18, misterfpga#15, workbench#14).


Generated by Claude Code

Activity

  1. self-assigned this
    on Nov 10, 2026
  2. SDNick484 commented on Nov 11, 2026

    @SDNick484
    OwnerAuthor

    Second round (2026-11-10): what closed the remaining items

    Everything below is merged, and CI is green on main in every repo it touched. main is tagged v0.1.0 (9449e9f, after A) and v0.1.1 (5f9b824, after #33).

    A · mcp-server-shared

    Item PR Status
    A1 · JWKS lock comment; last_fetch only on a network fetch (it was a real bug: cache hits kept a rotated key refused for up to the 1 h cache) #27 merged
    A2 · redact() masks e-mail (u***@example.com), plus a fix for a quadratic _URL_PASSWORD regex and a flaky hypothesis test #28 merged
    A3 · pre-commit: ruff + render-and-lint of the test templates, SHA-pinned; Dependabot pre-commit ecosystem (F11) #29 merged
    A4 · reusable shared-drift workflow (workflow_call), read-only token, SHA-pinned, timeout, per-event concurrency #30 merged
    A5 · optional version lock key, written by --update, shown by --check/status (F14 b) #31 merged
    A6 · update --pr --auto-merge, off by default; reports and skips where auto-merge is off or no checks are required (all siblings today) #32 merged
    Test placeholders a sibling's privacy scan accepts #33 merged
    Sync commits always carry the account's name and noreply address, not the local git identity #34 merged

    B · sibling sync to 185fc55 (same shared files as v0.1.1)

    batocera#28 · harmony#23 · misterfpga#14 · onkyo#11 · pixelcade#18 · shieldtv#11 · sofabaton#26 · steam-backlog#11 · webos#17 · workbench#12: all merged. Two earlier rounds (at 9449e9f and 5f9b824) were closed unmerged: the first because #33 was needed, the second because its commits carried the local git identity (#34).

    C · sibling-side

    Item PRs Status
    C1 · initd retry="SIGTERM/15/SIGKILL/5", with each service's shutdown budget in a comment · C2 · CI permissions: contents: read, per-event concurrency (only PR runs cancel), timeout-minutes on every job, SHA-pinned actions, Dependabot (actions + pip, weekly), shared-drift calling #30's workflow at v0.1.1 batocera#25 · harmony#20 · misterfpga#11 · onkyo#8 · pixelcade#15 · shieldtv#8 · sofabaton#23 · steam-backlog#7 · webos#14 · workbench#7, workbench#13 merged
    Shutdown can still exceed 15 s; these need code changes, not a longer retry sofabaton#27 (worst case about 20 s, steps in sequence) · webos#18 (TVs one at a time, disconnect unbounded) · misterfpga#15 (tracker 5N + 2 s) · workbench#14 (exit waits on an in-flight git fetch/push) open issues (deferred)

    Related fixes made along the way: steam-backlog#10 adds a commit allowlist to its privacy scan, for one earlier sync commit that carried the local git identity. steam-backlog#12 and steam-backlog-triage#19 allow Dependabot's support@github.com sign-off, which was failing every PR's scan.

    F14 · architecture

    (a) lock only main commits: done in #21. (b) tag main, version in the lock: done (#31, v0.1.0/v0.1.1). (c) publish mcp-server-shared to PyPI: won't fix; copy-and-sync stays.

    Convention changes

    • main gets vX.Y.Z tags. shared.lock may carry version = "vX.Y.Z", written by --update when the locked commit is tagged. The first sync after this one writes it, because each sibling's --update runs its own (older) script. Rolling back means deleting the key.
    • Siblings' drift check is uses: SDNick484/mcp-server-shared/.github/workflows/shared-drift.yml@<SHA> # vX.Y.Z. Workflows are not synced files; Dependabot bumps that pin like an action.
    • redact() masks e-mail addresses by default: a log-output change for every consumer.
    • pre-commit is in the dev extra (pre-commit install).
    • Sync commits are always authored and committed as the account with its noreply address.
    • Every sibling CI job has a timeout, every action is SHA-pinned with its version as a comment, and the token is read-only unless a job asks for more.
    • Every initd sets retry="SIGTERM/15/SIGKILL/5"; supervise-daemon reads it at start.

    Deploying the merged services, along with their new initd files, is a separate step.

    🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions