skillsio 1.0.1 → 1.1.1

package/README.md

@@ -14,8 +14,8 @@ security gate so you can still move fast without running untrusted code.
 
 ## What It Does
 
-Every `skillsio add` command runs a local security scan **before** anything is installed. The scanner applies ~52 regex
-rules derived from the Snyk and ClawHavoc research, organized into 8 threat categories:
+Every `skillsio add` command runs a local security scan **before** anything is installed. The scanner applies ~81 regex
+rules and a correlation engine derived from the Snyk and ClawHavoc research, organized into 8 threat categories:
 
 | Category | What it catches |
 | --- | --- |
@@ -81,17 +81,111 @@ VT_API_KEY=YOUR_API_KEY npx skillsio add owner/repo
 
 `--vt-key` flag takes precedence over `VT_API_KEY` env var.
 
+### External Rules
+
+You can extend the built-in scanner with your own rules using the `--rules` flag. This is useful for enforcing
+organization-specific policies — for example, blocking references to internal infrastructure or flagging deprecated
+tools.
+
+Rules are defined in JSON files with a simple format:
+
+```json
+{
+  "rules": [
+    {
+      "id": "no-internal-api",
+      "severity": "critical",
+      "description": "References internal API — may leak infrastructure details",
+      "pattern": "https?://internal\\.company\\.com",
+      "flags": "i"
+    },
+    {
+      "id": "no-sudo",
+      "severity": "high",
+      "description": "Skill should not require sudo access",
+      "pattern": "\\bsudo\\s+"
+    }
+  ]
+}
+```
+
+Each rule requires `id`, `severity` (`critical`/`high`/`medium`/`low`/`info`), `description`, and `pattern` (a regex
+string). The optional `flags` field defaults to `"i"` (case-insensitive).
+
+```bash
+# Load rules from a single file
+npx skillsio add owner/repo --rules ./my-rules.json
+
+# Load all .json rule files from a directory
+npx skillsio add owner/repo --rules ./rules/
+```
+
+External rules are applied **in addition to** the built-in ~81 rules — they never replace them. Findings from external
+rules follow the same severity-based prompt flow as built-in findings.
+
+See [docs/EXTERNAL-RULES.md](docs/EXTERNAL-RULES.md) for the full format reference, more examples, and tips for writing
+rules.
+
+### Deep Taint Analysis (`--deep-scan`)
+
+Regex rules detect individual dangerous patterns, but sophisticated attacks hide data flows across variables and
+functions. The `--deep-scan` flag enables a lightweight taint analysis engine that tracks how data moves from
+**sources** (environment variables, credential files) through variable assignments to **sinks** (network calls, exec,
+file writes).
+
+```bash
+npx skillsio add owner/repo --deep-scan
+```
+
+What it catches that regex cannot:
+
+```python
+# Variable-mediated exfiltration — regex sees the pieces but can't link them
+key = os.environ["SECRET"]        # source: env-access
+encoded = b64encode(key)          # taint propagates through assignment
+payload = json.dumps(encoded)     # ...and another hop
+requests.post(url, data=payload)  # sink: network  →  deep-env-access-to-network (critical)
+```
+
+```python
+# getattr trick — regex misses the source entirely
+env = getattr(os, 'environ')     # source: getattr-trick (evades os.environ regex)
+data = str(env)
+requests.post(url, data=data)    # → deep-getattr-trick-to-network (high)
+```
+
+```python
+# Cross-file attack — collector.py harvests, exfil.py sends
+# collector.py                    # exfil.py
+import os                         # from .collector import data
+secrets = os.environ.copy()       # requests.post(url, data=payload)
+                                  # → deep-cross-env-access-to-network (critical)
+```
+
+The analysis covers Python (`.py`) and JavaScript/TypeScript (`.js`, `.ts`) files. It adds zero dependencies — the
+tokenizer is regex-based, not AST-based, keeping the bundle small. See [docs/deep-scan.md](docs/deep-scan.md) for
+architecture details.
+
+Deep scan findings appear alongside regex findings in the same severity-based prompt. All cross-file flows are
+automatically classified as critical.
+
 ## Quick Start
 
 ```bash
 # Install a skill (scanned automatically)
 npx skillsio add vercel-labs/agent-skills
 
+# Enable deep taint analysis for Python/JS/TS files
+npx skillsio add owner/repo --deep-scan
+
 # Skip the scan if you trust the source
 npx skillsio add vercel-labs/agent-skills --skip-scan
 
 # Scan with VirusTotal threat intelligence
 VT_API_KEY=xxx npx skillsio add owner/repo
+
+# Scan with custom organization rules
+npx skillsio add owner/repo --rules ./company-rules.json
 ```
 
 ## CLI Reference
