spidershield 0.3.0__tar.gz

spidershield-0.3.0/.dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+tests
+docs
+examples
+*.md
+!README.md
+__pycache__
+*.pyc
+.ruff_cache
+.pytest_cache
+test-targets
+tmp_scan
+dist
+build
+*.egg-info

spidershield-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install ruff
+        run: pip install ruff>=0.4
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]" pytest-cov
+
+      - name: Run tests with coverage
+        run: pytest tests/ -v --cov=spidershield --cov-report=term-missing --cov-fail-under=60
+
+      - name: Verify CLI
+        run: spidershield --version

spidershield-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

spidershield-0.3.0/.github/workflows/scan.yml

@@ -0,0 +1,55 @@
+name: SpiderShield Scan
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'MCP server path or GitHub URL to scan'
+        required: true
+        type: string
+      format:
+        description: 'Output format'
+        required: false
+        default: 'table'
+        type: choice
+        options:
+          - table
+          - json
+
+  # Can be called from other repos
+  workflow_call:
+    inputs:
+      target:
+        description: 'MCP server path to scan'
+        required: true
+        type: string
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install SpiderShield
+        run: pip install -e .
+
+      - name: Run scan
+        run: |
+          spidershield scan "${{ inputs.target }}" --format "${{ inputs.format || 'table' }}"
+
+      - name: Run scan (JSON artifact)
+        if: always()
+        run: |
+          spidershield scan "${{ inputs.target }}" --format json -o scan-report.json || true
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: spidershield-report
+          path: scan-report.json

spidershield-0.3.0/.github/workflows/weekly-scan.yml

