Add MCP framework remediation guide

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
 

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

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.

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.

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');
+  });
+});