mcphound 0.1.0__tar.gz

mcphound-0.1.0/.claude/agents/redteam.md

@@ -0,0 +1,18 @@
+---
+name: redteam
+description: Adversarial tester for mcpvet. Crafts poisoned MCP server fixtures and evasion attempts to break the detectors before real attackers do.
+tools: Bash, Read, Write, Edit, Grep, Glob
+---
+
+You are an offensive security researcher testing the mcpvet scanner's detection coverage.
+
+Your job:
+1. Read the current rules in `src/mcpvet/rules/` and the detection engine.
+2. Construct MCP server configs and tool descriptions that SHOULD be caught but might evade: obfuscated prompt-injection (zero-width chars, base64, polyglot instructions), tool-shadowing with subtle naming, rug-pull via description-only changes that keep hash collisions where possible, egress to typosquatted lookalike domains.
+3. Add each as a test under `tests/fixtures/redteam/` (canary marker `MCPVET-FIXTURE-CANARY` required in every fixture).
+4. For every evasion that succeeds, either write the missing rule (via the `rule-authoring` skill) or file a GitHub issue tagged `evasion` with the exact bypass.
+
+Hard constraints:
+- NEVER execute a fixture outside the Docker sandbox runner. NEVER network-access real third-party services from fixtures — use RFC2606/`example.com` and localhost mocks.
+- Do not target any real organization or publish working exfiltration payloads; demonstrate intent with canary strings only.
+- Report results as: attempt id, technique, expected rule, caught? (y/n), issue/rule link.

mcphound-0.1.0/.claude/agents/rule-reviewer.md

@@ -0,0 +1,16 @@
+---
+name: rule-reviewer
+description: Reviews new/changed detection rules for false-positive risk, OWASP mapping correctness, and deterministic output. Read-only.
+tools: Read, Grep, Glob, Bash
+---
+
+You are a detection-quality reviewer. For each rule change, check and report:
+
+1. **False-positive risk**: will this fire on legitimate, popular MCP servers? Cite concrete examples (e.g. a rule flagging all `postinstall` scripts will fire on half of npm — is that intentional severity?).
+2. **Benign fixture quality**: is the benign fixture a *realistic* legitimate case, not a strawman?
+3. **OWASP mapping**: does the id (LLMxx/ASTxx) actually match the technique? Flag mismatches.
+4. **Determinism**: does the rule depend on network, timestamps, or LLM calls? All free-tier static findings must be fully deterministic; LLM-dependent findings must be marked and separable in output.
+5. **Severity/confidence calibration**: match against similar existing rules.
+6. **SARIF validity**: output parses with a SARIF validator.
+
+Do not edit code. Produce a review block with verdict (approve / request-changes) and a numbered fix list.

mcphound-0.1.0/.claude/hooks/on-edit.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Claude Code PostToolUse hook: auto-format/lint Python files on edit.
+# Never fails the agent's turn (exit 0) — formatting is best-effort.
+set -euo pipefail
+
+input=$(cat)
+file=$(echo "$input" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get("tool_input", {}).get("file_path", ""))
+except Exception:
+    print("")
+' 2>/dev/null || true)
+
+case "$file" in
+  *.py)
+    if command -v ruff >/dev/null 2>&1; then
+      ruff check --fix "$file" >/dev/null 2>&1 || true
+      ruff format "$file" >/dev/null 2>&1 || true
+    fi
+    ;;
+esac
+
+exit 0

mcphound-0.1.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(rtk git *)",
+      "Bash(rtk ls *)"
+    ]
+  }
+}

mcphound-0.1.0/.claude/skills/incident-teardown/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: incident-teardown
+description: Use when a new MCP/agent-supply-chain attack or worm is disclosed (e.g. another Miasma/ClawHavoc). Produces the analysis-to-rule pipeline.
+---
+
+# Turning a disclosed attack into detections (fast)
+
+Speed matters — being first with a public analysis is the distribution playbook.
+
+1. **Collect primary sources**: the disclosing lab's blog (Invariant, Koi, Snyk, OX, UpGuard, Antiy CERT), CVE if assigned, sample configs/IOCs, OWASP/CSA analysis. Save URLs.
+2. **Extract the kill chain** into `docs/incidents/<date>-<name>.md`: initial access (registry entry? repo PR?), poisoning technique (which field, what markers), action (credential theft? config rewrite?), persistence.
+3. **Write detection rule(s)** using the `rule-authoring` skill:
+   - Static: match the IOC/pattern (e.g. specific config-rewrite path, hidden comment style, endpoint).
+   - Dynamic: what egress/tool-shadowing behavior did it exhibit? Add a sandbox assertion.
+4. **Build fixtures from the real IOCs** (sanitized, canary-marked) — real attacks make the best regression tests.
+5. **Publish**: short public teardown on the site/blog, X/LinkedIn thread, HN if novel, responsible-disclosure email to affected registries. Include "detected by mcpvet rule MCP-xxx" in the post with a link to the server's reputation page.
+6. Bump version per `release-checklist` if the rule is time-critical (patch release).

