teehooai

# SpiderShield Security Scanner

Security scanning and trust scoring for OpenClaw skills. 6 commands covering
the full security lifecycle: trust lookup, malware scan, config audit,
auto-fix, rug pull detection, and bulk scanning.

**4,000+ skills pre-scanned. Precision 93%+ (improving). 0.1s trust score lookup.**

---

## Setup

The `/spidershield check` command works immediately — no installation needed.
It queries the SpiderRating Trust API (public, no key required).

For local scanning commands (scan, audit-config, fix, pin, scan-all),
install the scanner:

```bash
pip install spidershield
```

---

## Commands

### /spidershield check <author/skill>

Check the Trust Score for a published skill. Queries the SpiderRating Trust
Registry (4,000+ pre-scanned skills) and returns score, grade, capabilities,
ecosystem ranking, and VirusTotal comparison.

**Examples**:
```
/spidershield check spclaudehome/web-search-pro
/spidershield check alice/my-skill
```

**Output**:
```
SpiderRating Skill Trust Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Skill:      spclaudehome/web-search-pro
  Score:      7.2 / 10   Grade: B
  Verdict:    ✅ SAFE
  Precision:  93%+ (improving)

  📦 Capabilities:
    🌐 Browser  📦 Installs Deps  🔗 Webhook

  🔍 Security: 0 critical · 0 high · 1 medium · 0 low
    [HIGH] No sandbox — Agent can execute arbitrary shell commands

  📊 Ecosystem: #142 / 4,037 skills (Top 4%)
    Breakdown: Description 6.5 · Security 8.0 · Metadata 5.5
    Downloads: 5,000  Active installs: 42

  💡 Rated B (7.2/10) — safe to install.
  🔗 https://spiderrating.com/servers/spclaudehome__web-search-pro
```

**Implementation**: calls `scripts/check.sh $1`

---

### /spidershield scan <path>

Scan a single skill for malicious patterns using 24 detection rules.
Detects credential theft, prompt injection, crypto wallet access,
obfuscated payloads, and more.

**Examples**:
```
/spidershield scan ./my-skill/
/spidershield scan ./my-skill/SKILL.md
```

**Output**:
```
SAFE — my-skill
```
or
```
MALICIOUS — evil-skill
  • Reads ~/.ssh/id_rsa and sends to external webhook
  • Base64-encoded shell command detected
```

**Implementation**: calls `scripts/scan.sh $1`

---

### /spidershield audit-config [--skills] [--verify]

Audit your OpenClaw installation for insecure settings.
Checks 10 configuration items including gateway binding, auth strength,
sandbox mode, and file permissions.

**Options**:
- `--skills` — Also scan all installed skills for malware
- `--verify` — Also verify pinned skills for tampering

**Examples**:
```
/spidershield audit-config
/spidershield audit-config --skills --verify
```

**Implementation**: calls `scripts/audit-config.sh`

---

### /spidershield fix [--dry-run]

Scan OpenClaw config and auto-fix insecure settings.
Shows before/after score change.

**Options**:
- `--dry-run` — Preview what would be fixed without making changes

**Examples**:
```
/spidershield fix --dry-run
/spidershield fix
```

**Output**:
```
Score: 5.2/10 -> 8.1/10
Fixed: gateway binding, auth strength, sandbox mode
```

**Implementation**: calls `scripts/fix.sh`

---

### /spidershield pin add|verify|list|remove [path]

Pin skill content hashes to detect rug pull attacks — when a skill
is silently modified after installation (supply chain attack).

**Subcommands**:
- `pin add <path>` — Record current content hash
- `pin verify [path]` — Check if any pinned skills were modified
- `pin list` — Show all pinned skills
- `pin remove <name>` — Remove a pin

**Examples**:
```
/spidershield pin add ~/.openclaw/skills/web-search-pro/
/spidershield pin verify
/spidershield pin list
```

