{"id":51158658,"url":"https://github.com/malkreide/mcp-audit-skill","last_synced_at":"2026-06-26T12:02:07.450Z","repository":{"id":353920816,"uuid":"1221418638","full_name":"malkreide/mcp-audit-skill","owner":"malkreide","description":"Claude-Skill für systematische MCP-Server-Audits gegen einen kuratierten Best-Practice-Standards-Korpus · 68 Checks · 8 Kategorien · OAuth 2.1, OWASP, Lethal Trifecta, Schweiz-Compliance (DSG/ISDS) · MIT","archived":false,"fork":false,"pushed_at":"2026-05-06T11:33:33.000Z","size":514,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T13:32:40.669Z","etag":null,"topics":["audit","claude-code","claude-skills","compliance","defense-in-depth","dsg","governance","mcp","model-context-protocol","oauth2","oeffentliche-verwaltung","prompt-injection","public-sector","security-audit","solid-principles","swiss-public-data","swissmade"],"latest_commit_sha":null,"homepage":"https://github.com/malkreide/swiss-public-data-mcp","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/malkreide.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T07:13:45.000Z","updated_at":"2026-05-06T11:20:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/malkreide/mcp-audit-skill","commit_stats":null,"previous_names":["malkreide/mcp-audit-skill"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/malkreide/mcp-audit-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malkreide%2Fmcp-audit-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malkreide%2Fmcp-audit-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malkreide%2Fmcp-audit-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malkreide%2Fmcp-audit-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/malkreide","download_url":"https://codeload.github.com/malkreide/mcp-audit-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/malkreide%2Fmcp-audit-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34815669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audit","claude-code","claude-skills","compliance","defense-in-depth","dsg","governance","mcp","model-context-protocol","oauth2","oeffentliche-verwaltung","prompt-injection","public-sector","security-audit","solid-principles","swiss-public-data","swissmade"],"created_at":"2026-06-26T12:02:05.692Z","updated_at":"2026-06-26T12:02:07.444Z","avatar_url":"https://github.com/malkreide.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-audit-skill\n\n\u003e Claude-Skill für systematische Audits von MCP-Servern gegen einen kuratierten Best-Practice-Standards-Korpus. **68 Checks**, 8 Kategorien, mit Schweiz-Compliance-Layer für die öffentliche Verwaltung.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Checks: 68](https://img.shields.io/badge/Checks-68-blue.svg)](./checks/)\n[![Coverage: A1–A9, B1–B12, C1–C4](https://img.shields.io/badge/Best--Practice%20Coverage-A1%E2%80%93A9%2C%20B1%E2%80%93B12%2C%20C1%E2%80%93C4-success)](./CHANGELOG.md)\n[![MCP Spec: 2025-06-18](https://img.shields.io/badge/MCP%20Spec-2025--06--18-orange)](https://modelcontextprotocol.io/specification/)\n\n---\n\n**Was es ist:** Ein Claude-Skill, der MCP-Server systematisch gegen veröffentlichte Best Practices auditiert. Jeder Check referenziert seine Quelle, hat klare Pass-Kriterien, einen Remediation-Pfad und einen Aufwands-Indikator.\n\n**Was es nicht ist:** Kein automatischer Code-Scanner, kein Vulnerability-Tool, kein Compliance-Stempel. Der Skill macht die Methodik reproduzierbar — Architektur-Urteile bleiben menschlich.\n\n## Architektur-Modell\n\nDie Checks orientieren sich am Fünf-Schichten-Sicherheitsmodell, das in der MCP-Sicherheits-Community als Konsens-Architektur etabliert ist. Jede Schicht prüft eigenständig — keine vertraut der nächsthöheren blind.\n\n```text\n┌────────────────────────────────────────────────────────┐\n│  LLM-Host (Claude, ChatGPT, Cursor)                    │\n│  Untrusted: kann Prompt-Injektionen enthalten          │\n└────────────────────────┬───────────────────────────────┘\n                         │\n┌────────────────────────▼───────────────────────────────┐\n│  MCP-Gateway / Policy Layer                            │\n│  Rate-Limit · Audit-Log · DLP · Tool-Allowlist         │\n└────────────────────────┬───────────────────────────────┘\n                         │\n┌────────────────────────▼───────────────────────────────┐\n│  Authentifizierung \u0026 Autorisierung                     │\n│  OAuth 2.1 + PKCE · Resource Indicators · Scopes       │\n└────────────────────────┬───────────────────────────────┘\n                         │\n┌────────────────────────▼───────────────────────────────┐\n│  MCP-Server-Logik                                      │\n│  Input-Validierung · Schema · Idempotenz · Sandbox     │\n└────────────────────────┬───────────────────────────────┘\n                         │\n┌────────────────────────▼───────────────────────────────┐\n│  Datenquelle / Backend                                 │\n│  Read-only Service-Account · Least Privilege           │\n└────────────────────────────────────────────────────────┘\n```\n\n## SOLID für MCP-Server\n\nDie fünf Prinzipien, an denen sich der gesamte Check-Katalog ausrichtet:\n\n| Prinzip | Bedeutung | Schlüssel-Checks |\n|---|---|---|\n| **S**andbox | Jeder Server in Docker / WASM mit Egress-Filter | [`SEC-007`](./checks/SEC-007.md), [`SEC-021`](./checks/SEC-021.md) |\n| **O**Auth 2.1 | OAuth statt API-Keys, mit PKCE und Resource Indicators | [`SEC-001`](./checks/SEC-001.md), [`SEC-002`](./checks/SEC-002.md), [`SEC-003`](./checks/SEC-003.md) |\n| **L**east Privilege | Service-Account-Rechte minimal halten | [`SEC-003`](./checks/SEC-003.md), [`SEC-013`](./checks/SEC-013.md) |\n| **I**dempotency | Idempotency-Keys + Compensating Actions bei jedem Write | [`ARCH-010`](./checks/ARCH-010.md) |\n| **D**efense-in-Depth | Gateway + Auth + Schema + Sandbox + DLP gestapelt | [`SCALE-005`](./checks/SCALE-005.md), [`SEC-018`](./checks/SEC-018.md), [`SEC-023`](./checks/SEC-023.md) |\n\nWer alle fünf abdeckt, ist gegen ~80% der heute beobachteten Angriffsklassen geschützt. Die übrigen ~20% — primär Prompt-Injection auf Tool-Description-Ebene — sind strukturell ungelöst und brauchen organisatorische Kontrollen (Human-in-the-Loop, Threat Detection, Audit-Reviews).\n\n## Anchor-Demo\n\n\u003e «Erfüllt mein `parlament-mcp`-Server alle 23 Security-Checks für eine Phase-1-Read-only-Anbindung an Stadt-Zürich-Verwaltungsdaten?»\n\nMit installiertem Slash-Command:\n\n```\n\u003e /audit-mcp .\n```\n\nOutput: Profil-getriebene Auswahl der ~30 anwendbaren Checks aus 68, automatisierte Verifikation aller `automated`/`config_check`/`documentation_check`-Modi, Findings-Stubs für `code_review`/`runtime_test`-Modi, vollständiger Audit-Report nach Template — alles in `\u003crepo\u003e/audits/YYYY-MM-DD-\u003cserver-name\u003e/`.\n\n## Standards-Provenance\n\nDie 68 Checks sind systematische Übersetzungen aus zwei kuratierten Best-Practice-Dokumenten in auditierbare Form. Jeder Check trägt im Frontmatter eine `pdf_ref`-Referenz auf seine Quelle.\n\n| Quelle | Inhalt | Abgeleitete Checks |\n|---|---|---|\n| **Hauptkatalog** «MCP Server-Entwicklung — Best Practices \u0026 Standards» | Architektur, SDK-Patterns, Security, Skalierung, Observability, Human-in-the-Loop | 54 Checks (v0.1–v0.4) |\n| **Architektur-Anhang** «Architektur und Sicherheit von MCP-Servern» | Sektion A (Architektur, A1–A9), Sektion B (Sicherheit, B1–B12), Sektion C (Operative Praxis, C1–C4); schliesst u.a. Lethal-Trifecta-, Idempotency- und Egress-Control-Lücken | 14 Checks (v0.5) |\n| **Schweiz-Compliance-Layer** | revDSG, EDÖB-Meldepflicht, ISDS Stadt Zürich, OGD-Lizenz-Compliance, Volksschule-spezifische Datenschutz-Anforderungen | 8 Checks (`CH-*`) |\n\n## Schnellstart\n\n### Voraussetzungen — Cross-Platform\n\n| Betriebssystem | Voraussetzung |\n|---|---|\n| Linux / macOS | Python 3.11+, Bash, `git`, `yq` |\n| Windows (Git Bash) | Python 3.11+ mit `PYTHONUTF8=1`, Git Bash, `git`, `yq` |\n\n**Windows-User:** Setze die Env-Var `PYTHONUTF8=1` in deinem Profil (oder pro Session), sonst crasht Python beim Schreiben von Umlauten/Emojis:\n\n```powershell\n# PowerShell\n[Environment]::SetEnvironmentVariable(\"PYTHONUTF8\", \"1\", \"User\")\n\n# Git Bash\necho 'export PYTHONUTF8=1' \u003e\u003e ~/.bashrc\n```\n\nPfad-Helpers für Skill-Scripts liegen unter [`tools/paths.sh`](tools/paths.sh) (Bash) und [`tools/path_utils.py`](tools/path_utils.py) (Python). Sie konvertieren zwischen `/c/Users/foo` (Git Bash) und `C:\\Users\\foo` (Windows-native, was die Read/Edit/Write-Tools brauchen).\n\n### Als Claude-Code-Slash-Command (`/audit-mcp`)\n\nDer Skill bringt einen Slash-Command mit, der den 6-Schritte-Workflow als Claude-Code-Workflow ausführt — Profil-Load, Applicability-Filter, automatisierte Check-Ausführung, Findings-Generierung und Report-Erstellung in einem Lauf.\n\n```bash\ngit clone https://github.com/malkreide/mcp-audit-skill.git\ncd mcp-audit-skill\n./setup-slash-command.sh\n```\n\nDas Setup-Script symlinkt `.claude/commands/audit-mcp.md` nach `~/.claude/commands/`, damit `/audit-mcp` global in jeder Claude-Code-Session verfügbar ist.\n\nVerwendung:\n\n```bash\n# In einem MCP-Server-Repo oder beliebigen Verzeichnis\nclaude\n```\n\n```\n\u003e /audit-mcp .\n\u003e /audit-mcp /pfad/zum/server-repo\n\u003e /audit-mcp https://github.com/malkreide/zh-education-mcp\n```\n\nOutput landet in `\u003crepo\u003e/audits/YYYY-MM-DD-\u003cserver-name\u003e/` mit:\n\n- `audit-report.md` — Gesamtreport nach Template\n- `findings/\u003ccheck-id\u003e-*.md` — pro Fail/Partial-Check ein Finding\n- `raw/\u003ccheck-id\u003e.txt` — Roh-Output der Bash-Befehle für Audit-Trail\n\nAutomatisierungstiefe ist **Standard**: alle `automated`/`config_check`/`documentation_check`-Modi laufen automatisch, `code_review`/`runtime_test`-Modi werden als TODO mit Such-Pattern in den Report geschrieben (kein Pattern-Match-Halluzinieren).\n\n### Portfolio-Batch-Audit (`audit-portfolio.sh`)\n\nWenn du mehrere MCP-Server in einem Run auditieren willst, nutze das Top-Level-Script `audit-portfolio.sh`. Es liest deine `portfolio.yaml` (Server-Liste mit Profil pro Server), klont jedes Repo, ruft `claude -p` mit dem `/audit-mcp`-Slash-Command non-interactive auf und aggregiert die Findings in eine `portfolio-summary.md`.\n\n```bash\ncp portfolio.example.yaml portfolio.yaml\n$EDITOR portfolio.yaml          # deine Server-Liste anpassen\n./audit-portfolio.sh --dry-run  # Plan verifizieren, kein claude-Call\n./audit-portfolio.sh            # echter Run, alle Server sequenziell\n./audit-portfolio.sh zh-education-mcp foo-mcp   # Subset\n./audit-portfolio.sh --force    # auch heute schon auditierte Server neu\n```\n\n`portfolio.yaml` ist `.gitignore`d — committe deine Server-Liste nicht versehentlich. Dependencies: `yq` (Mike Farahs Go-yq oder kislyuks Python-yq + `jq`), `git`, `claude` CLI. Output landet in `portfolio-logs/\u003cdatum\u003e/`.\n\n### Notion-Sync (`audit-notion-sync.py`) — bidirektionale Tracker-Integration\n\nWenn dein Audit-Tracker in Notion lebt, nutze `audit-notion-sync.py` für bidirektionale Synchronisation: Pull generiert `portfolio.yaml` aus dem Tracker, Push schreibt Findings-Anzahl und Audit-Status nach jedem Lauf zurück. Stdlib-only, kein `pip install` nötig.\n\n**Einmaliges Setup:**\n\n1. In Notion: Tracker → `•••` → **Connections** → **+ Add connections** → deine Internal Integration auswählen\n2. Im Tracker eine neue Property anlegen: Name `Org-Kontext`, Type `Multi-select`, Optionen `Stadt Zürich`, `Schulamt`, `Volksschule`, `Enterprise` — dann pro Server ankreuzen, was zutrifft\n3. Token in deine Shell-RC (niemals committen):\n   ```bash\n   export NOTION_TOKEN=\"ntn_...\"\n   ```\n4. Verifizieren:\n   ```bash\n   python3 audit-notion-sync.py health\n   ```\n\n**Verwendung:**\n\n```bash\n# Nur Pull (Tracker → portfolio.yaml)\npython3 audit-notion-sync.py pull --force\n./audit-portfolio.sh\n\n# Oder kombiniert: Pull, Audit, Push in einem Run\n./audit-portfolio.sh --from-notion --sync-back\n```\n\nDer Pull filtert standardmässig auf Server mit `Audit-Status` ∈ {`Triagiert`, `In Audit`} — `--all` ignoriert den Filter. Der Push setzt `Findings` (number), `Audit-Status` (auf `Findings dokumentiert`) und appendet eine Notiz mit dem Report-Pfad. Formula-Felder (`Risiko-Score`, `Reife-Score`, `Prio`) bleiben unangetastet.\n\nDie DB-ID ist als Default auf `a2736a65-677d-4cf3-9f94-e874f74a1975` (Stadt Zürich Schulamt MCP Audit Tracker) gesetzt; `NOTION_AUDIT_DB_ID` env var überschreibt.\n\n### Als Claude.ai-Skill (manuell)\n\n```bash\ngit clone https://github.com/malkreide/mcp-audit-skill.git ~/skills/mcp-audit\n```\n\nDann in Claude.ai: `Verwende mcp-audit-Skill für \u003cserver-name\u003e`. Der Workflow läuft dann interaktiv ohne Slash-Command-Automatisierung.\n\n## Check-Katalog im Überblick\n\n| Code | Bereich | Quelle | Anzahl | Severity-Profil |\n|---|---|---|---:|---|\n| `ARCH` | Tool-Design, Annotations, Idempotency, Repo-Struktur, Spec-Versionierung | Hauptkatalog Sec 2 + Anhang A | 12 | 1 critical · 7 high · 4 medium |\n| `SDK` | FastMCP, TypeScript, Zod, Lifecycle | Hauptkatalog Sec 3 | 5 | — · 3 high · 2 medium |\n| `SEC` | Security (grösste Kategorie) | Hauptkatalog Sec 4 + Anhang B | 23 | 14 critical · 8 high · 1 medium |\n| `SCALE` | Transport, Load Balancing, Container, Gateway | Hauptkatalog Sec 5 | 6 | — · 3 high · 3 medium |\n| `OBS` | Logging, Errors, SIEM, OpenTelemetry | Hauptkatalog Sec 6 + Anhang B10 | 6 | 1 critical · 1 high · 4 medium |\n| `HITL` | Sampling, Human-in-the-Loop | Hauptkatalog Sec 7 | 5 | 1 critical · 4 high · — |\n| `CH` | DSG/EDÖB, ISDS Stadt Zürich, Volksschule | Custom | 8 | 3 critical · 4 high · 1 medium |\n| `OPS` | Test-Strategie, Doku-Standard, Phasenarchitektur | Anhang C | 3 | — · 2 high · 1 medium |\n| **Total** | | | **68** | **15 critical · 31 high · 22 medium** |\n\n## Severity-Stufen\n\n| Stufe | Bedeutung | Konsequenz |\n|---|---|---|\n| `critical` | Sicherheitslücke / Compliance-Bruch | Blockiert Produktion |\n| `high` | Architektureller Mangel mit signifikantem Risiko | Im laufenden Sprint fixen |\n| `medium` | Best-Practice-Verletzung | Im nächsten Sprint planen |\n| `low` | Polish, Optimierung | Backlog |\n\n## Audit-Workflow (Kurzform)\n\n1. **Profil laden** — Server-Eigenschaften aus Notion-Audit-Tracker oder via Inferenz aus dem Repo\n2. **Katalog laden** — alle 68 Checks parsen\n3. **Applicability-Filter** — nur passende Checks selektieren (z.B. stdio-only-Server überspringt OAuth-Checks)\n4. **Check-Ausführung** — automatisiert (grep, AST, Config-Scan) oder als Code-Review-TODO pro Check\n5. **Findings dokumentieren** — `templates/finding.md`\n6. **Audit-Report** — `templates/audit-report.md`\n\nDetails siehe [`SKILL.md`](./SKILL.md).\n\n## Positionierung gegenüber verwandten Tools\n\n| Tool | Kategorie | Fokus |\n|---|---|---|\n| `apisec-inc/mcp-audit` | Code-Scanner | Lokale MCP-Configs (Secrets, Shadow-APIs, AI-BOM, SARIF) |\n| `ModelContextProtocol-Security/mcpserver-audit` (CSA) | Tutorial-Tool | Lehrt CWE/AIVSS-Methodik anhand von Beispiel-Servern |\n| `qianniuspace/mcp-security-audit` | Dependency-Scanner | npm-Vulnerability-Scan für MCP-Pakete |\n| **`malkreide/mcp-audit-skill`** | **Audit-Framework** | **Systematische Prüfung gegen kuratierten Best-Practice-Korpus + CH-Compliance** |\n\nKomplementär nutzbar — keiner der Genannten ersetzt die anderen.\n\n## Verwandte Repos\n\n- [`malkreide` MCP-Server-Portfolio](https://github.com/malkreide?tab=repositories) — die Server, gegen die dieses Skill auditiert wird\n- Notion **MCP Audit Tracker** — laufender Status aller Server-Audits (intern)\n- Notion **MCP Server Portfolio** — Master-Inventar aller Server (intern)\n\n## Status\n\n**Version:** v1.0.0 — Production-Ready Reproducibility (10 Helper-Scripts, 255 pytest cases, CI auf Ubuntu + Windows × py3.11 + py3.13). Siehe [CHANGELOG.md](./CHANGELOG.md) für die vollständige Release-History.\n\n**Vollständigkeit:**\n- ✅ Methodik (`SKILL.md`) und Templates (Finding, Audit-Report)\n- ✅ Reference-Summary\n- ✅ Check-Katalog: **68 Checks, alle 8 Kategorien vollständig**\n- ✅ Slash-Command für Claude Code (`/audit-mcp \u003crepo\u003e`)\n- ✅ Portfolio-Batch-Audit (`audit-portfolio.sh` für Multi-Server-Runs)\n- ✅ Notion-Sync (`audit-notion-sync.py` für bidirektionale Tracker-Integration)\n- ✅ Vollständige Abdeckung beider Standards-Quellen (Hauptkatalog + Architektur-Anhang)\n\nKünftige Erweiterungen kommen aus Real-World-Findings beim Portfolio-Audit, MCP-Spec-Updates oder neuen Compliance-Anforderungen (EU AI Act, Schweizer KI-Gesetz). Versions-Roadmap siehe [`docs/roadmap.md`](./docs/roadmap.md).\n\n## Lizenz\n\nMIT — siehe [`LICENSE`](./LICENSE).\n\n## Kontext\n\nEntwickelt im Rahmen des Swiss Public Data MCP Portfolio. Frei verwendbar von anderen Verwaltungen, Forschungsinstituten oder Privatpersonen, die MCP-Server systematisch auditieren wollen.\n\nPull Requests willkommen — insbesondere für ergänzende Compliance-Layer anderer Jurisdiktionen (DSGVO-Spezifika, kantonale Datenschutzgesetze, sektorspezifische Vorgaben).\n\n---\n\n**Autor:** [Hayal Oezkan](https://github.com/malkreide)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalkreide%2Fmcp-audit-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmalkreide%2Fmcp-audit-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmalkreide%2Fmcp-audit-skill/lists"}