@@ -116,6 +210,8 @@ npx skillsio add ./my-local-skills                   # Local path
 | `-y, --yes` | Skip confirmation prompts |
 | `--all` | Install all skills to all agents without prompts |
 | `--skip-scan` | Skip the security scan before installation |
+| `--rules <path>` | Load additional scan rules from a JSON file or directory (see [External Rules](#external-rules)) |
+| `--deep-scan` | Enable deep taint analysis on Python/JS/TS files |
 | `--vt-key <key>` | VirusTotal API key for additional threat intelligence |
 | `--full-depth` | Search all subdirectories even when a root SKILL.md exists |
 
@@ -146,21 +242,21 @@ Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [35 more](#su
 <!-- supported-agents:start -->
 | Agent | `--agent` | Project Path | Global Path |
 |-------|-----------|--------------|-------------|
-| Amp, Kimi Code CLI | `amp`, `kimi-cli` | `.agents/skills/` | `~/.config/agents/skills/` |
+| Amp, Kimi Code CLI, Replit | `amp`, `kimi-cli`, `replit` | `.agents/skills/` | `~/.config/agents/skills/` |
 | Antigravity | `antigravity` | `.agent/skills/` | `~/.gemini/antigravity/skills/` |
-| Augment | `augment` | `.augment/rules/` | `~/.augment/rules/` |
+| Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
 | Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
 | OpenClaw | `openclaw` | `skills/` | `~/.moltbot/skills/` |
 | Cline | `cline` | `.cline/skills/` | `~/.cline/skills/` |
 | CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
-| Codex | `codex` | `.codex/skills/` | `~/.codex/skills/` |
+| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
 | Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
 | Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
 | Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
 | Cursor | `cursor` | `.cursor/skills/` | `~/.cursor/skills/` |
 | Droid | `droid` | `.factory/skills/` | `~/.factory/skills/` |
-| Gemini CLI | `gemini-cli` | `.gemini/skills/` | `~/.gemini/skills/` |
-| GitHub Copilot | `github-copilot` | `.github/skills/` | `~/.copilot/skills/` |
+| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
+| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
 | Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
 | Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
 | iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
@@ -170,12 +266,11 @@ Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [35 more](#su
 | MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
 | Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
 | Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
-| OpenCode | `opencode` | `.opencode/skills/` | `~/.config/opencode/skills/` |
+| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
 | OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
 | Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
 | Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
 | Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
-| Replit | `replit` | `.agents/skills/` | N/A (project-only) |
 | Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
 | Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
 | Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
@@ -194,8 +289,6 @@ The CLI automatically detects which coding agents you have installed.
 | --- | --- |
 | `VT_API_KEY` | VirusTotal API key for optional threat intelligence during security scans |
 | `INSTALL_INTERNAL_SKILLS` | Set to `1` to show and install skills marked as `internal: true` |
-| `DISABLE_TELEMETRY` | Disable anonymous usage telemetry |
-| `DO_NOT_TRACK` | Alternative way to disable telemetry |
 
 ## Development
 
@@ -210,17 +303,39 @@ pnpm format           # Format code with Prettier
 
 ### Scanner Architecture
 
-- `src/scanner.ts` — Rules engine. Defines ~52 regex rules across 8 threat categories, runs them against all skill
-  files (.md, .txt, .yaml, .json, .sh, .py, .js, .ts, .ps1, .bat, .cmd).
+- `src/scanner.ts` — Rules engine. Defines ~81 regex rules across 8 threat categories, a correlation engine for
+  multi-signal detection, and optional deep taint analysis integration. Supports loading external rules from JSON
+  files via `--rules`.
 - `src/scanner-ui.ts` — Presentation layer. Displays findings by severity, runs optional VT lookups, handles
   escalation logic and user confirmation prompts.
 - `src/vt.ts` — VirusTotal API client. SHA-256 hashing, `GET /api/v3/files/{hash}` lookup, verdict mapping, graceful
   error handling.
+- `src/deep-scan/` — Deep taint analysis engine (enabled via `--deep-scan`). Regex-based tokenizers extract sources,
+  sinks, and assignments from Python/JS/TS files; a forward taint tracker propagates data flow; a cross-file analyzer
+  detects multi-file attack patterns via import graph analysis. See [docs/deep-scan.md](docs/deep-scan.md).
 - `src/add.ts` — Integration point. The scanner is wired into all 4 install paths (GitHub/git repos, remote providers,
   well-known endpoints, legacy Mintlify).
 
 ## Changelog
 
+### 1.1.1
+
+- Removed anonymous usage telemetry inherited from the original Vercel `skills` CLI
+- The upstream tool sent events to `https://add-skill.vercel.sh/t` on every command (install, remove, find, check, update) — this has been completely stripped out
+- Removed `DISABLE_TELEMETRY` and `DO_NOT_TRACK` environment variables (no longer needed)
+- Added 12 more regex rules to the scanner
+
+### 1.1.0
+
+- Added `--rules <path>` flag to load external scan rules from JSON files or directories
+- External rules are applied alongside built-in rules, supporting organization-specific policies
+- See [docs/EXTERNAL-RULES.md](docs/EXTERNAL-RULES.md) for format documentation and examples
+- **Deep taint analysis** (`--deep-scan`): lightweight forward taint propagation for Python and JS/TS files
+- Tracks data flow from sources (env vars, credential files, getattr tricks) through variable chains to sinks (network
+  calls, exec, file writes)
+- Cross-file analysis detects multi-file exfiltration patterns via import graph resolution
+- Zero new dependencies — regex-based tokenizers keep the bundle small
+
 ### 1.0.1
 
 - Critical security prompts now default to **No** — users must explicitly confirm to install skills flagged as malicious
@@ -232,6 +347,14 @@ pnpm format           # Format code with Prettier
 - URL transparency: all external URLs in skill files are shown before installation
 - Scanner rules informed by Snyk and ClawHavoc research
 
+## Research
+
+The scanner rules are informed by the following research into malicious agent skills:
+
+- **Snyk (2025)** — [Analysis of 3,984 published agent skills](https://snyk.io/blog/), finding 76 confirmed malicious skills (13.4% of clawhub.ai had critical issues). Identified core attack taxonomy: data exfiltration, prompt injection, credential theft, and obfuscated payloads.
+- **Koi Security (2025)** — [ClawHavoc: 341 Malicious ClawedBot Skills](https://www.koi.ai/blog/clawhavoc-341-malicious-clawedbot-skills-found-by-the-bot-they-were-targeting). Documented AMOS stealer droppers, password-protected archives, base64 payloads, macOS quarantine bypasses, and reverse shells in the wild.
+- **arxiv 2602.06547v1 (2025)** — [Malicious Agent Skills at Scale](https://arxiv.org/abs/2602.06547v1). Large-scale analysis identifying attack taxonomies (E1-E3 exfiltration, P1-P4 prompt injection, SC1-SC3 supply chain, PE2-PE3 privilege escalation), MCP server abuse, agent hook interception, permission bypass flags, environment-gated sleeper patterns, invisible Unicode instruction smuggling, and the "industrial actor fingerprint" (credential access + remote execution, 97.6% sensitivity).
+
 ## Acknowledgments
 
 This project is a fork of [skills](https://github.com/vercel-labs/skills) by