**Output**:
```
OK web-search-pro
TAMPERED evil-skill
  - Content hash changed since pin (possible rug pull)

Results: 12 OK, 1 TAMPERED, 0 UNKNOWN
```

**Implementation**: calls `scripts/pin.sh $1 $2`

---

### /spidershield scan-all

Scan ALL installed OpenClaw skills for malicious patterns in one command.
Equivalent to `/spidershield audit-config --skills`.

**Example**:
```
/spidershield scan-all
```

**Implementation**: calls `scripts/scan-all.sh`

---

## Privacy

- `/check`: sends only `author/skill` slug to SpiderRating API
- `/scan`, `/audit-config`, `/fix`, `/pin`, `/scan-all`: run **entirely locally** — no data leaves your machine
- SpiderRating never stores your code, credentials, or session data

---

## Links

- Trust Registry: https://spiderrating.com
- Source: https://github.com/teehooai/spidershield
- Issues: https://github.com/teehooai/spidershield/issues

FILE:README.md
# SpiderShield — OpenClaw Security Skill

Security scanning and trust scoring for OpenClaw skills.
4,000+ skills pre-scanned. 93.6% precision. 0.1s trust score lookup.

## Install via ClawHub

```bash
npx clawhub install spidershield
```

`/spidershield check` works immediately — no extra setup needed.

For local scanning commands (scan, audit-config, fix, pin, scan-all), also install:
```bash
pip install spidershield
```

## Commands

| Command | Description |
|---------|-------------|
| `/spidershield check <author/skill>` | Trust score lookup (0.1s, pre-computed) |
| `/spidershield scan <path>` | Skill malware scan (24 detection rules) |
| `/spidershield audit-config` | OpenClaw config security audit |
| `/spidershield fix` | Auto-fix insecure config settings |
| `/spidershield pin add\|verify\|list` | Rug pull detection (content hash pinning) |
| `/spidershield scan-all` | Scan all installed skills |

## Privacy

- `/check` sends only author/skill slug to API
- All other commands run **entirely locally** — no data leaves your machine

## Source

