spidershield: Instructions file for Codex

AGENTS.md — SpiderShield

Security scanner and runtime guard for MCP servers. Static analysis, policy enforcement, DLP, prompt injection detection.

What This Project Does

SpiderShield is an open-source security linter for MCP (Model Context Protocol) servers and AI agent skills. Think "npm audit for MCP tools." It scans tool descriptions, security patterns, architecture quality, and licensing, then outputs a 0-10 SpiderScore.

Quick Start

pip install spidershield

# Scan an MCP server from GitHub
spidershield scan https://github.com/owner/repo

# Check an AI agent config (Claude Code / OpenClaw)
spidershield agent-check /path/to/config

# Run as MCP server (for integration with Claude Desktop, etc.)
spidershield serve

Project Structure

src/spidershield/
  cli.py              -- Click CLI entry point
  models.py            -- Pydantic V2 models (ScanReport, SecurityIssue, etc.)
  server.py            -- MCP server mode (scan_mcp_server tool)
  scanner/
    runner.py          -- 4-stage scan pipeline (descriptions → security → architecture → license)
    description_quality.py -- Tool description scoring (7 criteria)
    security_scan.py   -- 46+ static security patterns
    architecture_check.py -- Code quality checks
    license_check.py   -- License detection
  agent/
    scanner.py         -- Agent config security audit
    skill_scanner.py   -- Skill malware/injection detection (20+ patterns)
    toxic_flow.py      -- Dangerous capability combination detection
    pinning.py         -- SHA-256 content pinning for rug-pull detection
  rewriter/
    runner.py          -- Template + LLM description rewriter
  hardener/runner.py   -- Security fix suggestions

Build & Test

# Install in dev mode
pip install -e ".[dev]"

# Run tests (use empty env vars to skip Supabase, use local SQLite)
SUPABASE_URL= SUPABASE_SERVICE_KEY= python -m pytest tests/ -x -q

# Run a specific test
python -m pytest tests/test_scanner.py -x -q