mcphound-0.1.0/.claude/skills/release/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: release
+description: Use before cutting a release of mcpvet or publishing the GitHub Action. Full pre-flight checklist.
+---
+
+# Release checklist
+
+1. `uv run pytest -q` — all green.
+2. `uv run ruff check .` — clean.
+3. `uv run mcpvet scan .mcp.json opencode.jsonc --fail-on high` — scanner passes over the repo's own agent configs (dogfood, same command as `make scan-self`). Zero unacknowledged high/critical findings.
+4. Scan the 5 most-downloaded community MCP servers as a canary batch; compare scores to previous release — document any score changes in CHANGELOG.
+5. SARIF output verified to load in GitHub code scanning (test on a throwaway branch).
+6. Version bumped in `pyproject.toml`; CHANGELOG entry with Conventional Commits; git tag `vX.Y.Z`.
+7. GitHub Action's `action.yml` references the new version (or `@v1` major tag moved intentionally).
+8. Release notes include: new rule ids, OWASP mapping changes, any breaking output-format changes.
+9. **Human runs the publish commands** — the agent prepares everything but never executes `uv publish`, `git push --tags`, or marketplace publish without approval.

mcphound-0.1.0/.claude/skills/rule-authoring/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: rule-authoring
+description: Use when adding a new detection rule to mcpvet (static or dynamic). Covers the YAML rule schema, fixtures, OWASP mapping, and tests.
+---
+
+# Authoring a new mcpvet detection rule
+
+Every rule MUST land with four artifacts: YAML rule, malicious fixture, benign fixture, pytest.
+
+## 1. Rule file: `src/mcpvet/rules/<id>.yaml`
+
+```yaml
+id: MCP-STATIC-0xx        # next unused number — check src/mcpvet/rules/ before picking one
+title: Dangerous install command (curl pipe shell)
+owasp: LLM01            # LLMxx = OWASP LLM Top10, ASTxx = OWASP Agentic Top10
+phase: static           # static | dynamic
+severity: high           # low | medium | high | critical
+confidence: high
+description: >
+  MCP server launch commands that pipe a remote script into a shell
+  execute attacker-controlled code at startup.
+detect:
+  target: command          # which field of the server config to inspect: command | url | env | raw
+  pattern: '(curl|wget)\s+[^\s|]+\s*\|\s*(sh|bash|zsh)'
+recommendation: Vendor the script or use a pinned package from a registry.
+references:
+  - https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks
+```
+
+Most detections are a regex against `target` text — that's "rules are data, not code." One
+exception exists: **typosquat checks need edit-distance, not a regex**, so they use a second
+`detect` shape with dedicated engine support in `rules/engine.py`:
+
+```yaml
+detect:
+  type: typosquat
+  target: command                        # only "command" is supported today
+  reference_list: known_servers.yaml     # YAML list under src/mcpvet/rules/data/
+  max_distance: 2                        # flag names within N edits of a reference name,
+                                          # but not an exact match (exact = it IS that package)
+```
+
+A third exists for checks that need live registry data — **npm provenance**:
+
+```yaml
+network: true             # REQUIRED alongside this detect.type — see below
+detect:
+  type: npm_provenance
+  target: command          # only npx-launched packages are checked
+```
+
+Any rule whose `detect` needs the network (not just this one) MUST set the top-level `network: true`
+field. `cli.py`'s `_collect()` filters those rules out unless `--deep` is passed — per
+GOVERNANCE.md, network-dependent checks must be marked and kept separable from the default free
+scan. The actual HTTP call must live in its own small function (see `_fetch_npm_metadata` in
+`rules/engine.py`) so tests can `monkeypatch` it instead of hitting the real registry — `pytest`
+must never make live network calls.
+
+Don't add a fourth `detect.type` casually — every new type is engine code, not a community-PR-able
+YAML rule. Prefer extending the regex path unless the check is genuinely not regex-expressible.
+
+## 2. Fixtures
+- Malicious: `tests/fixtures/static/<id>/mcp-malicious.json` — contains the triggering pattern AND the canary string `MCPVET-FIXTURE-CANARY` somewhere in the file.
+- Benign: `tests/fixtures/static/<id>/mcp-benign.json` — the closest legitimate config (false-positive guard). For install-command rules, a pinned `npx -y pkg@1.2.3`.
+
+## 3. Test: add cases to `tests/test_rules.py`
+- Use the `_finding_ids(fixture, rule_dir)` helper already in that file.
+- Assert the malicious fixture fires with the exact rule id.
+- Assert the benign fixture does NOT fire the rule.
+- The existing `test_every_finding_is_owasp_mapped` / `test_sarif_serializes` cases cover OWASP-code presence and SARIF validity for all rules automatically — no per-rule duplication needed.
+
+## 4. Before you commit
+- `uv run pytest tests/test_rules.py -q` passes.
+- Run `uv run mcpvet scan tests/fixtures/static/<id>/mcp-malicious.json --json` and eyeball the output.
+- No separate rule index to update — `rules/loader.py` globs every `*.yaml` in `src/mcpvet/rules/` automatically.
+- Never run the malicious fixture's server — static rules never execute anything. Dynamic rules only execute inside the Docker sandbox runner.
+
+## Rule numbering convention
+- `MCP-STATIC-0xx` static config/package checks
+- `MCP-DYNAMIC-0xx` sandbox runtime checks
+- `SKILL-0xx` agent-skill/tool-description language checks

