@yourclaw/clawguard-rules

Detection patterns for the ClawGuard security scanner. This package contains YAML-based pattern definitions, custom semgrep rules, and test fixtures used to identify malicious, vulnerable, or over-permissioned AI agent skills.

Installation

npm install @yourclaw/clawguard-rules

For local development as part of the ClawGuard project:

cd ../clawguard && make setup

Usage

import { matchPatterns, loadRules, categories } from "@yourclaw/clawguard-rules";

// Match against all categories
const findings = matchPatterns(suspiciousContent);

// Match against a specific category
const piFindings = matchPatterns(content, "prompt-injection");
const secretFindings = matchPatterns(content, "secrets");

API

matchPatterns(content: string, category?: string): Finding[]

Scans the provided content against all loaded detection patterns (or a specific category) and returns an array of findings sorted by severity.

loadRules(): Rule[]

Loads and validates all YAML pattern files. Rules are cached after first load.

categories

Array of available categories: prompt-injection, secrets, malware, permissions.

Detection Categories

Prompt Injection (prompt-injection.yaml)

88 patterns across 5 sub-categories:

| Sub-category | IDs | Examples | | ------------ | --- | ------- | | instructionOverride | PI-001 — PI-020 | "ignore previous instructions", "disregard all prior" | | rolePlaying | PI-021 — PI-040 | "you are now DAN", "pretend you are" | | encodingObfuscation | PI-041 — PI-060 | Base64 payloads, hex-encoded commands | | contextManipulation | PI-061 — PI-075 | "system prompt:", fake XML/JSON contexts | | instructionSmuggling | PI-076 — PI-088 | Hidden instructions in markdown, comments |

Secrets (secrets.yaml)

15 patterns for leaked credentials:

| ID | What it catches | | -- | --------------- | | SEC-001 — SEC-003 | AWS access keys, secret keys, session tokens | | SEC-004 — SEC-006 | GitHub tokens, private keys, GCP/Azure credentials | | SEC-007 — SEC-015 | Connection strings, JWTs, Slack tokens, generic API keys |

Malware (malware.yaml)

10 pattern groups for malicious behaviour:

| ID | What it catches | | -- | --------------- | | MAL-001 | Pipe-to-shell (curl | bash) | | MAL-002 | Reverse shells | | MAL-003 | Data exfiltration (curl/wget with sensitive paths) | | MAL-004 | Credential file access | | MAL-005 | Crypto mining | | MAL-006 — MAL-010 | Process injection, keyloggers, rootkits, persistence |

Permissions (permissions.yaml)

8 pattern groups for over-permissioned skills:

| ID | What it catches | | -- | --------------- | | PERM-001 | Unrestricted shell access | | PERM-002 | Root/admin filesystem access | | PERM-003 | Wildcard network access | | PERM-004 — PERM-008 | Docker socket, environment snooping, sudo, SSH, cron |

Semgrep Rules

Custom semgrep rules are provided in semgrep/:

| File | Catches | | ---- | ------- | | shell-injection.yaml | child_process.exec() with unsanitised input | | eval-usage.yaml | eval(), Function(), vm.runInNewContext() | | credential-access.yaml | Reading from ~/.ssh, ~/.aws/credentials, etc. |

Use with semgrep:

semgrep --config ./semgrep/ /path/to/skill

Test Fixtures

The test-fixtures/ directory contains sample skills for testing:

test-fixtures/
├── malicious/
│   ├── data-exfiltration-skill/    # triggers MAL-003, SEC-*
│   ├── prompt-override-skill/      # triggers PI-*
│   └── reverse-shell-skill/        # triggers MAL-002
└── benign/
    ├── memory-manager-skill/       # should trigger zero findings
    └── code-formatter-skill/       # should trigger zero findings

Development

# Install dependencies
npm install

# Run tests
npm run test:run        # single run
npm test                # watch mode

# Build
npm run build

# Lint
npm run lint
npm run lint:fix        # auto-fix

Adding a new pattern

1. Edit the appropriate YAML file in src/.
2. Use the next available ID in the sequence (e.g., PI-089).
3. Add a test fixture if the pattern covers a new attack vector.
4. Run npm run test:run to verify no regressions.

Makefile

A local Makefile is provided for convenience:

make install    # npm install
make build      # tsup build
make test       # vitest run
make lint       # biome check
make clean      # remove dist/ and node_modules/

License

CC-BY-SA-4.0 — Detection patterns are community-contributed and shared under Creative Commons.