- [SKILL.md](SKILL.md) — full command documentation
- [SpiderRating](https://spiderrating.com) — Trust Registry
- [GitHub](https://github.com/teehooai/spidershield)

FILE:scripts/scan.sh
#!/usr/bin/env bash
# /spidershield scan <path>
# Scan a single skill for malicious patterns (24 detection rules).
# Wraps: spidershield agent-check <path> (open-source CLI)

set -euo pipefail

TARGET="-"
if [[ -z "$TARGET" ]]; then
  echo "Usage: /spidershield scan <path-to-skill-or-SKILL.md>" >&2
  echo "" >&2
  echo "Examples:" >&2
  echo "  /spidershield scan ./my-skill/" >&2
  echo "  /spidershield scan ./my-skill/SKILL.md" >&2
  exit 1
fi

echo ""
echo "SpiderShield — Skill Malware Scan"
echo "Target: $TARGET"
echo ""

# Resolve CLI: prefer spidershield (open-source, pip install spidershield)
if command -v spidershield &>/dev/null; then
  spidershield agent-check "$TARGET"
elif python3 -c "import spidershield" 2>/dev/null; then
  python3 -m spidershield agent-check "$TARGET"
else
  echo "" >&2
  echo "spidershield not installed. To use this command:" >&2
  echo "" >&2
  echo "  pip install spidershield" >&2
  echo "" >&2
  echo "Or use /spidershield check <skill-name> (works without installation)." >&2
  exit 1
fi

FILE:scripts/fix.sh
#!/usr/bin/env bash
# /spidershield fix [--dry-run]
# Scan OpenClaw config and auto-fix insecure settings.
# Wraps: spidershield agent-check --fix | --dry-run

set -euo pipefail

MODE="fix"
if [[ "-" == "--dry-run" ]]; then
  MODE="dry-run"
fi

if [[ "$MODE" == "dry-run" ]]; then
  echo ""
  echo "SpiderShield — Config Fix (DRY RUN — no changes will be made)"
  echo ""
else
  echo ""
  echo "SpiderShield — Config Auto-Fix"
  echo ""
  echo "This will modify your OpenClaw configuration files in ~/.openclaw/"
  echo -n "Continue? [y/N] "
  read -r CONFIRM
  if [[ "$CONFIRM" != "y" && "$CONFIRM" != "Y" ]]; then
    echo "Cancelled."
    exit 0
  fi
  echo ""
fi

# Resolve CLI: prefer spidershield (open-source, pip install spidershield)
if command -v spidershield &>/dev/null; then
  if [[ "$MODE" == "dry-run" ]]; then
    spidershield agent-check --dry-run
  else
    spidershield agent-check --fix
  fi
elif python3 -c "import spidershield" 2>/dev/null; then
  if [[ "$MODE" == "dry-run" ]]; then
    python3 -m spidershield agent-check --dry-run
  else
    python3 -m spidershield agent-check --fix
  fi
else
  echo "" >&2
  echo "spidershield not installed. To use this command:" >&2
  echo "" >&2
  echo "  pip install spidershield" >&2
  echo "" >&2
  echo "Or use /spidershield check <skill-name> (works without installation)." >&2
  exit 1
fi

FILE:scripts/audit-config.sh
#!/usr/bin/env bash
# /spidershield audit-config [--skills] [--verify] [--json] [--sarif]
# Scan your OpenClaw installation for security issues (10 config checks).
# Wraps: spidershield agent-check [--skills] [--verify]

set -euo pipefail

EXTRA_FLAGS=""

# Parse optional flags — warn on unknown
while [[ $# -gt 0 ]]; do
  case "$1" in
    --skills)  EXTRA_FLAGS="$EXTRA_FLAGS --skills"; shift ;;
    --verify)  EXTRA_FLAGS="$EXTRA_FLAGS --verify"; shift ;;
    --json)    EXTRA_FLAGS="$EXTRA_FLAGS --format json"; shift ;;
    --sarif)   EXTRA_FLAGS="$EXTRA_FLAGS --format sarif"; shift ;;
    -*)
      echo "Warning: unknown option '$1' (ignored)" >&2
      shift ;;
    *)
      echo "Warning: unexpected argument '$1' (ignored)" >&2
      shift ;;
  esac
done

echo ""
echo "SpiderShield — OpenClaw Config Audit"
echo ""

# Resolve CLI: prefer spidershield (open-source, pip install spidershield)
if command -v spidershield &>/dev/null; then
  # shellcheck disable=SC2086
  spidershield agent-check $EXTRA_FLAGS
elif python3 -c "import spidershield" 2>/dev/null; then
  # shellcheck disable=SC2086
  python3 -m spidershield agent-check $EXTRA_FLAGS
else
  echo "" >&2
  echo "spidershield not installed. To use this command:" >&2
  echo "" >&2
  echo "  pip install spidershield" >&2
  echo "" >&2
  echo "Or use /spidershield check <skill-name> (works without installation)." >&2
  exit 1
fi

FILE:scripts/pin.sh
#!/usr/bin/env bash
# /spidershield pin <subcommand> [args]
# Skill pinning — detect rug pull attacks by tracking content hashes.
# Wraps: spidershield agent-pin add|verify|list|remove|add-all

set -euo pipefail

# Helper: resolve CLI command (prefer spidershield open-source package)
_run() {
  if command -v spidershield &>/dev/null; then
    spidershield "$@"
  elif python3 -c "import spidershield" 2>/dev/null; then
    python3 -m spidershield "$@"
  else
    echo "" >&2
    echo "spidershield not installed. To use this command:" >&2
    echo "" >&2
    echo "  pip install spidershield" >&2
    echo "" >&2
    echo "Or use /spidershield check <skill-name> (works without installation)." >&2
    exit 1
  fi
}