mcphound-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# Copy to .env (gitignored). Never commit real values.
+
+# Read-only Postgres DSN for the postgres MCP server / local dev DB.
+# Create a ROLE with SELECT only, on the DEV database — never production.
+MCPVET_DATABASE_URL_RO=postgresql://mcpvet_ro:password@localhost:5432/mcpvet_dev
+
+# Optional: local LLM deep-analysis mode (free tier never needs these)
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+# Local model option:
+# OLLAMA_HOST=http://localhost:11434
+
+# GitHub token for the GitHub MCP (fine-grained, read + issues/PRs scope only, no admin)
+GITHUB_PERSONAL_ACCESS_TOKEN=
+
+# Optional research MCPs (add to ~/.claude.json or global opencode config if wanted)
+# EXA_API_KEY=
+# FIRECRAWL_API_KEY=

mcphound-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: uv sync --all-extras
+      - name: Lint
+        run: uv run ruff check .
+      - name: Tests
+        run: uv run pytest -q
+      - name: SARIF output smoke test
+        run: uv run mcpvet scan tests/fixtures --sarif -o mcpvet-results.sarif || true
+      - name: Upload SARIF (works once findings exist)
+        if: hashFiles('mcpvet-results.sarif') != ''
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: mcpvet-results.sarif
+
+  self-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Dogfood the scanner on our own agent configs
+        run: |
+          if [ -f pyproject.toml ]; then
+            pip install uv -q
+            uv sync
+            uv run mcpvet scan .mcp.json opencode.jsonc --fail-on high --json
+          else
+            echo "mcpvet not built yet"
+          fi
+
+  nightly-registry-scan:
+    # Phase 2+ : start as a weekly cron, promote to nightly when the poller exists.
+    if: ${{ false }}  # flip on after Phase 2 ships
+    runs-on: ubuntu-latest
+    schedule:
+      - cron: "0 18 * * *"  # daily ~04:30 Adelaide time
+    steps:
+      - uses: actions/checkout@v4
+      - run: uv sync
+      - run: uv run mcpvet registry-poll --config config/registry.yaml

mcphound-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.env
+.venv/
+venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.mcp-scan*
+scan-results/
+sandbox/work/
+.DS_Store
+node_modules/
+.claude/settings.json
+

mcphound-0.1.0/.mcp.json

@@ -0,0 +1,21 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@1.0.0"]
+    },
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    },
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@0.0.40"]
+    }
+  }
+}