@@ -0,0 +1,66 @@
+name: Weekly MCP Server Scan
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday at 09:00 UTC
+  workflow_dispatch:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install SpiderShield
+        run: pip install -e .
+
+      - name: Scan official MCP servers
+        run: |
+          mkdir -p scan-results
+          TARGETS=(
+            "https://github.com/modelcontextprotocol/servers"
+            "https://github.com/supabase-community/supabase-mcp"
+            "https://github.com/neondatabase/mcp-server-neon"
+            "https://github.com/korotovsky/slack-mcp-server"
+          )
+          for target in "${TARGETS[@]}"; do
+            name=$(basename "$target")
+            echo "Scanning: $name"
+            spidershield scan "$target" --format json -o "scan-results/${name}.json" || true
+          done
+
+      - name: Generate summary
+        run: |
+          python -c "
+          import json, glob, sys
+          results = []
+          for f in sorted(glob.glob('scan-results/*.json')):
+              try:
+                  data = json.load(open(f))
+                  results.append({
+                      'server': data.get('target', f),
+                      'overall': data.get('overall_score', 0),
+                      'security': data.get('security_score', 0),
+                      'descriptions': data.get('description_score', 0),
+                      'rating': data.get('rating', '?'),
+                      'tools': data.get('tool_count', 0),
+                  })
+              except Exception as e:
+                  print(f'Error reading {f}: {e}', file=sys.stderr)
+          json.dump({'scan_date': '$(date -I)', 'servers': results}, open('scan-results/summary.json', 'w'), indent=2)
+          print(f'Scanned {len(results)} servers')
+          for r in sorted(results, key=lambda x: -x['overall']):
+              print(f\"  {r['rating']:3s} {r['overall']:5.1f}  {r['server']}\")
+          "
+
+      - name: Upload scan results
+        uses: actions/upload-artifact@v4
+        with:
+          name: weekly-scan-${{ github.run_number }}
+          path: scan-results/
+          retention-days: 90

spidershield-0.3.0/.gitignore

@@ -0,0 +1,36 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+.env.*
+*.log
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+node_modules/
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+reports/
+
+# Test targets (cloned repos)
+test-targets/
+
+# Generated reports
+*.report.json
+fs-report.json
+
+# Internal docs (not published)
+docs/internal/
+docs/observations/

spidershield-0.3.0/CLAUDE.md

@@ -0,0 +1,123 @@
+# SpiderShield -- MCP Server Security Linter
+
+## Project Overview
+SpiderShield is a static analysis tool for MCP (Model Context Protocol) servers.
+It scans tool descriptions, security patterns, architecture quality, and licensing.
+Think "npm audit for MCP tools".
+
+## Architecture
+```
+src/spidershield/
+  cli.py              -- Click CLI (scan, rewrite, harden, eval)
+  models.py            -- Pydantic V2 models (ScanReport, SecurityIssue, etc.)
+  server.py            -- MCP server mode (scan_mcp_server tool)
+  spiderrating.py      -- SpiderRating format conversion (metadata, grades)
+  scanner/
+    runner.py          -- Orchestrates 4-stage scan pipeline
+    description_quality.py -- Tool description scoring (7 criteria)
+    security_scan.py   -- Static security pattern matching
+    architecture_check.py -- Code quality checks
+    license_check.py   -- License detection
+  agent/
+    scanner.py         -- Agent config security audit
+    skill_scanner.py   -- Skill malware/injection pattern matching (20 patterns)
+    toxic_flow.py      -- Dangerous capability combination detection (keyword + AST)
+    pinning.py         -- SHA-256 content pinning for rug-pull detection
+    allowlist.py       -- Approved-only skills enforcement
+    sarif.py           -- SARIF output for agent findings
+    models.py          -- Finding, SkillFinding, ScanResult, AuditFramework
+    issue_codes.py     -- TS-E/W/C/P code registry
+  rewriter/
+    runner.py          -- Template + LLM description rewriter
+    cache.py           -- SHA-256 keyed LLM rewrite cache
+    providers.py       -- Anthropic / OpenAI / Gemini providers
+  hardener/runner.py   -- Security fix suggestions
+  evaluator/runner.py  -- Tool selection accuracy testing
+```
+
+## Hard Constraints (G0 -- never violate)
+
+1. **No false sense of security**: Never give A rating to a server with undetected critical issues.
+   If uncertain, score conservatively.
+2. **No destructive modifications**: `rewrite` and `harden` must never break working code.
+   Always preserve original semantics.
+3. **Reproducible results**: Same input must produce identical scan output.
+   No randomness, no network-dependent scoring.
+
+## Evolution Mode Protocol
+
+SpiderShield uses evidence-driven evolution (see docs/internal/001-audit-quality-evolution-2026-03-08.md).
+
+### Per-Change Cycle
+1. **Evidence first**: Before changing a scanner, document the false positive/negative that motivates the change
+2. **Measure before/after**: Run `spidershield scan` on test-targets/ before and after changes
+3. **Update observation doc**: Record what changed and why in docs/internal/
+
+### Scanner Quality Rules
+- Security scanner: Minimize false positives. A false positive erodes trust more than a missed issue.
+- Description scorer: Score must correlate with actual LLM tool selection success.
+- Architecture checker: Gradual scoring preferred over binary pass/fail.
+- Overall score: SpiderRating formula `descriptions*0.35 + security_adjusted*0.35 + architecture*0.30`.
+- Architecture bonus: `min(3.0, arch_score * 0.3)` folds into security_adjusted.
+- Grade scale: F/D/C/B/A (thresholds: 3.0/5.0/7.0/8.5).
+- Hard constraints: critical→F, no_tools→F, license_banned→D cap.
+
+### Scoring Calibration
+- A server with no quality signals in descriptions should score 0-2/10, not 3-4/10
+- A server with all quality signals should score 8-10/10
+- Security score 10.0 means zero issues found, not "secure" (we can't prove absence)
+
+## PR Campaign Quality Gates (G1 -- must pass before submitting any PR)
+
+Before submitting a PR to any external MCP repo, ALL 5 gates must pass:
+
+1. **Real problem**: The original description has a concrete, demonstrable issue
+   (ambiguous scope, missing side-effects, misleading trigger). Not "could be better".
+2. **Narrower and more precise**: The rewrite must be semantically narrower or more
+   specific than the original. Never broaden scope.
+3. **Preserves command semantics**: The rewrite must not change what the tool actually does.
+   `git fetch` fetches from git remotes, not URLs. `git add` stages files, not "appends".
+4. **One-sentence justification**: If you cannot explain the change in one sentence,
+   the change is not high-confidence enough for an automated PR.
+5. **Tests must pass**: If the target repo has CI, the PR must not break it.
+   Description-only changes should never break tests.
+
+### PR Strategy by Repo Type
+
+| Type | Stars | Action | Example |
+|------|-------|--------|---------|
+| A: Small active | < 1k | Direct PR | HenkDz/postgresql-mcp-server |
+| B: Large/strict | > 1k | Issue first, PR if invited | modelcontextprotocol/servers |
+| C: Corporate | any | Issue only | playwright-mcp, github-mcp |
+
+### PR Anti-Patterns (learned from rejected PRs)
+
+- **Tautological triggers**: "Opens a file. Use when user wants to open a file." (rejected by ida-pro-mcp #277)
+- **Semantic mismatches**: git "fetch" matched to URL "fetch", git "add" matched to "append" (flagged on git-mcp-server #42)
+- **Template boilerplate**: Generic error guidance unrelated to the tool's domain
+- **Too many changes**: Large PRs scare maintainers. Keep to 1-5 tool descriptions per PR.
+
+## Development Standards
+
+- Python 3.11+ with type hints on all new functions
+- Use Pydantic V2 for data models
+- Rich console for CLI output
+- Tests in tests/ directory
+- No unnecessary dependencies
+
+## Key Files for Common Tasks
+
+| Task | Files |
+|------|-------|
+| Add security pattern | scanner/security_scan.py (DANGEROUS_PATTERNS dict) |
+| Add description criterion | scanner/description_quality.py + models.py (ToolDescriptionScore) |
+| Change scoring weights | scanner/description_quality.py (line ~90-108) |
+| Add tool extraction pattern | scanner/description_quality.py (_extract_tools) |
+| Change report output | scanner/runner.py (_print_table) |
+| SpiderRating conversion (MCP) | spiderrating.py (convert, metadata scoring) |
+| SpiderRating conversion (Skill) | spiderrating.py (convert_skill, score_skill_description) |
+| Agent security patterns | agent/skill_scanner.py (MALICIOUS_PATTERNS list) |
+| Agent config checks | agent/scanner.py |
+| Toxic flow detection | agent/toxic_flow.py (keyword + AST) |
+| LLM rewrite cache | rewriter/cache.py (~/.spidershield/rewrite-cache/) |
+| Add CLI command | cli.py |

spidershield-0.3.0/CURATION-REPORT.md

@@ -0,0 +1,68 @@
+# SpiderShield Curation Report
+
+Batch scan of top MCP servers. Generated by `spidershield scan`.
+
+## Summary
+
+| Server | Tools | Security | Description | Arch | Overall | Rating | Rewrite Gain |
+|--------|-------|----------|-------------|------|---------|--------|-------------|
+| filesystem (official) | 14 | 10.0 | 3.2 | 10.0 | 7.6 | B | +4.8 |
+| memory (official) | 9 | 10.0 | 2.3 | 10.0 | 7.3 | B | - |
+| git (official) | 12 | 10.0 | 2.4 | 10.0 | 7.3 | B | +6.6 |
+| fetch (official) | 1 | 9.0 | 3.5 | 10.0 | 7.3 | B | - |
+| time (official) | 0 | 10.0 | 5.0 | 10.0 | 8.2 | A | - |
+| everything (python-sdk) | 13 | 10.0 | 2.8 | 7.0 | 6.7 | B | - |
+| supabase (community) | 30 | 9.0 | 2.3 | 8.0 | 6.4 | B | +5.6 |
+
+**Totals:** 7 servers, 79 tools scanned
+
+## Key Findings
+
+### 1. Description quality is universally poor
+- Average description score: **3.1/10**
+- 0% of tools have scenario triggers ("Use when...")
+- 0% of tools have parameter examples
+- <5% have error guidance
+- This confirms the Neon finding: tool descriptions are the #1 bottleneck for agent tool selection
+
+### 2. Rewriting delivers massive gains
+
+**Template-based (zero cost):**
+- filesystem: 3.7 -> 8.5 (+4.8 points)
+- git: 2.9 -> 9.5 (+6.6 points)
+- supabase: 3.4 -> 9.0 (+5.6 points)
+- Average improvement: +5.7 points
+
+**Claude API (higher quality):**
+- filesystem: 3.7 -> 9.6 (+5.9 points)
+- memory: 3.4 -> 9.4 (+6.0 points)
+- git: 2.9 -> 8.6 (+5.7 points)
+- fetch: 3.5 -> 9.6 (+6.1 points)
+- **Average improvement: +5.9 points with Claude API**
+
+### 3. Security is generally solid
+- Average security score: **9.7/10**
+- Official servers score 10.0 (clean)
+- Community servers have minor issues (SSRF in fetch, credential handling)
+- No critical vulnerabilities found in production servers
+
+### 4. Architecture quality varies
+- Official servers: strong (10.0) - tests, error handling, types
+- Community servers: moderate (7-8) - often missing tests
+
+## Top Curation Candidates
+
+Servers that would benefit most from SpiderShield curation (high tool count + low description quality):
+
+1. **supabase** - 30 tools, desc 2.3/10, improvement potential +5.6
+2. **filesystem** - 14 tools, desc 3.2/10, improvement potential +4.8
+3. **everything** - 13 tools, desc 2.8/10
+4. **git** - 12 tools, desc 2.4/10, improvement potential +6.6
+5. **memory** - 9 tools, desc 2.3/10
+
+## Not Yet Scanned (need pattern support)
+- Playwright MCP (compiled JS only, no source TS)
+- GitHub MCP (Go, not yet supported)
+- Context7 (clone failed)
+- AWS MCP servers
+- Desktop Commander

spidershield-0.3.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 spidershield
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN pip install --no-cache-dir .
+
+USER spidershield
+
+HEALTHCHECK --interval=30s --timeout=5s CMD spidershield --version || exit 1
+
+CMD ["spidershield-server"]

spidershield-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TeeShield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spidershield-0.3.0/MCP-SECURITY-REPORT.md

@@ -0,0 +1,132 @@
+# The MCP Tool Security Report
+
+**We scanned 79 MCP tools across 7 production servers. Here's what we found.**
+
+## What we scanned
+
+We ran [SpiderShield](https://github.com/teehooai/spidershield) against the most widely used MCP servers in the ecosystem:
+
+| Server | Type | Tools |
+|--------|------|-------|
+| filesystem | Official | 14 |
+| git | Official | 12 |
+| memory | Official | 9 |
+| fetch | Official | 1 |
+| time | Official | 0 |
+| everything | SDK example | 13 |
+| supabase | Community | 30 |
+
+Each tool was scored on four dimensions: description quality, security patterns, architecture, and license compliance.
+
+## The headline number
+
+**Average description quality: 3.1 out of 10.**
+
+This matters because AI agents choose which tool to call based entirely on the description text. A vague description gives the agent no boundaries.
+
+## What's missing from tool descriptions
+
+We checked every tool description for five critical attributes:
+
+| Attribute | Present | Missing |
+|-----------|---------|---------|
+| Scenario triggers ("Use when...") | 0% | 100% |
+| Parameter examples | 0% | 100% |
+| Error handling guidance | <5% | >95% |
+| Disambiguation vs similar tools | <10% | >90% |
+| Adequate length (>50 chars) | ~40% | ~60% |
+
+Not a single tool across all 79 had a scenario trigger. This means agents have zero guidance on *when* to pick one tool over another.
+
+## Why this matters for agents
+
+Consider the official Git MCP server. It has 12 tools, including three that show diffs:
+
+```
+git_diff_unstaged: "Shows changes in the working directory that are not yet staged"
+git_diff_staged:   "Shows changes that are staged for commit"
+git_diff:          "Shows differences between branches or commits"
+```
+
+An agent seeing these descriptions has to guess which one to call. There's no "Use when..." trigger, no examples, no disambiguation. The result: agents frequently call the wrong diff tool, waste context tokens, and produce incorrect results.
+
+## What a good description looks like
+
+Here's the same tool after SpiderShield rewrites it:
+
+**Before (score 2.9):**
+```
+"Shows the working tree status"
+```
+
+**After (score 9.6):**
+```
+"Show the working tree status including modified, staged, and untracked files.
+Use when the user wants to see the current state of the repository before
+committing or staging changes. Unlike git_diff tools that show content changes,
+this only shows which files have changed."
+```
+
+Three things changed:
+1. **Scenario trigger** -- tells the agent *when* to use this tool
+2. **What it returns** -- the agent knows what to expect
+3. **Disambiguation** -- prevents confusion with similar tools
+
+## The rewrite impact
+
+We rewrote all 79 tool descriptions using SpiderShield's template engine (zero cost, no API calls):
+
+| Server | Before | After | Gain |
+|--------|--------|-------|------|
+| git | 2.9 | 9.5 | +6.6 |
+| supabase | 3.4 | 9.0 | +5.6 |
+| filesystem | 3.7 | 8.5 | +4.8 |
+| **Average** | **3.1** | **8.8** | **+5.7** |
+
+Using Claude API for higher-quality rewrites: average gain of **+5.9 points**.
+
+## Security is actually solid
+
+Good news: the code-level security of MCP servers is generally strong.
+
+| Server | Security Score |
+|--------|---------------|
+| filesystem | 10.0 |
+| git | 10.0 |
+| memory | 10.0 |
+| time | 10.0 |
+| everything | 10.0 |
+| fetch | 9.0 |
+| supabase | 9.0 |
+
+The security risk in MCP isn't in the code. It's in the descriptions. A tool with perfect code but a vague description like "access filesystem" is still dangerous -- because the agent doesn't know what boundaries to respect.
+
+## Top findings
+
+1. **Description quality is the #1 security bottleneck.** Not code vulnerabilities. Not architecture. The descriptions.
+
+2. **Zero tools have scenario triggers.** This is the single most impactful improvement. Adding "Use when..." costs nothing and immediately improves tool selection accuracy.
+
+3. **Disambiguation is almost nonexistent.** Servers with similar tools (git has 3 diff tools, filesystem has 3 read tools) provide no guidance on which to choose.
+
+4. **The fix is cheap.** Template-based rewriting is free and delivers +5.7 points on average. No API calls, no runtime overhead, no code changes.
+
+## What server authors should do
+
+1. **Add scenario triggers** to every tool description: "Use when the user wants to..."
+2. **Add parameter examples** with concrete values, not just type annotations
+3. **Disambiguate similar tools** explicitly: "Unlike X, this tool..."
+4. **Declare side effects**: "This tool writes to disk" / "This tool is read-only"
+5. **Run SpiderShield** before publishing: `pip install spidershield && spidershield scan .`
+
+## Methodology
+
+- Scanner: [SpiderShield v0.1.0](https://pypi.org/project/spidershield/)
+- Description scoring: 5 criteria weighted to 10-point scale (scenario triggers 3.0, disambiguation 2.0, parameter examples 2.0, error guidance 1.5, length 1.5)
+- Security scanning: pattern-based detection for path traversal, command injection, SSRF, credential exposure
+- All scans are static analysis -- no runtime execution, no network calls
+- Raw data: [batch-scan-results.json](batch-scan-results.json)
+
+---
+
+*This report was generated by [SpiderShield](https://github.com/teehooai/spidershield), a static security linter for MCP tools. Install: `pip install spidershield`*