SUBCMD="-"
if [[ $# -gt 0 ]]; then shift; fi

case "$SUBCMD" in
  add)
    TARGET="-"
    if [[ -z "$TARGET" ]]; then
      echo "Usage: /spidershield pin add <path-to-skill>" >&2
      echo "Example: /spidershield pin add ~/.openclaw/skills/web-search-pro/" >&2
      exit 1
    fi
    echo ""
    echo "SpiderShield — Pin Skill"
    echo ""
    _run agent-pin add "$TARGET"
    ;;
  add-all)
    echo ""
    echo "SpiderShield — Pin All Installed Skills"
    echo ""
    _run agent-pin add-all
    ;;
  verify)
    echo ""
    echo "SpiderShield — Verify Pinned Skills"
    echo ""
    TARGET="-"
    if [[ -n "$TARGET" ]]; then
      if [[ -e "$TARGET" ]]; then
        _run agent-pin verify "$TARGET"
      elif [[ -d "$HOME/.openclaw/skills/$TARGET" ]]; then
        _run agent-pin verify "$HOME/.openclaw/skills/$TARGET"
      else
        echo "Error: '$TARGET' not found as path or installed skill name." >&2
        echo "Usage: /spidershield pin verify [<path-to-skill>]" >&2
        exit 1
      fi
    else
      _run agent-pin verify
    fi
    ;;
  list)
    echo ""
    echo "SpiderShield — Pinned Skills"
    echo ""
    _run agent-pin list
    ;;
  remove)
    NAME="-"
    if [[ -z "$NAME" ]]; then
      echo "Usage: /spidershield pin remove <skill-name>" >&2
      exit 1
    fi
    _run agent-pin remove "$NAME"
    ;;
  *)
    echo "SpiderShield Pin — Rug Pull Detection" >&2
    echo "" >&2
    echo "Usage:" >&2
    echo "  /spidershield pin add <path>        Pin a skill (record hash)" >&2
    echo "  /spidershield pin add-all           Pin all installed skills" >&2
    echo "  /spidershield pin verify [path]     Verify pinned skills" >&2
    echo "  /spidershield pin list              List all pinned skills" >&2
    echo "  /spidershield pin remove <name>     Remove a pin" >&2
    exit 1
    ;;
esac

FILE:scripts/check.sh
#!/usr/bin/env bash
# /spidershield check <skill-name> or <author/skill>
# Queries SpiderRating Skill Trust API and prints rich trust report.
# Supports both "web-search-pro" (fuzzy) and "alice/web-search-pro" (exact).

set -euo pipefail

INPUT="-"
if [[ -z "$INPUT" ]]; then
  echo "Usage: /spidershield check <skill-name>" >&2
  echo "" >&2
  echo "Examples:" >&2
  echo "  /spidershield check web-search-pro" >&2
  echo "  /spidershield check spclaudehome/web-search-pro" >&2
  exit 1
fi

API_BASE="https://api.spiderrating.com"

# Detect format: author/skill or just skill name
if [[ "$INPUT" == *"/"* ]]; then
  # Exact: author/skill
  AUTHOR=$(echo "$INPUT" | cut -d/ -f1)
  SKILL=$(echo "$INPUT" | cut -d/ -f2-)
  URL="$API_BASE/v1/public/skill-score/$AUTHOR/$SKILL"
else
  # Fuzzy: skill name only
  URL="$API_BASE/v1/public/skill-score/$INPUT"
fi

RESPONSE=$(curl -sf --max-time 10 "$URL") || {
  echo "[SpiderRating] API unavailable — check your connection." >&2
  exit 1
}

# Parse and display rich output
echo "$RESPONSE" | python3 -c "
import sys, json

try:
    d = json.load(sys.stdin)
except json.JSONDecodeError:
    print('[SpiderRating] Invalid response from API.')
    sys.exit(1)

