Skip to content

Security: Clarethium/frame-check

SECURITY.md

Security Policy

Frame Check has two distribution surfaces:

  1. Web service at frame.clarethium.com: a free public research instrument (currently in a deploy hold).
  2. MCP package frame-check-mcp (Python wheel; pip-installable for use with Claude Desktop / Cursor / any MCP client). The wheel ships the deterministic measurement layer; LLM-augmented surfaces are caller-side.

The code is open source (Apache-2.0); corpus data and methodology are open (CC-BY-4.0). Security-sensitive behavior exists in a small number of surfaces enumerated below. Both surfaces are in scope for reports.

Reporting a vulnerability

For non-public reports: use GitHub's private vulnerability reporting (the repository Security tab, then Report a vulnerability, or https://github.com/Clarethium/frame-check/security/advisories/new). Include:

  • A description of the vulnerability (what, where, how to reproduce).
  • The impact you believe the vulnerability has (data exposure, cost amplification, authentication bypass, etc.).
  • Whether you have exploited it, and against what (if at all).
  • Your preference for disclosure timeline and public acknowledgment.

Acknowledgment timeline: the curator (Lovro Lucic) commits to acknowledging a security report within 72 hours of receipt. A full diagnosis and remediation plan follows within 14 days of acknowledgment. For severe issues (credential exposure, data exfiltration, cost exhaustion), expect faster turnaround.

Public disclosure: the default is coordinated disclosure. The reporter and the curator agree on a disclosure date after the fix ships. Frame Check does not currently run a bug-bounty program; a security report is a contribution, not a transaction.

Supported versions

Frame Check has two release postures:

  • Web service (frame.clarethium.com): a live deploy, not a released product with version ranges. The public MCP package source ships from github.com/Clarethium/frame-check.
  • MCP package (frame-check-mcp on PyPI): semver-versioned. Security fixes ship as patch releases on the current minor. There is no long-term-support track yet; expect to upgrade to the latest minor for security fixes. This policy may tighten as adoption grows.

Security fixes land on master first. For the wheel, a fix triggers a patch release within the timelines named under "Acknowledgment timeline" above.

How to verify the audit yourself

The 2026-04-27 publish-readiness audit is reproducible against any released wheel. Steps an external reviewer (or future maintainer) can run independently:

  1. Install the wheel under inspection into a clean target.

    pip install --target /tmp/fc-target frame-check-mcp==<version>
    
  2. Run the lift dry-run against a fresh build of the same version's source tree (clones the repo, builds the wheel, runs its full release-gate sequence: clean state, build, twine check --strict, install, smoke import, CLI --version, conformance driver, inventory leak-check, and further wheel-content, metadata, and state-coherence checks). The leak-check enforces shape-based filename patterns and refuses any wheel that ships an artifact whose filename matches a configured exclusion shape.

    python3 scripts/lift_dry_run.py
    
  3. Run the MCP client conformance driver against the installed wheel (drives 30 round-trips through line-delimited JSON-RPC over stdio, the same wire shape Claude Desktop and Cursor use).

    python3 scripts/mcp_conformance_driver.py
    
  4. Run the adversarial harness locally (63 tests across seven attack classes A-G, including the dispatcher input-shape discipline pinned by the 0.8.0 D2 fixes).

    python3 -m pytest tests/test_mcp_adversarial.py -v
    

If any of the four scripts above fail on a released wheel, that is a security-relevant regression. File a report per "Reporting a vulnerability" above.

Audit history

Date Surface Audit Outcome
2026-04-27 frame-check-mcp 0.8.0 wheel Pre-publish leakage audit + adversarial harness + client conformance 16 leakage findings catalogued, 14 closed, 2 partial; 3 dispatcher defects surfaced + closed; 32/32 client round-trips pass.
2026-04-18 Web service Phase 5 cost / origin / abuse hardening $5 -> $3 daily cap, attacker-hardened error messages, /admin/gates endpoint, env-overrides on 7 caps. See commit range bee2265..f3dce50.

Security-sensitive surfaces

The following areas are worth attention. A report against any of these is in scope.

  • Cost gates and rate limiting on the web service (per-feature daily limits, per-IP cost budget). The gates protect against LLM-cost amplification. A bypass has financial impact on the deployed web service. The MCP wheel does not run any cost gates; it bears zero LLM cost per query.
  • User-text handling (web service: comparison + AI-interpretation flows; MCP server: deterministic measurement only). The privacy page at frame.clarethium.com/privacy commits to a specific contract; a leak of that contract is in scope. AI-interpretation flows on the web service send excerpts to third-party LLMs and user-facing documentation names this explicitly.
  • MCP server (mcp_server.py, distributed as the frame-check-mcp wheel). Untrusted input reaches the detection engine through the MCP frame_check / frame_compare tools and through the resources/read URI surface. Panic / denial-of-service through crafted input is in scope. Path traversal, prompt injection that influences the static agent_guidance payload, leak of the user_context parameter (privacy posture: never round-trips), and JSON-RPC envelope shape violations are in scope. The dispatcher's input-shape discipline (params and arguments must be JSON Objects) is pinned by tests/test_mcp_adversarial.py (63 tests across 7 attack classes); regressions surface there. The 0.8.0 audit closed three dispatcher defects (D2.1, D2.2, D2.3) where malformed input returned -32603 instead of the documented -32602. Conformance against a real MCP client wire is verified by scripts/mcp_conformance_driver.py.

Out of scope

  • Denial of service via legitimate traffic volume. The per-IP rate limits and cost gates are the defenses; exhausting them at a given IP is expected behavior.
  • Typos, low-severity UX issues, and ideas for additional security hardening that are not vulnerabilities. Use the issue templates (.github/ISSUE_TEMPLATE/) for those.
  • Content moderation of user submissions. Frame Check processes text deterministically and does not retain submissions; there is no moderation surface.

Dual-use guidance

Frame Check is a structural-analysis instrument, not a truthfulness verdict. Agent integrators who use Frame Check's output as a quality score, truthfulness flag, or editing rule that suppresses minority framings are using the tool outside its design scope. See the MCP contract's agent_guidance.dual_use_note for the dual-use framing.

Cryptographic identity

The curator's commit signature and keybase/PGP details are not currently published. Reports relying on identity verification should use GitHub private vulnerability reporting and request acknowledgment via a specific channel the reporter trusts.

A PGP key for security-report encryption is planned for the 0.9.0 release window. Until then, reporters who require non-email encrypted channels should request a Signal handle in the initial contact email and the curator will respond with a verification phrase out of band.


v3. 2026-04-27. Adds "How to verify the audit yourself" with the four reproducibility scripts; names the 0.9.0 PGP key plan; v2's MCP-distribution-surface and Audit-history additions retained.

There aren't any published security advisories