From f471574b8a5b0187a2446387d828f6c309f6ffed Mon Sep 17 00:00:00 2001 From: soria Date: Wed, 6 May 2026 22:35:10 -0400 Subject: [PATCH] Add MCP framework remediation guide --- docs/README.md | 1 + docs/frameworks.md | 3 + docs/frameworks/README.md | 13 ++ docs/frameworks/mcp.md | 189 ++++++++++++++++++ tests/unit/framework-remediation-docs.test.ts | 22 ++ 5 files changed, 228 insertions(+) create mode 100644 docs/frameworks/README.md create mode 100644 docs/frameworks/mcp.md create mode 100644 tests/unit/framework-remediation-docs.test.ts diff --git a/docs/README.md b/docs/README.md index 11ff6a3..03aa980 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,6 +30,7 @@ Welcome to the g0 documentation. g0 runs background checks on your AI agents — - [**MCP Security**](mcp-security.md) — Assess MCP servers, detect rug-pulls, pin tool descriptions - [**Dynamic Testing**](dynamic-testing.md) — 4,000+ adversarial payloads, adaptive attacks, CVSS scoring, 20 attack categories, 20 mutators - [**Framework Guide**](frameworks.md) — Per-framework detection, patterns, and findings +- [**Framework Remediation Guides**](frameworks/) — Framework-specific fixes for common g0 findings ## Integration diff --git a/docs/frameworks.md b/docs/frameworks.md index 6291bf1..9a8c9c2 100644 --- a/docs/frameworks.md +++ b/docs/frameworks.md @@ -181,6 +181,9 @@ result = Runner.run(agent, "Analyze this data") See [MCP Security](mcp-security.md) for the full MCP assessment guide. +For framework-specific remediation examples, see the +[MCP remediation guide](frameworks/mcp.md). + --- ## Vercel AI SDK diff --git a/docs/frameworks/README.md b/docs/frameworks/README.md new file mode 100644 index 0000000..1ed5188 --- /dev/null +++ b/docs/frameworks/README.md @@ -0,0 +1,13 @@ +# Framework remediation guides + +These guides show how to turn g0 findings into framework-specific fixes. +They complement the high-level [Framework Guide](../frameworks.md) by focusing +on concrete before/after remediation patterns. + +Available guides: + +- [Model Context Protocol (MCP)](mcp.md) + +Each guide keeps examples intentionally small and reviewable. The examples are +not a guarantee of security or compliance; they are starting points for fixing +specific finding classes in the target framework. diff --git a/docs/frameworks/mcp.md b/docs/frameworks/mcp.md new file mode 100644 index 0000000..5e4e077 --- /dev/null +++ b/docs/frameworks/mcp.md @@ -0,0 +1,189 @@ +# MCP remediation guide + +This guide maps common g0 MCP findings to concrete remediation patterns. It +focuses on tool validation, least privilege, transport hardening, and audit +evidence for agent tool calls. + +## Findings covered + +| Finding class | Relevant g0 area | Remediation pattern | +| --- | --- | --- | +| Tool lacks input validation | Tool safety | Add `inputSchema` with bounded JSON Schema | +| Filesystem access is too broad | Tool safety | Scope roots to explicit read/write directories | +| MCP package version is unpinned | Supply chain | Pin package versions or use a reviewed local server | +| Shell execution is exposed | Code execution | Remove shell tools or require human review | +| Remote transport has weak controls | Identity and access | Use authenticated HTTPS/SSE with explicit allowlists | +| Tool description changed unexpectedly | Tool safety | Pin and diff tool descriptions before use | + +## 1. Add input schema validation + +Before: + +```json +{ + "name": "search_docs", + "description": "Search company documents" +} +``` + +After: + +```json +{ + "name": "search_docs", + "description": "Search approved company documents", + "inputSchema": { + "type": "object", + "additionalProperties": false, + "required": ["query"], + "properties": { + "query": { + "type": "string", + "minLength": 3, + "maxLength": 300 + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 10, + "default": 5 + } + } + } +} +``` + +Why this helps: + +- agents cannot pass unbounded or unexpected arguments +- downstream tools receive typed inputs +- audit records can show which schema was enforced + +## 2. Scope filesystem servers + +Before: + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/"] + } + } +} +``` + +After: + +```json +{ + "mcpServers": { + "filesystem-readonly-docs": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem@2026.1.14", + "./docs" + ] + } + } +} +``` + +Prefer separate read-only and write-capable servers. Route write-capable tools +through human review for production workspaces. + +## 3. Pin server packages + +Before: + +```json +{ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"] +} +``` + +After: + +```json +{ + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github@2025.4.8"] +} +``` + +Pinning reduces package rug-pull risk and makes tool description drift easier +to review in CI. + +## 4. Gate shell or deploy tools + +Before: + +```json +{ + "name": "run_shell", + "description": "Run any shell command", + "inputSchema": { + "type": "object", + "properties": { + "command": { "type": "string" } + } + } +} +``` + +After: + +```json +{ + "name": "run_checked_command", + "description": "Run an allowlisted read-only diagnostic command", + "inputSchema": { + "type": "object", + "additionalProperties": false, + "required": ["command"], + "properties": { + "command": { + "type": "string", + "enum": ["git status --short", "npm test", "pytest"] + } + } + } +} +``` + +Shell, deploy, delete, permission-changing, export, and payment tools should +produce an audit record and require explicit approval before execution. + +## 5. Record a minimal tool-call audit event + +Use a redacted audit event when a tool call is allowed, denied, modified, or +routed to review: + +```json +{ + "event_id": "mcp_tool_evt_001", + "server": "filesystem-readonly-docs", + "tool": "search_docs", + "decision": "allow", + "args_hash": "sha256:example-argument-fingerprint", + "policy": "mcp-tool-policy-v1", + "review_required": false, + "redacted_fields": ["arguments.query"] +} +``` + +Store hashes, policy identifiers, and decisions instead of raw prompts, secrets, +credentials, or private document text. + +## g0 review checklist + +- [ ] Tool has an `inputSchema` with `additionalProperties: false`. +- [ ] Unbounded strings, arrays, and numeric limits are capped. +- [ ] MCP package versions are pinned. +- [ ] Filesystem, shell, network, deploy, and data-export tools are scoped. +- [ ] Human review is required for destructive or irreversible tools. +- [ ] Tool descriptions are pinned or diffed before use. +- [ ] Audit records store hashes and redacted metadata, not raw sensitive data. diff --git a/tests/unit/framework-remediation-docs.test.ts b/tests/unit/framework-remediation-docs.test.ts new file mode 100644 index 0000000..dd4323c --- /dev/null +++ b/tests/unit/framework-remediation-docs.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from 'vitest'; +import { readFileSync } from 'node:fs'; + +describe('framework remediation docs', () => { + it('links the MCP remediation guide from the docs index', () => { + const docsIndex = readFileSync('docs/README.md', 'utf8'); + const frameworksGuide = readFileSync('docs/frameworks.md', 'utf8'); + + expect(docsIndex).toContain('frameworks/'); + expect(frameworksGuide).toContain('frameworks/mcp.md'); + }); + + it('covers key MCP remediation patterns', () => { + const guide = readFileSync('docs/frameworks/mcp.md', 'utf8'); + + expect(guide).toContain('inputSchema'); + expect(guide).toContain('additionalProperties'); + expect(guide).toContain('Pin server packages'); + expect(guide).toContain('tool-call audit event'); + expect(guide).toContain('Human review'); + }); +});