SpiderShield -- Security Scanner & Runtime Guard for MCP Servers

Security toolkit for MCP servers and AI agents. Static analysis, runtime policy enforcement, DLP, and audit logging -- from development to production.

What SpiderShield does

SpiderShield is a 5-subsystem security toolkit:

Install

pip install spidershield

Requires Python 3.11+. See SUPPORT.md for version compatibility and optional dependencies.

5-Minute Success Path

# 1. Install
pip install spidershield

# 2. Scan any MCP server
spidershield scan ./your-mcp-server

# 3. See what's wrong and how to fix it
spidershield rewrite ./your-mcp-server --dry-run

# 4. (Optional) Protect at runtime
spidershield proxy -- npx server-filesystem /tmp

For contributors:

git clone https://github.com/teehooai/spidershield && cd spidershield
make verify-oss   # One command: install + lint + type check + test + scan

Quick Start

Static scan (CI / development)

spidershield scan ./your-mcp-server

Example output:

            SpiderShield Scan Report
   modelcontextprotocol/servers/filesystem
+---------------------------------------------+
| Metric                | Value     |   Score |
|-----------------------+-----------+---------|
| License               | MIT       |      OK |
| Tools                 | 14        |      OK |
| Security              | 0 issues  | 10.0/10 |
| Descriptions          |           |  3.2/10 |
| Architecture          |           | 10.0/10 |
| Tests                 | Yes       |      OK |
|                       |           |         |
| Overall               | Rating: B |  7.6/10 |
| Improvement Potential |           |  2.4/10 |
+---------------------------------------------+

Runtime Guard SDK (production)

Enforce security policies on every tool call at runtime:

from spidershield import SpiderGuard, Decision

guard = SpiderGuard(policy="strict")

result = guard.check("read_file", {"path": "/etc/passwd"})
if result.decision == Decision.DENY:
    print(result.reason)       # "System file access blocked"
    print(result.suggestion)   # "Use application-level files instead"

Policy presets:

With audit logging and DLP:

guard = SpiderGuard(
    policy="strict",
    audit=True,              # Write audit trail to disk
    audit_dir="./logs",      # Custom audit directory
    dlp="redact",            # Scan outputs for PII/secrets, redact matches
)

# Pre-execution check
result = guard.check("query_db", {"sql": "SELECT * FROM users"})

# Post-execution DLP scan
clean_output = guard.after_check("query_db", raw_result)

With data flywheel (opt-in telemetry to local SQLite):

guard = SpiderGuard(policy="balanced", dataset=True)
# Every check() call feeds the local dataset for scoring calibration

MCP Proxy (transparent protection)

Wrap any MCP server with SpiderShield policy enforcement:

from spidershield import guard_mcp_server

# Proxy between agent and server, enforcing "balanced" policy
guard_mcp_server(
    ["npx", "server-filesystem", "/tmp"],
    policy="balanced",
    audit=True,
)

Or from the CLI:

spidershield proxy -- npx server-filesystem /tmp --policy balanced

Rewrite tool descriptions

SpiderShield can automatically rewrite tool descriptions to be action-oriented, with scenario triggers, parameter examples, and error guidance.

# Preview changes (no files modified)
spidershield rewrite ./your-mcp-server --dry-run

# Apply changes to source files
spidershield rewrite ./your-mcp-server

Before (score 2.9):

"Shows the working tree status"

After (score 9.6):

"Query the current state of the Git working directory and staging area.
 Use when the user wants to check which files are modified, staged, or
 untracked before committing."

The rewriter works offline using templates (zero cost). Set ANTHROPIC_API_KEY for higher-quality LLM-powered rewrites.

Scan results across the MCP ecosystem

Full report: MCP-SECURITY-REPORT.md | Raw data: CURATION-REPORT.md

Try it on an example

The repo includes example MCP servers for instant demo:

git clone https://github.com/teehooai/spidershield
cd spidershield

spidershield scan examples/insecure-server   # Rating: D (3.3/10)
spidershield scan examples/secure-server     # Rating: D (4.7/10)

