Skip to content

teehooai/spidershield

BranchesTags

Repository files navigation

SpiderShield -- Security Scanner & Runtime Guard for MCP Servers

SpiderShield Verified PyPI License: MIT

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:

Subsystem Command / API What it does
Static Scanner spidershield scan Score tool descriptions, detect code vulnerabilities, rate overall quality (F/C/B/A/A+)
Agent Security spidershield agent-check 18 config checks, 15 malicious pattern detections, toxic flow analysis, rug pull detection
Runtime Guard SDK SpiderGuard(policy="balanced") Pre/post-execution policy enforcement for tool calls
MCP Proxy guard_mcp_server(cmd) Transparent security proxy between agent and MCP server
DLP Engine Built into Guard SDK Scan tool outputs for PII/secrets, redact or block

Install

pip install spidershield

Requires Python 3.11+.

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:

Preset Behavior
strict Deny by default, explicit allow list
balanced Block known-dangerous patterns, allow common operations
permissive Warn on suspicious patterns, allow most operations
Custom YAML Load your own policy file: SpiderGuard(policy="my-policy.yaml")

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

Server Tools Security Descriptions Overall Rating
filesystem 14 10.0 3.2 7.6 B
git 12 10.0 2.4 7.3 B
memory 9 10.0 2.3 7.3 B
fetch 1 9.0 3.5 7.3 B
supabase 30 9.0 2.3 6.4 B

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:

Code Category Example
TS-E001~E015 Error (malicious) Reverse shell, credential theft, prompt injection
TS-W001~W011 Warning (suspicious) Typosquat, toxic flow, unapproved skill
TS-C001~C018 Config No auth, sandbox disabled, SSRF enabled
TS-P001~P002 Pin Verified, tampered

Rating scale (SpiderRating)

Rating Score Meaning
A 8.5+ Production-ready
B 7.0+ Safe with minor suggestions
C 5.0+ Usable, needs improvements
D 3.0+ Significant issues
F <3.0 Unsafe, do not deploy

Formula: description * 0.35 + security_adjusted * 0.35 + architecture * 0.30

JSON output

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

GitHub Action

Add SpiderShield to your CI pipeline:

- uses: teehooai/spidershield@v0.3.0
  with:
    target: '.'
    fail-below: '6.0'

Commands

Command Description
spidershield scan <path> Scan and rate an MCP server
spidershield rewrite <path> Rewrite tool descriptions
spidershield harden <path> Suggest security hardening (advisory only)
spidershield eval <original> <improved> Compare tool selection accuracy
spidershield agent-check [dir] Scan an AI agent for security issues
spidershield agent-pin <cmd> Manage skill pins for rug pull detection
spidershield dataset stats View data flywheel statistics
spidershield dataset benchmark-add Add a benchmark entry
spidershield dataset benchmark-run Re-run benchmarks
spidershield dataset calibrate Run scoring calibration

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

About

Scan, rate, and harden MCP servers for AI agent safety

pypi.org/project/teeshield/

Topics

mcp ai-security mcp-server mcp-tools tool-safety

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

v0.3.0 — SpiderShield: unified static + runtime security Latest
Mar 10, 2026
+ 5 releases

Packages

 
 
 

Contributors

Languages