verdict  = d.get('verdict', 'unknown')
score    = d.get('score')
grade    = d.get('grade', '?')
block    = d.get('block', False)
msg      = d.get('message', '')
slug     = d.get('slug', '?')
conf     = d.get('confidence')
scanned  = d.get('scanned_at', '')
caps     = d.get('capabilities', [])
rank     = d.get('ecosystem_rank')
findings = d.get('finding_summary', {})
risks    = d.get('risk_factors', [])
breakdown = d.get('score_breakdown', {})
mp       = d.get('marketplace')
url      = d.get('report_url', '')

score_str = f'{score:.1f} / 10' if score is not None else 'N/A'
conf_label = d.get('confidence_label', f'{conf*100:.0f}%' if conf else 'N/A')

VERDICT_ICONS = {'safe': '\u2705', 'risky': '\u26a0\ufe0f ', 'malicious': '\U0001f6a8', 'unknown': '\u2753'}
icon = VERDICT_ICONS.get(verdict, '\u2753')

CAP_ICONS = {
    'browser_access': '\U0001f310 Browser',
    'installs_deps': '\U0001f4e6 Installs Deps',
    'webhook_calls': '\U0001f517 Webhook',
    'credential_handling': '\U0001f511 Credentials',
    'env_var_access': '\U0001f527 Env Vars',
    'external_network': '\U0001f30d Network',
    'data_mutation': '\U0001f4be Data Mutation',
    'crypto_wallet': '\U0001f4b0 Crypto',
    'downloads_binary': '\u2b07\ufe0f  Binary',
}

# Header
print()
print(f'SpiderRating Skill Trust Report')
print('\u2501' * 40)
print(f'  Skill:      {slug}')
print(f'  Score:      {score_str}   Grade: {grade}')
print(f'  Verdict:    {icon} {verdict.upper()}')
print(f'  Precision:  {conf_label}')
if scanned:
    print(f'  Scanned:    {scanned[:10]}')

# Capabilities
if caps:
    print()
    print(f'  \U0001f4e6 Capabilities:')
    cap_strs = [CAP_ICONS.get(c, c) for c in caps]
    print(f'    {\"  \".join(cap_strs)}')

# Security findings
crit = findings.get('critical', 0)
high = findings.get('high', 0)
med  = findings.get('medium', 0)
low  = findings.get('low', 0)
print()
print(f'  \U0001f50d Security: {crit} critical \u00b7 {high} high \u00b7 {med} medium \u00b7 {low} low')
if risks:
    for r in risks:
        print(f'    {r}')

# Ecosystem ranking
if rank:
    pos = rank.get('position', '?')
    total = rank.get('total', '?')
    pct = rank.get('percentile', '')
    print()
    print(f'  \U0001f4ca Ecosystem: #{pos} / {total} skills ({pct})')

# Score breakdown
if breakdown:
    desc = breakdown.get('description')
    sec  = breakdown.get('security')
    meta = breakdown.get('metadata')
    parts = []
    if desc is not None: parts.append(f'Description {desc:.1f}')
    if sec  is not None: parts.append(f'Security {sec:.1f}')
    if meta is not None: parts.append(f'Metadata {meta:.1f}')
    if parts:
        print(f'    Breakdown: {\" \u00b7 \".join(parts)}')

# Marketplace
if mp and mp.get('downloads'):
    dl = mp['downloads']
    inst = mp.get('installs_current', 0)
    print(f'    Downloads: {dl:,}  Active installs: {inst:,}')

# Recommendation
print()
if msg:
    print(f'  \U0001f4a1 {msg}')
if url:
    print(f'  \U0001f517 {url}')
print()

# Exit code: 2 for malicious (blocked), 1 for risky, 0 for safe/unknown
if block:
    sys.exit(2)
elif verdict == 'risky':
    sys.exit(1)
"

FILE:scripts/scan-all.sh
#!/usr/bin/env bash
# /spidershield scan-all
# Scan ALL installed OpenClaw skills for malicious patterns.
# Wraps: spidershield agent-check --skills

set -euo pipefail

echo ""
echo "SpiderShield — Scan All Installed Skills"
echo "(also includes OpenClaw config audit)"
echo ""