What SpiderShield checks

Static Scanner

Security (weighted 35%)

• Path traversal
• Command injection / dangerous eval
• SQL injection (Python + TypeScript)
• SSRF (unrestricted network access)
• Hardcoded credentials
• Unsafe deserialization (pickle, yaml.load)
• Prototype pollution (TypeScript)

Descriptions (weighted 35%)

• Action verb starts ("List", "Create", "Execute")
• Scenario triggers ("Use when the user wants to...")
• Parameter documentation
• Parameter examples
• Error handling guidance
• Disambiguation between similar tools
• Length (too short = vague, too long = noisy)

Architecture (weighted 30%)

• Test coverage (gradual: count-based)
• Error handling (gradual: coverage-based)
• README quality (gradual: length-based)
• Type annotations
• Dependency management
• Environment configuration

License (pass/fail gate, not weighted)

• MIT, Apache-2.0, BSD = OK
• GPL, AGPL = warning
• Missing = fail

Agent Security Checker

Scan AI agent installations for security misconfigurations and malicious skills.

spidershield agent-check ~/.openclaw

What it checks:

• 10 configuration security checks (auth, sandbox, SSRF, permissions, etc.)
• 20+ malicious skill patterns (reverse shells, credential theft, prompt injection)
• Toxic flow detection -- flags skills that can read sensitive data AND send it externally
• Typosquat detection for skill names
• Excessive permission requests

Advanced options:

# Verify skill integrity (rug pull detection)
spidershield agent-check --verify

# Only approved skills allowed
spidershield agent-check --allowlist approved.json

# Strict mode: fail on any finding
spidershield agent-check --policy strict

# Ignore specific rules
spidershield agent-check --ignore TS-W001 --ignore typosquat

# Auto-fix configuration issues
spidershield agent-check --fix

# SARIF output for GitHub Code Scanning
spidershield agent-check --format sarif > results.sarif

Skill pinning (rug pull protection):

spidershield agent-pin add ~/.openclaw/skills/my-skill/SKILL.md
spidershield agent-pin add-all
spidershield agent-pin verify    # detect tampered skills
spidershield agent-pin list

46 standardized issue codes across 4 categories:

Rating scale (SpiderRating)

Formula (MCP servers): description × 0.38 + security × 0.34 + metadata × 0.28 Formula (Skills): description × 0.45 + security × 0.35 + metadata × 0.20

JSON output

spidershield scan ./server --format json
spidershield scan ./server --format json -o report.json

GitHub Action

Add SpiderShield to your CI pipeline. Available on the GitHub Marketplace.

Basic usage

# .github/workflows/security.yml
name: SpiderShield Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: teehooai/spidershield@v1
        with:
          target: '.'
          fail-below: '6.0'

With outputs

- uses: actions/checkout@v4
- id: scan
  uses: teehooai/spidershield@v1
  with:
    target: '.'
    fail-below: '6.0'
    format: 'json'
- run: |
    echo "Score: ${{ steps.scan.outputs.score }}"
    echo "Rating: ${{ steps.scan.outputs.rating }}"

Action inputs

Action outputs

Commands

Threat model

SpiderShield provides both static analysis and runtime policy enforcement.

What it catches:

• Ambiguous tool definitions that lead to agent misuse
• Missing side-effect declarations (writes, deletes, network calls)
• Unsafe permission patterns (unbounded file access, unrestricted queries)
• Vague descriptions that give agents no operational boundaries
• Malicious agent skills (reverse shells, credential theft, prompt injection)
• Dangerous capability combinations (data exfiltration flows)
• Insecure agent configurations (no auth, disabled sandbox, open DM policy)
• Skill tampering (rug pull detection via content hashing)
• PII/secret leakage in tool outputs (DLP engine)
• Policy violations at runtime (Runtime Guard)

What it does NOT do:

• Network traffic monitoring
• Container-level sandboxing
• Access control management (it enforces policies, not manages identities)

License

MIT