mcphound-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9  # pin to a real release
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.0  # pin
+    hooks:
+      - id: gitleaks
+
+  - repo: local
+    hooks:
+      - id: mcpvet-self-scan
+        name: mcpvet self-scan of agent MCP configs
+        language: system
+        entry: scripts/self-scan.sh
+        files: '(\.mcp\.json|opencode\.jsonc?|\.claude/settings\.json)$'
+        pass_filenames: false

mcphound-0.1.0/.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

mcphound-0.1.0/.serena/project.local.yml

@@ -0,0 +1,5 @@
+# This file allows you to locally override settings in project.yml for development purposes.
+#
+# Use the same keys as in project.yml here. Any setting you specify will override the corresponding
+# setting in project.yml, allowing you to customise the configuration for your local development environment
+# without affecting the project configuration in project.yml (which is intended to be versioned).

mcphound-0.1.0/.serena/project.yml

@@ -0,0 +1,169 @@
+# the name by which the project can be referenced within Serena/when chatting with the LLM.
+project_name: "MCP-Security-Tool"
+
+# list of language servers to start when using the LSP backend; choose from:
+#   ada                    al                     angular                ansible                bash
+#   bsl                    clojure                cpp                    cpp_ccls               crystal
+#   csharp                 csharp_omnisharp       cue                    dart                   deno
+#   elixir                 elm                    erlang                 fortran                fsharp
+#   gdscript               gleam                  go                     groovy                 haskell
+#   haxe                   hlsl                   html                   java                   json
+#   julia                  kotlin                 latex                  lean4                  lua
+#   luau                   markdown               matlab                 msl                    nextflow
+#   nix                    ocaml                  pascal                 perl                   php
+#   php_phpactor           php_phpantom           powershell             python                 python_basedpyright
+#   python_jedi            python_pyrefly         python_ty              qml                    r
+#   rego                   ruby                   ruby_solargraph        rust                   scala
+#   scss                   solidity               svelte                 swift                  systemverilog
+#   terraform              toml                   typescript             typescript_vts         vue
+#   wolfram                yaml                   zig
+#   (This list may be outdated; generated with scripts/print_language_list.py;
+#   For the current list, see values of the LanguageServerId enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py)
+# For some languages, there are several alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For Deno projects, use deno (serves the same .ts/.js files as typescript; requires the deno CLI on PATH)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some language servers require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple language servers, the first language server that supports a given file will be used for that file.
+# The first language server is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+language_servers:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# optional shell command to run before the language backend (LSP or JetBrains) is initialised.
+# the command runs in the project root directory and is only executed if the project is trusted
+# (see trusted_project_path_patterns in the global configuration).
+# serena waits for the command to exit: a non-zero exit code is logged as an error but does not
+# abort activation. a per-project timeout (activation_command_timeout, default 180s) is the safety
+# backstop for non-terminating commands; on expiry the process is killed and activation continues.
+# example: activation_command: "npx nx run-many -t build"
+activation_command:
+
+# maximum time in seconds to wait for activation_command to complete before killing it (default 180s).
+# must be a positive number.
+activation_command_timeout: 180.0
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# The settings are considered only if the project is trusted (see global configuration to define trusted projects).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#language-server-specific-settings
+ls_specific_settings: {}
+
+# list of workspace folder paths (LSP backend only).
+# These folders will be used to build up Serena's symbol index.
+# Paths must be within the project root and should thus be relative to the project root.
+# Furthermore, the paths should not be filtered by ignore settings.
+# Default setting: The entire project root folder (".") is considered.
+# In (large) monorepos, this can be used to index only subfolders of the project root, e.g.
+#   ls_workspace_folders:
+#     - "./subproject1"
+#     - "./subproject2"
+ls_workspace_folders:
+- "."
+
+# list of additional workspace folder paths for cross-package reference support.
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries, but these folders are not indexed by Serena,
+# i.e. the respective symbols will not be found using Serena's symbol search tools.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+ls_additional_workspace_folders: []
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Important: quote patterns that start with `*`, otherwise YAML treats them as aliases.
+# Example:
+#   ignored_paths:
+#     - "examples/**"
+#     - ".worktrees/**"
+#     - "**/bin/**"
+#     - "**/obj/**"
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