# Resolve CLI: prefer spidershield (open-source, pip install spidershield)
if command -v spidershield &>/dev/null; then
  spidershield agent-check --skills
elif python3 -c "import spidershield" 2>/dev/null; then
  python3 -m spidershield agent-check --skills
else
  echo "" >&2
  echo "spidershield not installed. To use this command:" >&2
  echo "" >&2
  echo "  pip install spidershield" >&2
  echo "" >&2
  echo "Or use /spidershield check <skill-name> (works without installation)." >&2
  exit 1
fi

FILE:skill.yaml
# SpiderShield — OpenClaw Skill Manifest
# ClawHub submission format

name: spidershield
display_name: "SpiderShield Security Scanner"
version: "0.3.0"
description: |
  4,000+ skills already scanned. 0.1s trust score lookup. Precision 93%+ (improving).
  When VirusTotal says "suspicious", SpiderShield tells you why it's safe (or not).

  Scan skills for malware (24 detection rules), audit your OpenClaw config,
  pin skills against tampering (rug pull detection), and auto-fix insecure settings.

author:
  name: SpiderRating
  email: [email protected]
  url: https://spiderrating.com

license: MIT
repository: https://github.com/teehooai/spidershield
homepage: https://spiderrating.com

keywords:
  - security
  - skill-security
  - trust-score
  - vulnerability-scan
  - malware-detection
  - openclaw-security
  - rug-pull-detection
  - config-audit

categories:
  - security
  - developer-tools

# Commands exposed by this skill (6 total, 5 unique to SpiderShield)
commands:
  - name: check
    description: "Check trust score for a published skill (0.1s, pre-computed)"
    usage: "/spidershield check <author/skill>"
    example: "/spidershield check spclaudehome/web-search-pro"

  - name: scan
    description: "Scan a single skill for malicious patterns (24 detection rules)"
    usage: "/spidershield scan <path>"
    example: "/spidershield scan ./my-skill/SKILL.md"

  - name: audit-config
    description: "Audit your OpenClaw installation for insecure settings"
    usage: "/spidershield audit-config [--skills] [--verify]"
    example: "/spidershield audit-config --skills"

  - name: fix
    description: "Auto-fix insecure OpenClaw config settings"
    usage: "/spidershield fix [--dry-run]"
    example: "/spidershield fix --dry-run"

  - name: pin
    description: "Pin skills against tampering (rug pull detection)"
    usage: "/spidershield pin add|verify|list|remove <path>"
    example: "/spidershield pin verify"

  - name: scan-all
    description: "Scan all installed skills for malicious patterns"
    usage: "/spidershield scan-all"
    example: "/spidershield scan-all"

# Network access declaration (for ClawHub security review)
network:
  outbound:
    - host: api.spiderrating.com
      purpose: "Trust Registry lookups (check command only)"
      data_sent: "author/skill slug only — no source code"
  none_for:
    - scan
    - audit-config
    - fix
    - pin
    - scan-all

# Permissions (minimal)
permissions:
  filesystem:
    read:
      - "./"                    # scan: reads local skill path
      - "~/.openclaw/"          # audit-config/fix: reads OpenClaw config
      - "~/.spidershield/"      # pin: reads pin data
    write:
      - "~/.openclaw/"          # fix: writes config fixes
      - "~/.spidershield/"      # pin: writes pin data
  shell: true                      # scripts/*.sh are bash wrappers around spidershield CLI
  network: conditional           # only for check command

# Privacy declaration
privacy:
  data_collected: none
  data_sent_to_server: "Skill author/name slug for check command only"
  source_code_uploaded: false
  credentials_accessed: false
  telemetry: false

# Compatibility
platforms:
  - openclaw

requires:
  openclaw_version: ">=1.0.0"
  optional_dependencies:
    - name: spidershield
      install: "pip install spidershield"
      purpose: "Required for scan, audit-config, fix, pin, scan-all"
      fallback: "check command works without installation (API-only)"