@clawmaster/skillguard-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cydiar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+<p align="center">
+  <h1 align="center">SkillGuard CLI</h1>
+  <p align="center"><strong>Security Audit CLI for AI Agent Skills</strong></p>
+  <p align="center">
+    The command-line version of <a href="https://github.com/clawmaster-ai/skill-guard">SkillGuard</a> — zero infrastructure, same engine.
+  </p>
+  <p align="center">
+    10 Dimensions · 109 Rules · A–F Risk Grading · Token Cost Estimation
+  </p>
+  <p align="center">
+    <a href="#quick-start">Quick Start</a> ·
+    <a href="#features">Features</a> ·
+    <a href="#security-dimensions">Dimensions</a> ·
+    <a href="#architecture">Architecture</a> ·
+    <a href="#cli-reference">CLI Reference</a> ·
+    <a href="#claude-code-skills">Skills</a>
+  </p>
+</p>
+
+---
+
+## What is SkillGuard CLI?
+
+**SkillGuard CLI** is the standalone command-line version of [SkillGuard](https://github.com/clawmaster-ai/skill-guard), the security audit platform for AI agent skills. While the original SkillGuard requires FastAPI, Celery, Redis, and SQLite, the CLI version packages the same scanning engine into a single `npx` command with **zero infrastructure dependencies**.
+
+Paste a GitHub or [ClawHub](https://clawhub.ai) URL — get a full security report in your terminal.
+
+Audit methodology is based on **OWASP LLM Top 10**, **SLSA**, and **Google SAIF**.
+
+## Quick Start
+
+```bash
+# Scan a GitHub skill repository
+npx @clawmaster/skillguard-cli https://github.com/user/my-skill
+
+# Scan a local skill directory
+npx @clawmaster/skillguard-cli ./path/to/skill
+
+# Scan a ClawHub skill
+npx @clawmaster/skillguard-cli https://clawhub.ai/author/skill-name
+
+# Scan all skills in a marketplace directory
+npx @clawmaster/skillguard-cli ./marketplace --all
+```
+
+## Features
+
+### 🔍 Static Analysis
+Pattern-based scanning across **10 security dimensions** with **109 audit rules** (67 built-in + 42 configurable). Covers OWASP LLM Top 10, SLSA supply chain, and Google SAIF framework — from prompt injection to license compliance, every risk surface is checked.
+
+### 📊 A–F Risk Grading
+One glance, one grade. Every skill gets a clear **A–F letter rating** with per-dimension score breakdown, severity distribution, and actionable remediation in both Chinese and English.
+
+### 💰 Token Cost Estimation
+4-level token analysis (**L1** SKILL.md → **L2** eager/lazy references → **L3** all files) with multi-model cost projections across Claude Sonnet, Claude Opus, Gemini, and GPT. Know exactly how much a skill costs before you install it.
+
+### 📦 Multi-Skill Detection
+Drop a marketplace directory or monorepo — SkillGuard CLI automatically discovers every skill inside, scans them all, and generates an aggregated summary report.
+
+### 🌐 Bilingual Reports
+Full **CN/EN** remediation guidance for every finding. Switch with `--lang zh` or `--lang en`.
+
+### ⚙️ Configurable Rules
+YAML-based rule engine — enable, disable, adjust severity, or add whitelist entries. Ship your own security policy alongside the default 42-rule set with `--rules`.
+
+### 📄 Multiple Output Formats
+Terminal (colored), JSON (machine-readable), and Markdown (documentation-friendly). Pick the right format for your workflow.
+
+## Security Dimensions
+
+| # | Dimension | Coverage |
+|---|-----------|----------|
+| 1 | Prompt Injection | Direct/indirect injection patterns, zero-width chars, hidden instructions |
+| 2 | Permission Escalation | Missing `allowed-tools`, sudo, chmod 777, dangerous tool combinations |
+| 3 | Data Exfiltration | Credential theft, env leaks, outbound HTTP, webhook tunneling |
+| 4 | Destructive Operations | Path traversal, sensitive file deletion, git force push |
+| 5 | Supply Chain | Pipe-to-shell, unpinned dependencies, unverified Docker images |
+| 6 | Code Security | Arbitrary eval, shell injection, SQL injection, XSS |
+| 7 | Credential Leaks | Hardcoded API keys, JWT tokens, PEM private keys |
+| 8 | Least Privilege | Missing tool declarations, shell + network + write combos |
+| 9 | License Compliance | Proprietary restrictions, non-commercial clauses |
+| 10 | Resource Abuse | Infinite loops, excessive retries, recursive functions without base case |
+
+## Architecture
+
+```mermaid
+flowchart TD
+    CLI((CLI — npx @clawmaster/skillguard-cli)) -->|"URL or Path"| Fetcher[Repo Fetcher]
+    Fetcher -->|"GitHub Tarball / Git Clone"| GitHub[(GitHub)]
+    Fetcher -->|"ClawHub ZIP API"| ClawHub[(ClawHub)]
+    Fetcher -->|"Local Path"| Local[(Local Dir)]
+    Fetcher --> Scanner[Static Scan Engine — 10 Dimensions]
+    Scanner --> Rules[YAML Rules Engine — 42 Configurable]
+    Scanner --> Token[Token Estimator — L1/L2/L3]
+    Token --> Cost[Multi-Model Cost Calculator]
+    Scanner --> Renderer[Output Renderer]
+    Cost --> Renderer
+    Renderer -->|"--json"| JSON[JSON Output]
+    Renderer -->|"--md"| Markdown[Markdown Report]
+    Renderer -->|"default"| Terminal[Terminal — Colored]
+
+classDef startEndStyle fill:#e8f5e8,stroke:#4caf50,stroke-width:3px,color:#000
+classDef processStyle fill:#e3f2fd,stroke:#2196f3,stroke-width:2px,color:#000
+classDef decisionStyle fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#000
+classDef dataStyle fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000
+classDef outputStyle fill:#fce4ec,stroke:#e91e63,stroke-width:2px,color:#000
+
+class CLI startEndStyle
+class Fetcher,Scanner,Rules,Token,Cost processStyle
+class GitHub,ClawHub,Local dataStyle
+class Renderer decisionStyle
+class JSON,Markdown,Terminal outputStyle
+```
+
+### How it differs from SkillGuard
+
+| | SkillGuard (Web) | SkillGuard CLI |
+|--|------------------|----------------|
+| Interface | Web UI + WebSocket | Terminal |
+| Infrastructure | FastAPI + Celery + Redis + SQLite | None — single `npx` command |
+| Deep Scan | LLM-driven (Phase 2 in CLI) | Stubs ready, coming soon |
+| Output | HTML reports | Terminal, JSON, Markdown |
+| Distribution | Self-hosted | `npm install -g @clawmaster/skillguard-cli` |
+| Scan engine | Same 109 rules | Same 109 rules |
+
+## CLI Reference
+
+```
+skillguard <target> [options]
+
+Arguments:
+  target                    Local directory, GitHub URL, or ClawHub URL
+
+Options:
+  --all                     Scan all skill subdirectories (marketplace mode)
+  --json [file]             Output as JSON (stdout or file)
+  --md <file>               Output as Markdown report
+  --rules <path>            Custom rules.yaml file
+  --min-level <A-F>         Filter by minimum risk level (default: A)
+  --min-severity <severity> Filter by minimum severity (default: INFO)
+  --lang <en|zh>            Output language (default: en)
+  -V, --version             Show version
+  -h, --help                Show help
+```
+
+### Examples
+
+```bash
+# Quick audit with terminal output
+npx @clawmaster/skillguard-cli https://github.com/anthropics/claude-code
+
+# JSON report to file
+npx @clawmaster/skillguard-cli ./my-skill --json report.json
+
+# Markdown report
+npx @clawmaster/skillguard-cli ./my-skill --md audit-report.md
+
+# Chinese remediation text
+npx @clawmaster/skillguard-cli ./my-skill --lang zh
+
+# Only show HIGH and CRITICAL findings
+npx @clawmaster/skillguard-cli ./my-skill --min-severity HIGH
+
+# Marketplace scan with custom rules
+npx @clawmaster/skillguard-cli ./skills-directory --all --rules custom-rules.yaml
+```
+
+## Claude Code Skills
+
+SkillGuard CLI ships with three **Claude Code Skills** for integrated usage:
+
+| Skill | Description |
+|-------|-------------|
+| `skills/audit/` | Run security audits directly from Claude Code |
+| `skills/explain-report/` | Explain findings, assess real risk vs false positives |
+| `skills/suggest-fixes/` | Generate concrete code fixes for findings |
+
+## Tech Stack
+
+| Component | Technology | Role |
+|-----------|-----------|------|
+| Language | **TypeScript** | Type-safe scanning engine |
+| Runtime | **Node.js ≥ 18** | ESM module system |
+| CLI Framework | **Commander** | Argument parsing and help generation |
+| Rule Engine | **js-yaml** | 109 configurable rules in YAML format |
+| Terminal Output | **chalk** | Colored severity badges and risk grades |
+| GitHub Fetcher | **tar** | Tarball download + extraction |
+| ClawHub Fetcher | **unzipper** | ZIP download + extraction |
+| Token Estimator | Built-in | 4-level (L1/L2-eager/L2-lazy/L3) token & cost projection |
+| Build | **tsup** | Single-file ESM bundle (85KB) |
+| Tests | **vitest** | Fast unit and integration testing |
+
+## Versioning
+
+This project follows [Pride Versioning](https://pridever.org/) (`PROUD.DEFAULT.SHAME`):
+
+- **PROUD** — bumped when releasing features we're genuinely proud of
+- **DEFAULT** — bumped for ordinary, acceptable releases
+- **SHAME** — bumped when fixing embarrassing bugs
+
+Current version: **0.1.0**
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+You are free to use, modify, and distribute SkillGuard CLI in both personal and commercial projects. See the [LICENSE](LICENSE) file for full terms.
+
+---
+
+<p align="center">
+  <sub>CLI version of <a href="https://github.com/clawmaster-ai/skill-guard">SkillGuard</a> · Built for the AI Agent ecosystem · <a href="https://clawhub.ai">ClawHub</a></sub>
+</p>