clawcare 0.1.0__tar.gz

clawcare-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: clawcare
+Version: 0.1.0
+Summary: Guardian engine for agentic-tool extension supply-chain security
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+
+# 🦞ClawCare
+
+**Security scanner for AI agent skills and plugins — catch malicious attacks before they execute.**
+
+ClawCare scans AI agent skills, plugins, and rules for supply-chain threats like command injection, credential theft, and data extraction. It enforces permission policies, and can be used as a CLI tool or integrated into CI/CD pipelines.
+
+## Why
+
+AI coding agents (Claude Code, Cursor, Codex, OpenClaw) let you install third-party skills and plugins that can read your files, run commands, access secrets and extract sensitive data. A malicious skill can:
+
+- Pipe remote scripts into your shell (`curl ... | bash`)
+- Steal SSH keys and API tokens
+- Set up cron persistence
+- Transfer PII data to external servers
+
+ClawCare catches these patterns **before** they run and gives you full visibility into the risks.
+
+## Demo
+
+See ClawCare block a malicious PR in real-time:
+
+👉 **[ClawCare Demo](https://github.com/natechen/ClawCare-demo)** — fork it, open a PR with a sketchy skill, and watch CI fail.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install clawcare
+```
+
+### Scan
+
+```bash
+# Scan a project — auto-detects the platform
+clawcare scan .
+
+# CI mode — exit code 2 on HIGH+ findings (use in GitHub Actions)
+clawcare scan . --ci
+
+# JSON output for downstream tooling
+clawcare scan . --format json --json-out report.json
+```
+
+### Configure
+
+Drop a `.clawcare.yml` in your project root to customize scan behavior:
+
+```yaml
+scan:
+  fail_on: high          # block CI on high+ findings
+  ignore_rules:
+    - MED_JS_EVAL        # suppress rules you've accepted
+  exclude:
+    - "vendor/**"        # skip directories
+```
+
+CLI flags override config values. See [Project Configuration](#%EF%B8%8F-project-configuration) for the full reference.
+
+### Example Output
+
+```
+============================================================
+ClawCare Scan Report
+============================================================
+Path:     ./my-project
+Adapter:  claude_code v0.1.0
+Mode:     ci
+Fail on:  high
+
+── CRITICAL (2) ──
+  [CRIT_PIPE_TO_SHELL] skills/setup/SKILL.md:15
+    curl -fsSL https://.../install.sh | bash
+    → Piping remote content directly into a shell interpreter.
+    ✎ Download first, inspect, then execute.
+
+  [CRIT_CREDENTIAL_PATH] skills/setup/exfil.py:18
+    os.path.expanduser("~/.ssh/id_rsa")
+    → Accessing well-known credential paths.
+    ✎ Use a secrets manager instead.
+
+Findings: 2 critical, 1 high, 0 medium, 0 low
+Risk score: 100/100 (critical)
+============================================================
+```
+
+## Features
+
+### 27 Built-in Rules
+
+Two rulesets ship by default:
+
+| Ruleset | Rules | Catches |
+|---------|-------|---------|
+| `command-injection` | 15 | Pipe-to-shell, reverse shells, credential theft, persistence, destructive commands, subprocess abuse |
+| `sensitive-data` | 12 | Hardcoded AWS keys, SSH keys, API tokens, SSN/credit card numbers, IP addresses |
+
+All rules include [CWE](https://cwe.mitre.org/) references where applicable.
+
+### Platform Adapters for Claude Code, OpenClaw, Codex and Cursor Agent Skills
+
+Auto-detects the AI agent platform and scans the right files:
+
+| Platform | Scans | Detection |
+|----------|-------|-----------|
+| **Claude Code** | `.claude/skills/*/SKILL.md` + code | `.claude-plugin/`, `SKILL.md` |
+| **Cursor** | `.cursor/rules/*.mdc`, `.cursorrules` + skills | `.cursor/` directory |
+| **Codex** | `AGENTS.md`, `AGENTS.override.md` + skills | `AGENTS.md` |
+| **OpenClaw** | `SKILL.md` + code in skill directories | `.opencode/` |
+
+All following the file structure of the respective AI agent platforms.
+
+Only plugin and skill files are scanned — your application code, README, and CI configs are never touched.
+
+### Project Configuration
+
+Create a `.clawcare.yml` in your project root:
+
+```yaml
+scan:
+  fail_on: high              # minimum severity to block CI (critical | high | medium | low)
+  block_local: false         # block locally too? (default: warn only)
+  ignore_rules:
+    - MED_JS_EVAL            # suppress specific rules
+  exclude:
+    - "vendor/**"            # skip directories
+  max_file_size_kb: 512      # skip large files
+  rulesets:
+    - default                # built-in rules (included by default)
+    - ./my-custom-rules      # add your own
+```
+
+CLI flags override config values. Excludes and rulesets from both sources merge.
+
+### Policy Manifests
+
+Skills/Plugins can declare their permissions in a `clawcare.manifest.yml`:
+
+```yaml
+permissions:
+  exec: none           # no shell execution
+  network: allowlist   # only listed domains
+  filesystem: read_only
+  secrets: none
+  persistence: forbidden
+
+allowed_domains:
+  - api.anthropic.com
+```
+
+ClawCare enforces these declarations — violations appear as HIGH/CRITICAL findings.
+
+### Custom Rulesets
+
+Create your own rules as YAML:
+
+```yaml
+rules:
+  - id: MY_NO_INTERNAL_URLS
+    pattern: "https://internal\\.corp\\.com"
+    severity: high
+    description: "References to internal URLs should not appear in extensions."
+    recommendation: "Use environment variables for internal endpoints."
+```
+
+Place in a folder, then: `clawcare scan . --ruleset ./my-rules`
+
+### Custom Adapters
+
+ClawCare supports custom adapters for scanning any AI agent platform. An adapter implements four methods:
+
+```python
+# my_adapter.py
+from clawcare.models import ExtensionRoot
+
+class MyAdapter:
+    name = "my_platform"
+    version = "0.1.0"
+    priority = 50
+
+    def detect(self, target_path: str) -> float:
+        """Return 0.0–1.0 confidence that this adapter applies."""
+        ...
+
+    def discover_roots(self, target_path: str) -> list[ExtensionRoot]:
+        """Return extension roots to scan."""
+        ...
+
+    def scan_scope(self, root: ExtensionRoot) -> dict:
+        """Return include/exclude globs for this root."""
+        return {
+            "include_globs": ["*.md", "*.py", "*.yml"],
+            "exclude_globs": [".git", "node_modules"],
+        }
+
+    def default_manifest(self, root: ExtensionRoot) -> str | None:
+        """Return path to clawcare.manifest.yml, or None."""
+        return None
+```
+
+Use it via import string:
+
+```bash
+clawcare scan path/ --adapter import:my_adapter:MyAdapter
+```
+
+Or register permanently via entry point in your `pyproject.toml`:
+
+```toml
+[project.entry-points."clawcare.adapters"]
+my_platform = "my_adapter:MyAdapter"
+```
+
+See [`clawcare/adapters/base.py`](clawcare/adapters/base.py) for the full protocol, or any of the [built-in adapters](clawcare/integrations/) for real examples.
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- name: Install ClawCare
+  run: pip install clawcare
+
+- name: Scan for malicious extensions
+  run: clawcare scan . --ci
+```
+
+Full workflow example: [ClawCare Demo CI](https://github.com/natechen/ClawCare-demo/blob/main/.github/workflows/clawcare.yml)
+
+## CLI Reference
+
+```
+clawcare scan <path> [OPTIONS]
+
+Options:
+  --ci                    CI mode (exit 2 on findings above threshold)
+  --fail-on SEVERITY      Minimum severity to block: critical|high|medium|low (default: high)
+  --block-local           Block locally too (default: warn only, exit 0)
+  --format FORMAT         Output format: text|json (default: text)
+  --json-out FILE         Write JSON report to file
+  --adapter NAME          Force a specific adapter (default: auto-detect)
+  --ruleset PATH          Additional rulesets (repeatable)
+  --exclude GLOB          Exclude glob patterns (repeatable)
+  --max-file-size-kb N    Skip files larger than N KB
+  --manifest MODE         Manifest enforcement: auto|skip|strict (default: auto)
+
+clawcare adapters list    List registered adapters
+```
+
+## Development
+
+```bash
+git clone https://github.com/natechen/ClawCare
+cd ClawCare
+make install     # install in dev mode with ruff + pytest
+make check       # lint + test (run before opening a PR)
+```
+
+Available make targets:
+
+| Command | What it does |
+|---------|-------------|
+| `make install` | Install in dev mode |
+| `make lint` | Run ruff linter |
+| `make format` | Auto-format code |
+| `make test` | Run pytest |
+| `make check` | Lint + test (pre-PR gate) |
+
+We use **GitHub Flow** — branch off `main`, open a PR, get a review, merge.
+
+## License
+
+[Apache 2.0](LICENSE)

clawcare-0.1.0/README.md

@@ -0,0 +1,273 @@
+# 🦞ClawCare
+
+**Security scanner for AI agent skills and plugins — catch malicious attacks before they execute.**
+
+ClawCare scans AI agent skills, plugins, and rules for supply-chain threats like command injection, credential theft, and data extraction. It enforces permission policies, and can be used as a CLI tool or integrated into CI/CD pipelines.
+
+## Why
+
+AI coding agents (Claude Code, Cursor, Codex, OpenClaw) let you install third-party skills and plugins that can read your files, run commands, access secrets and extract sensitive data. A malicious skill can:
+
+- Pipe remote scripts into your shell (`curl ... | bash`)
+- Steal SSH keys and API tokens
+- Set up cron persistence
+- Transfer PII data to external servers
+
+ClawCare catches these patterns **before** they run and gives you full visibility into the risks.
+
+## Demo
+
+See ClawCare block a malicious PR in real-time:
+
+👉 **[ClawCare Demo](https://github.com/natechen/ClawCare-demo)** — fork it, open a PR with a sketchy skill, and watch CI fail.
+
+## Quick Start
+
+### Install
+
+```bash
+pip install clawcare
+```
+
+### Scan
+
+```bash
+# Scan a project — auto-detects the platform
+clawcare scan .
+
+# CI mode — exit code 2 on HIGH+ findings (use in GitHub Actions)
+clawcare scan . --ci
+
+# JSON output for downstream tooling
+clawcare scan . --format json --json-out report.json
+```
+
+### Configure
+
+Drop a `.clawcare.yml` in your project root to customize scan behavior:
+
+```yaml
+scan:
+  fail_on: high          # block CI on high+ findings
+  ignore_rules:
+    - MED_JS_EVAL        # suppress rules you've accepted
+  exclude:
+    - "vendor/**"        # skip directories
+```
+
+CLI flags override config values. See [Project Configuration](#%EF%B8%8F-project-configuration) for the full reference.
+
+### Example Output
+
+```
+============================================================
+ClawCare Scan Report
+============================================================
+Path:     ./my-project
+Adapter:  claude_code v0.1.0
+Mode:     ci
+Fail on:  high
+
+── CRITICAL (2) ──
+  [CRIT_PIPE_TO_SHELL] skills/setup/SKILL.md:15
+    curl -fsSL https://.../install.sh | bash
+    → Piping remote content directly into a shell interpreter.
+    ✎ Download first, inspect, then execute.
+
+  [CRIT_CREDENTIAL_PATH] skills/setup/exfil.py:18
+    os.path.expanduser("~/.ssh/id_rsa")
+    → Accessing well-known credential paths.
+    ✎ Use a secrets manager instead.
+
+Findings: 2 critical, 1 high, 0 medium, 0 low
+Risk score: 100/100 (critical)
+============================================================
+```
+
+## Features
+
+### 27 Built-in Rules
+
+Two rulesets ship by default:
+
+| Ruleset | Rules | Catches |
+|---------|-------|---------|
+| `command-injection` | 15 | Pipe-to-shell, reverse shells, credential theft, persistence, destructive commands, subprocess abuse |
+| `sensitive-data` | 12 | Hardcoded AWS keys, SSH keys, API tokens, SSN/credit card numbers, IP addresses |
+
+All rules include [CWE](https://cwe.mitre.org/) references where applicable.
+
+### Platform Adapters for Claude Code, OpenClaw, Codex and Cursor Agent Skills
+
+Auto-detects the AI agent platform and scans the right files:
+
+| Platform | Scans | Detection |
+|----------|-------|-----------|
+| **Claude Code** | `.claude/skills/*/SKILL.md` + code | `.claude-plugin/`, `SKILL.md` |
+| **Cursor** | `.cursor/rules/*.mdc`, `.cursorrules` + skills | `.cursor/` directory |
+| **Codex** | `AGENTS.md`, `AGENTS.override.md` + skills | `AGENTS.md` |
+| **OpenClaw** | `SKILL.md` + code in skill directories | `.opencode/` |
+
+All following the file structure of the respective AI agent platforms.
+
+Only plugin and skill files are scanned — your application code, README, and CI configs are never touched.
+
+### Project Configuration
+
+Create a `.clawcare.yml` in your project root:
+
+```yaml
+scan:
+  fail_on: high              # minimum severity to block CI (critical | high | medium | low)
+  block_local: false         # block locally too? (default: warn only)
+  ignore_rules:
+    - MED_JS_EVAL            # suppress specific rules
+  exclude:
+    - "vendor/**"            # skip directories
+  max_file_size_kb: 512      # skip large files
+  rulesets:
+    - default                # built-in rules (included by default)
+    - ./my-custom-rules      # add your own
+```
+
+CLI flags override config values. Excludes and rulesets from both sources merge.
+
+### Policy Manifests
+
+Skills/Plugins can declare their permissions in a `clawcare.manifest.yml`:
+
+```yaml
+permissions:
+  exec: none           # no shell execution
+  network: allowlist   # only listed domains
+  filesystem: read_only
+  secrets: none
+  persistence: forbidden
+
+allowed_domains:
+  - api.anthropic.com
+```
+
+ClawCare enforces these declarations — violations appear as HIGH/CRITICAL findings.
+
+### Custom Rulesets
+
+Create your own rules as YAML:
+
+```yaml
+rules:
+  - id: MY_NO_INTERNAL_URLS
+    pattern: "https://internal\\.corp\\.com"
+    severity: high
+    description: "References to internal URLs should not appear in extensions."
+    recommendation: "Use environment variables for internal endpoints."
+```
+
+Place in a folder, then: `clawcare scan . --ruleset ./my-rules`
+
+### Custom Adapters
+
+ClawCare supports custom adapters for scanning any AI agent platform. An adapter implements four methods:
+
+```python
+# my_adapter.py
+from clawcare.models import ExtensionRoot
+
+class MyAdapter:
+    name = "my_platform"
+    version = "0.1.0"
+    priority = 50
+
+    def detect(self, target_path: str) -> float:
+        """Return 0.0–1.0 confidence that this adapter applies."""
+        ...
+
+    def discover_roots(self, target_path: str) -> list[ExtensionRoot]:
+        """Return extension roots to scan."""
+        ...
+
+    def scan_scope(self, root: ExtensionRoot) -> dict:
+        """Return include/exclude globs for this root."""
+        return {
+            "include_globs": ["*.md", "*.py", "*.yml"],
+            "exclude_globs": [".git", "node_modules"],
+        }
+
+    def default_manifest(self, root: ExtensionRoot) -> str | None:
+        """Return path to clawcare.manifest.yml, or None."""
+        return None
+```
+
+Use it via import string:
+
+```bash
+clawcare scan path/ --adapter import:my_adapter:MyAdapter
+```
+
+Or register permanently via entry point in your `pyproject.toml`:
+
+```toml
+[project.entry-points."clawcare.adapters"]
+my_platform = "my_adapter:MyAdapter"
+```
+
+See [`clawcare/adapters/base.py`](clawcare/adapters/base.py) for the full protocol, or any of the [built-in adapters](clawcare/integrations/) for real examples.
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- name: Install ClawCare
+  run: pip install clawcare
+
+- name: Scan for malicious extensions
+  run: clawcare scan . --ci
+```
+
+Full workflow example: [ClawCare Demo CI](https://github.com/natechen/ClawCare-demo/blob/main/.github/workflows/clawcare.yml)
+
+## CLI Reference
+
+```
+clawcare scan <path> [OPTIONS]
+
+Options:
+  --ci                    CI mode (exit 2 on findings above threshold)
+  --fail-on SEVERITY      Minimum severity to block: critical|high|medium|low (default: high)
+  --block-local           Block locally too (default: warn only, exit 0)
+  --format FORMAT         Output format: text|json (default: text)
+  --json-out FILE         Write JSON report to file
+  --adapter NAME          Force a specific adapter (default: auto-detect)
+  --ruleset PATH          Additional rulesets (repeatable)
+  --exclude GLOB          Exclude glob patterns (repeatable)
+  --max-file-size-kb N    Skip files larger than N KB
+  --manifest MODE         Manifest enforcement: auto|skip|strict (default: auto)
+
+clawcare adapters list    List registered adapters
+```
+
+## Development
+
+```bash
+git clone https://github.com/natechen/ClawCare
+cd ClawCare
+make install     # install in dev mode with ruff + pytest
+make check       # lint + test (run before opening a PR)
+```
+
+Available make targets:
+
+| Command | What it does |
+|---------|-------------|
+| `make install` | Install in dev mode |
+| `make lint` | Run ruff linter |
+| `make format` | Auto-format code |
+| `make test` | Run pytest |
+| `make check` | Lint + test (pre-PR gate) |
+
+We use **GitHub Flow** — branch off `main`, open a PR, get a review, merge.
+
+## License
+
+[Apache 2.0](LICENSE)

clawcare-0.1.0/clawcare/__init__.py

@@ -0,0 +1,3 @@
+"""ClawCare — Guardian engine for agentic-tool extension supply-chain security."""
+
+__version__ = "0.1.0"

clawcare-0.1.0/clawcare/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter framework — protocol, registry, and selection logic."""

clawcare-0.1.0/clawcare/adapters/base.py

@@ -0,0 +1,42 @@
+"""Adapter protocol — the stable contract every adapter must satisfy."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from clawcare.models import ExtensionRoot
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """Pluggable adapter contract (§6.3 of design doc)."""
+
+    name: str
+    version: str
+    priority: int  # tie-break for auto-detect; higher wins
+
+    def detect(self, target_path: str) -> float:
+        """Return confidence 0.0–1.0 that this adapter applies.
+
+        Must be fast and side-effect free.
+        """
+        ...
+
+    def discover_roots(self, target_path: str) -> list[ExtensionRoot]:
+        """Return discovered extension roots under *target_path*."""
+        ...
+
+    def scan_scope(self, root: ExtensionRoot) -> dict:
+        """Return scan scope for *root*.
+
+        Expected keys:
+            include_globs: list[str]
+            exclude_globs: list[str]
+            max_file_size_kb: int  (optional override)
+            languages: list[str]   (optional hints)
+        """
+        ...
+
+    def default_manifest(self, root: ExtensionRoot) -> str | None:
+        """Return manifest path if adapter has conventions; else None."""
+        ...

clawcare-0.1.0/clawcare/adapters/registry.py

@@ -0,0 +1,86 @@
+"""Adapter registry — loading, registration, and selection."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+from clawcare.adapters.base import Adapter
+
+
+def _load_entry_point_adapters() -> list[Adapter]:
+    """Load adapters registered via the ``clawcare.adapters`` entry-point group."""
+    adapters: list[Adapter] = []
+    if sys.version_info >= (3, 12):
+        from importlib.metadata import entry_points
+        eps = entry_points(group="clawcare.adapters")
+    else:
+        from importlib.metadata import entry_points as _ep
+        all_eps = _ep()
+        eps = all_eps.get("clawcare.adapters", []) if isinstance(all_eps, dict) else all_eps.select(group="clawcare.adapters")
+    for ep in eps:
+        try:
+            cls = ep.load()
+            adapters.append(cls() if isinstance(cls, type) else cls)
+        except Exception:
+            pass  # skip broken adapters silently
+    return adapters
+
+
+def load_import_adapter(import_string: str) -> Adapter:
+    """Load an adapter from ``import:pkg.module:ClassName``.
+
+    The *import_string* is the part after ``import:``.
+    """
+    module_path, class_name = import_string.rsplit(":", 1)
+    mod = importlib.import_module(module_path)
+    cls = getattr(mod, class_name)
+    return cls() if isinstance(cls, type) else cls
+
+
+def load_adapters(adapter_spec: str = "auto") -> list[Adapter]:
+    """Return a list of candidate adapters for the given *adapter_spec*.
+
+    ``auto``       — entry-point adapters
+    ``<name>``     — entry-point adapters filtered to that name
+    ``import:...`` — single adapter from import string
+    """
+    if adapter_spec.startswith("import:"):
+        return [load_import_adapter(adapter_spec[len("import:"):])]
+
+    all_adapters = _load_entry_point_adapters()
+
+    if adapter_spec != "auto":
+        matched = [a for a in all_adapters if a.name == adapter_spec]
+        if not matched:
+            raise ValueError(f"No registered adapter named '{adapter_spec}'")
+        return matched
+
+    return all_adapters
+
+
+def select_adapter(
+    adapters: list[Adapter],
+    target_path: str,
+) -> Adapter | None:
+    """Pick the best adapter for *target_path* by confidence, with priority tie-break.
+
+    Returns ``None`` if all confidences are 0.0.
+    """
+    scored: list[tuple[float, int, Adapter]] = []
+    for a in adapters:
+        conf = a.detect(target_path)
+        if conf > 0.0:
+            scored.append((conf, a.priority, a))
+
+    if not scored:
+        return None
+
+    # highest confidence first, then highest priority
+    scored.sort(key=lambda t: (t[0], t[1]), reverse=True)
+    return scored[0][2]
+
+
+def list_registered_adapters() -> list[Adapter]:
+    """Return all entry-point-registered adapters (for ``adapters list``)."""
+    return _load_entry_point_adapters()