@clawmaster/skillguard-cli 0.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@clawmaster/skillguard-cli",
+  "version": "0.1.0",
+  "description": "Security audit CLI for AI agent skills — scans 10 dimensions with 109 rules",
+  "type": "module",
+  "bin": {
+    "skillguard": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "rules",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "security",
+    "audit",
+    "claude-code",
+    "skill",
+    "ai-agent",
+    "owasp"
+  ],
+  "author": "Cydiar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clawmaster-ai/skillguard-cli.git"
+  },
+  "homepage": "https://github.com/clawmaster-ai/skillguard-cli#readme",
+  "bugs": {
+    "url": "https://github.com/clawmaster-ai/skillguard-cli/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0",
+    "tar": "^7.4.0",
+    "unzipper": "^0.12.3"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@types/unzipper": "^0.10.10",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/rules/rules.yaml

@@ -0,0 +1,303 @@
+# SkillGuard 可配置规则 (Configurable Rules)
+# 用户可修改此文件来调整规则行为 — 也可通过 /rules 页面可视化编辑
+#
+# enabled:   true/false  — 开关（false 则跳过该规则）
+# severity:  CRITICAL / HIGH / MEDIUM / LOW / INFO  — 覆盖严重级别
+# whitelist: []  — 白名单（命中任一条则跳过），支持子字符串匹配
+
+data_exfiltration:
+- id: DE-01
+  pattern: \.env\b
+  description: Reads .env file (may contain secrets)
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: DE-02
+  pattern: ~/\.ssh/
+  description: Accesses SSH directory
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-03
+  pattern: /etc/passwd\b
+  description: Reads /etc/passwd
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-04
+  pattern: /etc/shadow\b
+  description: Reads /etc/shadow
+  severity: CRITICAL
+  enabled: true
+  whitelist: []
+- id: DE-05
+  pattern: ~/.aws/credentials
+  description: Reads AWS credentials
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-06
+  pattern: ~/.kube/config
+  description: Reads Kubernetes config
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-07
+  pattern: credentials\.json
+  description: Reads credentials file
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: DE-08
+  pattern: \.claude/settings
+  description: Reads Claude settings
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: DE-09
+  pattern: curl\s+.*-X\s*POST\b
+  description: curl POST - potential data exfiltration
+  severity: HIGH
+  enabled: true
+  whitelist:
+  - api.github.com
+  - registry.npmjs.org
+- id: DE-10
+  pattern: curl\s+.*--data\b
+  description: curl with data payload
+  severity: HIGH
+  enabled: true
+  whitelist:
+  - api.github.com
+- id: DE-11
+  pattern: requests\.post\s*\(
+  description: Python requests.post - outbound data
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-12
+  pattern: fetch\s*\([^)]*method\s*:\s*["']POST["']
+  description: fetch POST - outbound data
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-13
+  pattern: urllib\.request\.urlopen
+  description: urllib outbound request
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: DE-14
+  pattern: http\.client\.HTTP
+  description: http.client outbound connection
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: DE-15
+  pattern: webhook
+  description: Webhook URL reference
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: DE-16
+  pattern: ngrok
+  description: ngrok tunnel - external exposure
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-17
+  pattern: bigquery
+  description: URL pointing to data collection/analytics endpoint
+  severity: HIGH
+  enabled: true
+  whitelist: []
+- id: DE-18
+  pattern: (?:analytics|telemetry|tracking|collect)
+  description: URL pointing to data collection/analytics endpoint
+  severity: HIGH
+  enabled: true
+  whitelist: []
+supply_chain:
+- id: SC-01
+  pattern: curl\s+[^|]*\|\s*(bash|sh|python|perl)\b
+  description: 'Pipe-to-shell: curl | bash - remote code execution'
+  severity: CRITICAL
+  enabled: true
+  whitelist: []
+- id: SC-02
+  pattern: wget\s+[^|]*\|\s*(bash|sh|python|perl)\b
+  description: 'Pipe-to-shell: wget | sh - remote code execution'
+  severity: CRITICAL
+  enabled: true
+  whitelist: []
+- id: SC-03
+  pattern: curl\s+.*\|\s*sudo\b
+  description: 'Pipe-to-sudo: curl | sudo - elevated remote execution'
+  severity: CRITICAL
+  enabled: true
+  whitelist: []
+- id: SC-04
+  pattern: git\s+clone\s+
+  description: git clone - pulls external code
+  severity: MEDIUM
+  enabled: true
+  whitelist:
+  - github.com/anthropics
+  - github.com/modelcontextprotocol
+- id: SC-05
+  pattern: pip\s+install\s+(?!.*==)(?!.*>=)(?!.*~=)(\S+)
+  description: pip install without version pinning
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: SC-06
+  pattern: npm\s+install\s+(?!.*@\d)
+  description: npm install without version pinning
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: SC-07
+  pattern: go\s+get\s+
+  description: go get - pulls external dependency
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: SC-08
+  pattern: ^FROM\s+\S+(?!.*@sha256:)
+  description: Dockerfile FROM without digest pinning
+  severity: LOW
+  enabled: true
+  whitelist:
+  - 'python:'
+  - 'node:'
+  - alpine
+resource_abuse:
+- id: RA-01
+  pattern: 'while\s+True\s*:'
+  description: while True loop - potential infinite loop
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: RA-02
+  pattern: 'while\s+1\s*:'
+  description: while 1 loop - potential infinite loop
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: RA-03
+  pattern: while\s*\(\s*true\s*\)
+  description: while(true) loop - potential infinite loop
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: RA-04
+  pattern: for\s*\(\s*;\s*;\s*\)
+  description: for(;;) infinite loop
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: RA-05
+  pattern: retmax\s*=\s*\d{5,}
+  description: Very large retmax value - excessive data fetch
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: RA-06
+  pattern: limit\s*=\s*\d{5,}
+  description: Very large limit value
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: RA-07
+  pattern: time\.sleep\s*\(\s*0\s*\)
+  description: sleep(0) in potential busy loop
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: RA-08
+  pattern: retry.*=\s*(?:True|-1|999|float\(["']inf)
+  description: Unlimited/excessive retry configuration
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+license_compliance:
+- id: LC-01
+  pattern: proprietary\s+and\s+confidential
+  description: Proprietary and confidential license
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: LC-02
+  pattern: all\s+rights\s+reserved
+  description: All rights reserved notice
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: LC-03
+  pattern: unauthorized\s+copying.*strictly\s+prohibited
+  description: Copying prohibited notice
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: LC-04
+  pattern: non-?commercial
+  description: Non-commercial license restriction
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: LC-05
+  pattern: \bbilling\b|\bsubscription\b|\benterprise\b|\bpaid\s+(?:plan|tier|api)\b
+  description: References commercial service (billing/subscription/enterprise/paid)
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: LC-06
+  pattern: \bKEGG\b|\bBenchling\b|\bSnowflake\b
+  description: Known commercial/academic-license platform referenced
+  severity: INFO
+  enabled: true
+  whitelist: []
+- id: LC-07
+  pattern: \bBigQuery\b
+  description: Google BigQuery (commercial service, data collection risk)
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+least_privilege:
+- id: LP-01
+  pattern: missing allowed-tools
+  description: No allowed-tools declared in frontmatter - implicit all-tools access
+  severity: LOW
+  enabled: true
+  whitelist: []
+- id: LP-02
+  pattern: 'allowed-tools: shell'
+  description: Shell access declared in allowed-tools
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: LP-03
+  pattern: shell + network + write
+  description: 'Dangerous tool combination: shell + network + file write access'
+  severity: HIGH
+  enabled: true
+  whitelist: []
+prompt_injection_auxiliary:
+- id: PI-AUX-01
+  pattern: '[\u200b\u200c\u200d\ufeff\u2060]'
+  description: Zero-width character detected (possible steganographic injection)
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: PI-AUX-02
+  pattern: '[A-Za-z0-9+/]{200,}={0,2}'
+  description: Long base64-like string - may hide injected payload
+  severity: MEDIUM
+  enabled: true
+  whitelist: []
+- id: PI-AUX-03
+  pattern: <!--.*(?:instruction|ignore|override|system prompt|you must|you are now).*-->
+  description: Hidden instruction detected in HTML comment
+  severity: HIGH
+  enabled: true
+  whitelist: []

package/skills/audit/SKILL.md

@@ -0,0 +1,88 @@
+---
+description: Run SkillGuard security audit on AI agent skills — scans 10 dimensions with 109 rules based on OWASP LLM Top 10, SLSA, and Google SAIF
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+---
+
+# SkillGuard Audit
+
+Security audit tool for Claude Code Skills and AI agent plugins. Scans across 10 security dimensions with 109 detection rules, providing A–F risk grading and token cost estimation.
+
+## Quick Start
+
+```bash
+# Scan a local skill directory
+npx skillguard /path/to/skill
+
+# Scan a GitHub repository
+npx skillguard https://github.com/owner/repo
+
+# Scan a ClawHub skill
+npx skillguard https://clawhub.ai/author/skill-name
+
+# Scan all skills in a marketplace directory
+npx skillguard /path/to/marketplace --all
+```
+
+## Output Formats
+
+```bash
+# Terminal output (default) — colored, human-readable
+npx skillguard <target>
+
+# JSON output to stdout
+npx skillguard <target> --json
+
+# JSON output to file
+npx skillguard <target> --json report.json
+
+# Markdown report
+npx skillguard <target> --md report.md
+
+# Chinese language output
+npx skillguard <target> --lang zh
+```
+
+## Options
+
+- `--all` — Scan all skill subdirectories (marketplace mode)
+- `--json [file]` — Output as JSON (to stdout or file)
+- `--md <file>` — Output as Markdown report
+- `--rules <path>` — Custom rules.yaml file
+- `--min-level <A-F>` — Filter output by minimum risk level
+- `--min-severity <severity>` — Filter by minimum severity (CRITICAL, HIGH, MEDIUM, LOW, INFO)
+- `--lang <en|zh>` — Output language (default: en)
+
+## 10 Security Dimensions
+
+1. **Prompt Injection** — Direct/indirect injection patterns, zero-width chars, base64 payloads
+2. **Permission Escalation** — Sandbox bypass, sudo, chmod 777, dangerous tool combos
+3. **Data Exfiltration** — Credential theft, env leaks, outbound HTTP
+4. **Destructive Operations** — rm -rf, DROP TABLE, git reset --hard
+5. **Supply Chain** — Pipe-to-shell, unpinned deps, Docker without digest
+6. **Code Security** — eval(), shell=True, SQL injection, XSS
+7. **Credential Leaks** — Hardcoded API keys, JWT tokens, PEM keys
+8. **Least Privilege** — Missing allowed-tools, dangerous tool combinations
+9. **License Compliance** — Proprietary restrictions, non-commercial clauses
+10. **Resource Abuse** — Infinite loops, excessive retries, unbounded fetching
+
+## Risk Grading
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| A | 0–9 | Safe |
+| B | 10–29 | Acceptable |
+| C | 30–49 | Warning |
+| D | 50–69 | Unsafe |
+| F | 70–100 | Dangerous |
+
+## Example Workflow
+
+When a user asks to audit a skill:
+
+1. Run `npx skillguard <target>` to get the terminal report
+2. If the user wants details, use `--json report.json` and read the JSON file
+3. Explain findings in context — what each risk means and whether it's a real threat
+4. Suggest concrete fixes using the remediation guidance in each finding

package/skills/explain-report/SKILL.md

@@ -0,0 +1,52 @@
+---
+description: Explain a SkillGuard security audit report — analyze findings, assess real risk vs false positives, and provide context
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# Explain SkillGuard Report
+
+Reads a SkillGuard JSON report and explains each finding in context, helping users understand what the risks actually mean and which findings need attention vs which are false positives.
+
+## Usage
+
+1. First generate a JSON report:
+   ```bash
+   npx skillguard <target> --json report.json
+   ```
+
+2. Then ask to explain the report — read `report.json` and analyze each finding.
+
+## How to Analyze
+
+For each finding, evaluate:
+
+1. **Context** — Is this pattern in actual executable code, or in documentation/comments?
+2. **Intent** — Is the pattern used for a legitimate purpose (e.g., `eval()` in a build tool)?
+3. **Scope** — Is the finding isolated or part of a broader pattern (e.g., multiple exfiltration signals)?
+4. **Severity** — Does the assigned severity match the actual risk given the context?
+
+### Common False Positives
+
+- `eval()` in documentation explaining what NOT to do
+- API key patterns in `.env.example` with placeholder values
+- `rm -rf` in cleanup scripts with proper path validation
+- `sudo` in installation instructions (README)
+- `shell=True` with hardcoded safe commands (no user input)
+
+### Red Flags That Need Attention
+
+- Combined signals: env var reading + outbound HTTP in same skill
+- `dangerouslyDisableSandbox` — almost always a real risk
+- Base64-encoded strings in markdown files (possible payload hiding)
+- Missing `allowed-tools` with shell access patterns in code
+
+## Output Format
+
+For each finding group by dimension, explain:
+- What was detected and why it matters
+- Whether it's likely a real risk or false positive
+- What action (if any) the user should take

package/skills/suggest-fixes/SKILL.md

@@ -0,0 +1,82 @@
+---
+description: Suggest concrete code fixes for SkillGuard security findings — generate remediation patches
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+---
+
+# Suggest Fixes for SkillGuard Findings
+
+Reads SkillGuard scan findings and generates concrete code fixes. Can either suggest fixes or directly apply them with user approval.
+
+## Usage
+
+1. Generate a JSON report:
+   ```bash
+   npx skillguard <target> --json report.json
+   ```
+
+2. Ask to fix the findings. Read the report and the source files to generate patches.
+
+## Fix Strategies by Dimension
+
+### Prompt Injection
+- Remove injection phrases from prompts
+- Use structured prompt templates instead of string concatenation
+- Remove zero-width characters with text sanitization
+
+### Permission Escalation
+- Remove `dangerouslyDisableSandbox` — run in sandbox
+- Replace `sudo` with user-level operations
+- Change `chmod 777` to `chmod 755` or `644`
+- Add `allowed-tools` to SKILL.md frontmatter
+
+### Data Exfiltration
+- Isolate env var reads from network requests
+- Add URL allowlists for outbound HTTP
+- Remove direct .env file reading — use injected env vars
+
+### Destructive Operations
+- Add path allowlist validation before `rm -rf`
+- Replace `git push --force` with `--force-with-lease`
+- Add confirmation prompts before destructive ops
+
+### Supply Chain
+- Pin dependency versions: `package@1.2.3` instead of `package`
+- Replace `curl | bash` with download-then-review-then-execute
+- Add `@sha256:` digests to Docker FROM statements
+
+### Code Security
+- Replace `shell=True` with `shell=False` and argument lists
+- Replace `eval()` with `JSON.parse()` or safe alternatives
+- Use parameterized SQL queries instead of f-strings
+
+### Credential Leaks
+- Move hardcoded secrets to environment variables
+- Add `.env` to `.gitignore`
+- Replace hardcoded API keys with `process.env.KEY_NAME`
+
+### Least Privilege
+- Add `allowed-tools` frontmatter listing only needed tools
+- Split skills with shell+network+write into focused sub-skills
+
+### License Compliance
+- Check dependency license compatibility
+- Add license declarations to SKILL.md frontmatter
+
+### Resource Abuse
+- Add `maxIterations` or timeout to loops
+- Set reasonable retry limits with exponential backoff
+- Add recursion depth limits
+
+## Workflow
+
+1. Read the JSON report to identify findings
+2. Read each affected source file
+3. For each finding, propose a minimal, targeted fix
+4. Apply fixes with Edit tool (with user approval)
+5. Re-run `npx skillguard <target>` to verify the fix reduced the risk score