skill-security-scanner 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# skill-security-scanner
+
+> Static security scanner and linter for OpenClaw skill directories. Free tier. No config needed.
+
+[![npm version](https://img.shields.io/npm/v/skill-security-scanner)](https://www.npmjs.com/package/skill-security-scanner)
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `scan <skill>` | Security scan a single skill (default) |
+| `scan-all` | Security scan every skill in the project |
+| `lint <skill>` | Validate SKILL.md frontmatter schema |
+| `lint --all` | Validate every skill in the project |
+
+---
+
+## `scan` — Security Scanner
+
+```bash
+# By skill name — auto-discovered from anywhere in the project
+npx skill-security-scanner frontend-design
+npx skill-security-scanner clean-code
+
+# Or a full/relative path
+npx skill-security-scanner .agent/skills/frontend-design
+```
+
+The CLI walks up the directory tree to find `.agent/skills/<name>` automatically.
+
+### What It Scans
+
+| Check | Description | Risk |
+|---|---|---|
+| **Permissions** | `file_system:write`, `network:outbound`, `shell:execute` in YAML frontmatter | Med/High |
+| **Dangerous bins** | `curl`, `wget`, `ssh`, `bash`, etc. in `requires.bin` | High |
+| **Sensitive env vars** | Env vars with `key`, `secret`, `token`, `password` in name | Med |
+| **Code patterns** | `eval`, `exec`, `execSync`, network calls in source files | Med/High |
+| **Secret leaks** | OpenAI `sk-`, GitHub `ghp_`, AWS `AKIA`, hardcoded passwords | High |
+| **npm vulns** | `npm audit` for known CVEs (if `package.json` present) | Med/High |
+
+### Risk Scoring
+
+| Score | Meaning |
+|---|---|
+| 🟢 LOW | No significant risks detected |
+| 🟡 MED | Some concerns — review recommended |
+| 🔴 HIGH | Critical risks — block before deploy |
+
+### Scan Flags
+
+| Flag | Description |
+|---|---|
+| `--badge` | Print a Markdown shield badge (paste into your README) |
+| `--json` | JSON output for CI pipelines |
+
+```bash
+npx skill-security-scanner frontend-design --badge
+npx skill-security-scanner frontend-design --json
+```
+
+### Scan Output Example
+
+```
+🔍 Skill Security Scanner — voiceover-bot
+──────────────────────────────────────────────────
+Risk Score: 🚨 HIGH
+
+🚨 HIGH RISK (2)
+  • Requires dangerous binary: curl (network/exfil risk)
+  • eval/exec found in scripts/run.ts — remote code execution risk
+
+⚠️  MEDIUM RISK (1)
+  • Sensitive env var required: OPENAI_API_KEY
+```
+
+---
+
+## `scan-all` — Scan Every Skill
+
+```bash
+npx skill-security-scanner scan-all
+npx skill-security-scanner scan-all --json
+npx skill-security-scanner scan-all --fail-on med
+```
+
+### scan-all Flags
+
+| Flag | Description |
+|---|---|
+| `--json` | JSON array output |
+| `--fail-on <level>` | Exit 1 if any skill hits `low`/`med`/`high` (default: `high`) |
+| `--skip-audit` | Skip npm audit (auto-enabled when >5 skills found) |
+
+### scan-all Output Example
+
+```
+🔍 Skill Security Scanner — Project Scan (37 skills)
+────────────────────────────────────────────────────────────
+  🚨 HIGH   voiceover-bot
+          → [HIGH] eval/exec found in scripts/run.ts — remote code execution risk
+          → [MED]  Sensitive env var required: OPENAI_API_KEY
+
+  ✅ LOW    frontend-design
+  ✅ LOW    clean-code
+  ... (34 more)
+────────────────────────────────────────────────────────────
+  🚨 1 HIGH  ⚠️  0 MED  ✅ 36 LOW
+```
+
+---
+
+## `lint` — Schema Validator
+
+Validates SKILL.md frontmatter against the OpenClaw schema.
+
+```bash
+# Single skill
+npx skill-security-scanner lint frontend-design
+
+# All skills in the project
+npx skill-security-scanner lint --all
+
+# Fail on warnings too (strict CI mode)
+npx skill-security-scanner lint --all --strict
+```
+
+### What It Validates
+
+| Field | Rule |
+|---|---|
+| `name` | Required, string, ≥3 chars |
+| `description` | Required, string, ≥10 chars recommended |
+| `version` | Required, valid semver (`x.y.z`) |
+| `permissions` | Array of known OpenClaw permission scopes |
+| `requires.env/config/bin` | Must be arrays if present |
+| Body content | Warns if <50 chars |
+
+### Lint Flags
+
+| Flag | Description |
+|---|---|
+| `--all` | Lint every skill in the project |
+| `--strict` | Treat warnings as errors (exit 1) |
+| `--json` | JSON output |
+
+### Lint Output Example
+
+```
+� Lint — voiceover-bot
+──────────────────────────────────────────────────
+Status: ❌ FAIL
+
+Errors (2)
+  • [description] Missing required field
+  • [version] Missing required field
+
+Warnings (1)
+  • [SKILL.md body] Skill body is very short — consider adding usage examples
+```
+
+---
+
+## Install Globally
+
+```bash
+npm install -g skill-security-scanner
+
+# Then from anywhere in your project:
+skill-security-scanner frontend-design
+skill-security-scanner lint --all
+skill-security-scanner scan-all
+```
+
+## CI / GitHub Actions
+
+```yaml
+- name: Lint skills
+  run: npx skill-security-scanner lint --all
+
+- name: Security scan all skills
+  run: npx skill-security-scanner scan-all --fail-on high --json
+```
+
+## Upgrade
+
+Free tier covers static analysis + linting. For **dynamic sandboxing**, **GitHub org scans**, and **CI dashboards**:
+
+👉 [skill-security.com](https://skill-security.com) — 7-day free trial

package/TODO.md

@@ -0,0 +1,57 @@
+# skill-security-scanner — CLI Roadmap
+
+> Free tier features only. SaaS (dynamic analysis, GitHub Actions, CI dashboards) tracked separately.
+
+---
+
+## 🗂️ Skill Metadata & Quality
+
+- [x] **`lint <skill>`** — Validate SKILL.md frontmatter against OpenClaw schema (required fields: `name`, `description`, `version`). Exit 1 on missing fields.
+- [ ] **`info <skill>`** — Pretty-print parsed frontmatter (permissions, bins, env vars, command-dispatch). Useful for debugging what the scanner actually sees.
+- [ ] **`diff <skill-a> <skill-b>`** — Side-by-side comparison of permissions, requires.bin, and risk scores between two skills or two versions.
+- [ ] **`stats`** — Project-wide health snapshot: most common permissions, most used bins, avg finding count per skill, riskiest skill.
+
+---
+
+## 🔍 Deeper Static Analysis
+
+- [ ] **Entropy-based secret detection** — Flag high-entropy strings that look like secrets even without a known prefix (e.g. base64 blobs, random hex). Supplement existing regex checks.
+- [ ] **License check** — Scan `package.json` / `requirements.txt` for non-commercial or copyleft licenses (GPL, AGPL). Flag as MED risk.
+- [ ] **Dead code detection** — Find files in the skill dir never referenced by any other file. Flags bloat and unnecessary attack surface.
+- [ ] **Import graph** — List all external packages a skill actually imports and flag ones not declared in frontmatter `requires`.
+- [ ] **`--depth <n>`** flag — Control how many levels deep the code scanner recurses (default: 3).
+
+---
+
+## 🛠️ Developer UX
+
+- [ ] **`fix --dry-run`** — Suggest auto-fixable issues with diffs shown. E.g. overly broad `file_system:*` → suggest `file_system:read`.
+- [ ] **`watch <skill>`** — Re-scan on file save. Live feedback while authoring a skill.
+- [ ] **`init`** — Scaffold a compliant `SKILL.md` with correct frontmatter structure and placeholder values.
+- [ ] **`--ignore <rule-id>`** — Suppress specific finding by ID inline (e.g. `# sss-ignore: exec-pattern` in source).
+- [ ] **`.sss.yaml` config file** — Project-level config: ignored rules, custom dangerous bins list, custom secret regex patterns, default `--fail-on` level.
+
+---
+
+## 📊 Reporting & Output
+
+- [ ] **`--output <file>`** — Write full report to disk. Support `.json`, `.md`, and `.sarif` extensions (auto-detected from extension).
+- [ ] **Markdown report** — `scan-all --output report.md` generates a formatted table suitable for pasting into PR descriptions.
+- [ ] **SARIF output** — `--format sarif` for GitHub Code Scanning and VS Code Problems panel integration.
+
+---
+
+## Priority Order
+
+| Priority | Feature | Effort |
+|---|---|---|
+| 🔴 1 | `lint` command | Low |
+| 🔴 2 | `--ignore` + `.sss.yaml` config | Medium |
+| 🟡 3 | Entropy-based secret detection | Medium |
+| 🟡 4 | `--output report.md` | Low |
+| 🟢 5 | `diff` command | Medium |
+| 🟢 6 | `stats` command | Low |
+| 🟢 7 | `watch` mode | Medium |
+| ⚪ 8 | Import graph | High |
+| ⚪ 9 | Dead code detection | High |
+| ⚪ 10 | SARIF output | Medium |

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}