mcphound-0.1.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to mcpvet are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project doesn't use
+SemVer strictly pre-1.0 (see ROADMAP.md).
+
+## [0.1.0] — 2026-08-29
+
+First public release. Static-only scanning; nothing here ever executes an
+MCP server.
+
+### What v0.1 does
+
+mcpvet discovers the MCP servers configured in your AI coding clients
+(Claude Desktop/Code, Cursor, Windsurf, Gemini CLI, OpenCode — both `.json`
+and JSON5-style `.jsonc`) and runs a set of static detection rules against
+each server's launch command, environment, and (optionally) npm registry
+metadata. Every finding maps to an OWASP LLM Top 10 or Agentic/MCP Top 10
+code. Output is human-readable by default, or `--json` / `--sarif` for
+tooling and GitHub code scanning, with `--fail-on` exit codes for CI.
+
+Install and run (published on PyPI as `mcphound`; `mcpvet` is kept as a
+back-compat command alias):
+
+```bash
+uvx mcphound scan
+```
+
+### Detection rules
+
+| ID | Title | Severity | OWASP |
+|---|---|---|---|
+| `MCP-STATIC-001` | Hardcoded secret in MCP server environment | high | LLM02 |
+| `MCP-STATIC-002` | Remote code download-and-execute in launch command (curl/wget \| sh) | critical | AST04 |
+| `MCP-STATIC-003` | Over-broad host/filesystem permissions in launch command | high | LLM08 |
+| `MCP-STATIC-004` | Unpinned or `@latest` package version in launch command | medium | AST04 |
+| `MCP-STATIC-005` | Tool-description injection markers (hidden HTML comments, zero-width Unicode, exfiltration-imperative phrasing) | critical | LLM01 |
+| `MCP-STATIC-006` | Typosquat of a known MCP server package name (Levenshtein distance) | high | AST04 |
+| `MCP-STATIC-007` | npm package has no discoverable source repository — network-dependent, opt-in via `--deep` | medium | AST04 |
+
+Every rule ships with all four required artifacts: the YAML rule, a
+malicious fixture, a benign fixture (false-positive guard), and a pytest.
+
+### Not yet (post-v0.1)
+
+- **Dynamic analysis** — Docker sandbox runner, egress-proxy network,
+  runtime rug-pull / description-drift detection. Planned for v1.5
+  (ROADMAP.md).
+- **Reputation site + API** — registry poller, per-server score pages,
+  leaderboard, rate-limited API. Planned for v1.0-beta.
+- **GitHub Action** — `mcp-policy.yaml` allowlist enforcement on PRs.
+  Planned for v1.0.
+
+### Added
+- Config discovery for Claude Desktop/Code, Cursor, Windsurf, Gemini CLI,
+  and OpenCode (`.json` and `.jsonc`, including trailing-comma JSON5 style).
+- `mcpvet inspect` — lists configured servers without executing them.
+- `mcpvet scan` — runs detection rules; `--json`, `--sarif`, `--fail-on`,
+  `-o/--output`, and `--deep` (opt-in network-dependent checks).
+- SARIF 2.1.0 output for GitHub code scanning.
+- Seven static detection rules — see table above.
+
+### Fixed
+- `_target_text`'s raw-JSON dump used `ensure_ascii=True`, silently hex-escaping
+  zero-width Unicode characters before MCP-STATIC-005 could see them.
+- `.jsonc` configs with a trailing comma before `}`/`]` (valid JSON5, common
+  in hand-edited `opencode.jsonc`) failed to parse; the repo's own
+  `opencode.jsonc` hit this.
+- SARIF `informationUri` pointed at a placeholder org/repo instead of the
+  real repository.
+- SARIF `artifactLocation.uri` was a Windows-style path with a non-URI
+  `" :: server"` suffix appended, which is not a valid URI.
+- SARIF `security-severity` was set to the severity word (`"high"`,
+  `"critical"`) instead of a numeric CVSS-like score; GitHub's code-scanning
+  ingestion rejects non-numeric values outright, so every SARIF upload would
+  have silently failed until this fix. Verified with a live upload to
+  GitHub's code-scanning API during release prep.
+
+### Known limitations
+- Package provenance (`MCP-STATIC-007`) only checks for a missing npm
+  `repository` field. Postinstall-script inspection and registry-age checks
+  (both named in ROADMAP.md's W4) are not implemented yet.
+- The typosquat reference list (`src/mcpvet/rules/data/known_servers.yaml`)
+  is a small hand-curated seed, not the official registry — Phase 2's
+  registry poller will supersede it.
+- PyPI packages (`uvx`-launched) aren't covered by MCP-STATIC-007 yet, only
+  npm/`npx`.
+- The PyPI *distribution name* is `mcphound`, not `mcpvet`. `mcpvet` on
+  PyPI belongs to an unrelated package; `mcp-vet` was rejected by PyPI as
+  "too similar to an existing project" (its name-similarity check strips
+  hyphens/underscores before comparing, so `mcp-vet` collided with
+  `mcpvet`); `mcpaudit` belongs to a different, actively-maintained MCP
+  security scanner. The importable module and CLI command are still
+  `mcpvet` — `pip install mcphound` installs both the `mcphound` and
+  `mcpvet` commands (same entry point), so `uvx mcphound scan` and
+  `uvx --from mcphound mcpvet scan` both work.
+
+### Dogfood / canary results
+- `mcpvet scan .mcp.json opencode.jsonc --fail-on high`: zero findings against
+  this repo's own agent configs.
+- `mcpvet scan --deep` against 5 well-known real MCP packages
+  (`@modelcontextprotocol/server-filesystem`, `-postgres`, `-everything`,
+  `@upstash/context7-mcp`, `@playwright/mcp`): one genuine finding —
+  `@modelcontextprotocol/server-postgres` has no `repository` field in its
+  npm metadata (confirmed against the live registry; the package is also
+  marked deprecated on npm, unrelated to this rule but worth knowing).
+  No previous release to diff against — this is the baseline.

mcphound-0.1.0/CLAUDE.md

@@ -0,0 +1,33 @@
+# mcpvet — project rules for AI coding agents
+
+> This file is read by Claude Code automatically, and by OpenCode via `instructions: ["./CLAUDE.md"]` in opencode.json. Keep it short — long procedures go in `.claude/skills/` and `.opencode/skills/`.
+
+## What we're building
+Independent security reputation + policy-enforcement layer for MCP servers and agent skills. Three surfaces:
+1. **Scanner CLI** (`mcpvet`): discovers MCP configs, static + dynamic analysis, SARIF/JSON output.
+2. **Reputation DB + site/API**: continuous scanning of the public MCP registry; per-server risk pages.
+3. **Enforcement**: GitHub Action + `mcp-policy.yaml` allowlist enforcement.
+
+## Stack
+- Python 3.12, Typer CLI, `mcp` official SDK, FastAPI (API), Postgres, Docker for dynamic sandboxing.
+- Website: Next.js (separate `site/` directory later).
+- Package management: `uv`. Tests: `pytest`. Lint/format: `ruff`.
+
+## Non-negotiable engineering rules
+- **Every detection rule ships with**: a YAML rule file, a malicious fixture, a benign fixture (false-positive guard), and a pytest. No rule without all four.
+- Rules are data, not code: add detections in `src/mcpvet/rules/*.yaml` using the rule schema (see skill `rule-authoring`).
+- Every finding maps to an OWASP code (LLM Top 10 / Agentic-MCP Top 10). No uncategorized findings.
+- Output must be deterministic in CI: `--json` and SARIF modes print no spinner/emojis.
+- Tests must pass before you say a task is done. Run `uv run pytest -q`.
+
+## SAFETY RULES (this project handles malware-adjacent code — read twice)
+- **Never execute a fixture MCP server on the host.** No `npx`, `uvx`, `node`, or `python` against anything in `tests/fixtures/` outside Docker. Dynamic analysis runs only via the sandbox runner (`docker` with a dedicated egress-proxy network, no mounted secrets, no host network).
+- Every malicious fixture contains the canary marker string `MCPVET-FIXTURE-CANARY` and is never referenced from `.mcp.json`, `opencode.json`, or any agent config.
+- Do not add new MCP servers to agent configs without: (a) pinned version, (b) a note in this commit message why it's needed, (c) running `mcpvet scan` (or mcp-scan as interim) against the changed config.
+- Never put secrets in config files; use environment variables only (`.env`, gitignored).
+- `git push`, package publishes, and `docker run` require explicit human approval — they are set to "ask" in both tools' permissions.
+
+## Conventions
+- Conventional commits (`feat:`, `fix:`, `rule:`, `docs:`). Rule additions use `rule: MCP-0xx ...`.
+- New public CLI flags need a docs update in the same PR.
+- When researching attacks, prefer primary sources (Invariant Labs disclosures, CSA papers, OWASP, CVEs); cite URLs in code comments or PR descriptions.