ClawGuard

Security scanning & trust registry for AI agent skills (OpenClaw / Claude).

ClawGuard protects developers and users from malicious, vulnerable, or over-permissioned AI agent skills by providing multi-layered security analysis before a skill is ever installed.

Website: https://clawguard.sh

---

Why ClawGuard?

AI agent skills (MCP servers, OpenClaw skills, tool plugins) run with broad system access — filesystem, network, shell. A single malicious skill can steal credentials, exfiltrate data, or hijack the AI's behaviour through prompt injection.

ClawGuard exists to make the skill ecosystem safe by default:

• For hosted platforms (like YourClaw) — ClawGuard powers the trust registry that gates every skill before it reaches users.
• For self-hosters — run clawguard scan locally or add the upcoming GitHub Action to your CI pipeline to scan skills automatically on every PR.
• For the community — contribute detection rules, report malicious skills, and help secure the open AI agent ecosystem.

---

What is ClawGuard?

When developers install AI agent skills (e.g., OpenClaw skills for Claude), they trust that those skills won't:

• Inject malicious prompts to override the AI's behaviour
• Steal credentials or API keys
• Open reverse shells or exfiltrate data
• Request excessive permissions

ClawGuard scans skills before they're installed and provides:

1. 120+ detection patterns for prompt injection, secrets, malware, and permission abuse
2. A CLI that developers run locally: clawguard scan ./my-skill
3. npm packages (@yourclaw/clawguard-rules, @yourclaw/clawguard-scanner) you can integrate into your own projects programmatically
4. A web UI + REST API at clawguard.sh for browsing the trust registry and scanning skills on demand
5. SVG trust badges for skill READMEs: ![ClawGuard](https://clawguard.sh/api/v1/badge/memory-manager)
6. (Coming soon) A GitHub Action to scan skills on every PR in your CI

---

Quick Start (2 commands)

This is all you need. The bootstrap target clones all sibling repos, installs dependencies, and builds everything automatically.

git clone https://github.com/yourclaw/clawguard.git && cd clawguard
make bootstrap

That's it. After bootstrap finishes:

make dev     # → http://localhost:3000  (web UI + API)
make scan    # → demo scan against test fixtures
make test    # → run all tests

Prerequisites

• Node.js >= 20 and npm >= 10
• Git
• (optional) Docker — only if you want a local PostgreSQL database
• (optional) gitleaks, semgrep, mcp-scan — for extended scanning beyond the built-in patterns

---

How It Works

Repository Structure

ClawGuard is organised as independent repos that are cloned as siblings. The clawguard repo (this one) is the orchestration hub — it clones and wires everything together.

your-workspace/
├── clawguard/              ← YOU ARE HERE — orchestration, Makefile, docs
├── clawguard-rules/        ← Detection patterns (YAML + semgrep)
├── clawguard-scanner/      ← Scanner orchestrator (runs all tools)
├── clawguard-cli/          ← Developer CLI: clawguard scan <path>
└── clawguard-web/          ← Next.js web UI + REST API + trust registry

During local development, packages reference each other via file: links in package.json (e.g., "@yourclaw/clawguard-rules": "file:../clawguard-rules"). Changes in one repo are instantly visible to the others — no publishing needed.

Dependency Chain

clawguard-rules  ──→  clawguard-scanner  ──→  clawguard-cli
     │                       │
     │                       ↓
     └──────────────→  clawguard-web

Repo	npm package	Description
clawguard-rules	@yourclaw/clawguard-rules	120+ YAML detection patterns + semgrep rules
clawguard-scanner	@yourclaw/clawguard-scanner	Orchestrates 5 scanners in parallel
clawguard-cli	@yourclaw/clawguard-cli	CLI: clawguard scan, clawguard check, clawguard doctor
clawguard-web	—	Next.js 16 app at clawguard.sh

---

Local Development vs Production

	Local	Production
Web UI	http://localhost:3000	https://clawguard.sh
API	localhost:3000/api/v1/...	clawguard.sh/api/v1/...
Database	Mock data (no DB required)	Neon Serverless Postgres
Scanning	Built-in patterns + optional tools	Full pipeline
Deploy	make dev	Vercel auto-deploy on push to main

Local development does NOT require a database

The web app ships with mock data so you can develop the UI and API without any database setup. All API endpoints return realistic responses out of the box.

Optional: Local PostgreSQL (for DB development)

If you want to work on database features, you can spin up a local Postgres:

make db-start    # Docker: postgres:16-alpine on port 5432
make db-migrate  # Drizzle ORM migrations

This creates a separate local database — completely isolated from production. The connection string is:

postgresql://clawguard:clawguard@localhost:5432/clawguard

Production uses a separate Neon Serverless Postgres instance at clawguard.sh, configured via Vercel environment variables.

---

Makefile Reference

Run make help to see all targets:

Core Workflow

Target	Description
make bootstrap	First-time setup: clone all repos + install + build
make dev	Start the web app at http://localhost:3000
make test	Run all tests (rules + scanner)
make scan	Demo scan against test fixtures
make build	Build all packages

Setup & Maintenance

Target	Description
make clone	Clone any missing sibling repos
make setup	Install deps + build (assumes repos exist)
make update	git pull on all repos
make status	Show clone/deps/build status for every repo
make doctor	Check which external scanning tools are installed
make clean	Remove node_modules/ and dist/ everywhere
make rebuild	Clean → setup → build → test

Database

Target	Description
make db-start	Start local PostgreSQL via Docker
make db-stop	Stop the local database container
make db-reset	Destroy and recreate the local database
make db-migrate	Run Drizzle migrations

Testing & Scanning

Target	Description
make test-rules	Test detection patterns only
make test-scanner	Test scanner orchestrator only
make test-watch	Watch mode for rules tests
make scan-all-fixtures	Scan every test fixture with CI output
make lint	Lint all repos

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      clawguard-web                          │
│              Next.js UI + REST API + DB                     │
│         GET /api/v1/check?name=<skill>                      │
└──────────────────────┬──────────────────────────────────────┘
                       │ imports
┌──────────────────────▼──────────────────────────────────────┐
│                    clawguard-scanner                         │
│        Orchestrator — runs all scanners in parallel          │
│   ┌──────────┬──────────┬──────────┬──────────┬──────────┐  │
│   │BuiltinPI │ Gitleaks │ Semgrep  │ MCP-Scan │ npm audit│  │
│   └──────────┴──────────┴──────────┴──────────┴──────────┘  │
└──────────────────────┬──────────────────────────────────────┘
                       │ imports
┌──────────────────────▼──────────────────────────────────────┐
│                     clawguard-rules                          │
│          YAML patterns · Semgrep rules · Schemas             │
└─────────────────────────────────────────────────────────────┘

The CLI (clawguard-cli) wraps the scanner for terminal usage. The web app (clawguard-web) wraps it for browser-based scanning and serves as the public trust registry at clawguard.sh.

Optional: An AI review adapter (via Claude API) can be enabled for ambiguous cases that need judgement beyond static patterns.

---

API Endpoints

The web app exposes a REST API at /api/v1/:

Method	Endpoint	Description
GET	/api/v1/check?name=<skill>	Fast trust lookup (< 200 ms)
GET	/api/v1/skills	List all scanned skills
POST	/api/v1/scan	Trigger on-demand scan
GET	/api/v1/badge/<slug>	SVG trust badge

Example — check a skill:

# Local
curl http://localhost:3000/api/v1/check?name=memory-manager

# Production
curl https://clawguard.sh/api/v1/check?name=memory-manager

---

Detection Categories

Category	Pattern IDs	Count	Examples
Prompt Injection	PI-001 — PI-088	88	Instruction override, role-playing, encoding
Secrets	SEC-001 — SEC-015	15	AWS keys, GitHub tokens, private keys
Malware	MAL-001 — MAL-010	10	Reverse shells, crypto miners, exfiltration
Permissions	PERM-001 — PERM-008	8	Unrestricted shell/FS/network access

---

Deployment & CI/CD

Web App (clawguard.sh)

• Hosted on Vercel
• Auto-deploys when main is pushed on clawguard-web
• Database: Neon Serverless Postgres (separate from local dev)
• Domain: clawguard.sh

Contributing → Auto-Deploy Flow

You push to main → Vercel builds → clawguard.sh is updated

Contributors don't need access to the production database or Vercel — just push code and it deploys automatically.

---

Roadmap

• GitHub Action — Add yourclaw/clawguard-action to your CI to scan skills on every PR. Drop a one-liner into your workflow and get findings as PR comments.
• More detection rules — We're actively expanding coverage for new prompt injection techniques, supply chain attacks, and MCP-specific threats. Community contributions are especially welcome here.
• Hosted scanning for self-hosters — Run your own ClawGuard instance to secure your private OpenClaw deployment.

---

Contributing

We're actively inviting contributors — especially for:

• Detection rules — New YAML patterns and semgrep rules in clawguard-rules. This is the easiest and highest-impact way to contribute.
• Scanner adapters — Integrate new scanning tools in clawguard-scanner.
• Web UI & API — Features, bug fixes, and UX improvements in clawguard-web.
• CLI improvements — Better output, new commands, CI integrations in clawguard-cli.

See CONTRIBUTING.md for complete guidelines.

TL;DR:

git clone https://github.com/yourclaw/clawguard.git && cd clawguard
make bootstrap          # one-time setup
make dev                # start developing
# ... make changes ...
make test && make lint  # verify before PR

---

License

• clawguard-rules — CC-BY-SA-4.0 (community-contributed detection patterns)
• All other repos — Apache-2.0