🇬🇧 English | 🇻🇳 Tiếng Việt

⚡ SkillSpector-TKV Scanner

AI agent skill security scanner — written 100% in TokenVector, compiled to tiny native .exe files. Inspired by NVIDIA SkillSpector.

Scan skill folders, zip files, URLs and git repos for vulnerabilities, malicious patterns and risk score before you install them — offline by default, optional LLM (11 providers) via GUI popup or env keys. D:\ai_skills (171 skills) scans in seconds when LLM OFF, minutes when LLM ON (one 30s-capped HTTP call per skill with findings).

---

✨ Highlights (v0.25)

• 101 detection rules across 27 groups — 87 NVIDIA rules + 14 exclusive (secrets, exfil endpoints, reverse shells, destructive, supply-chain...). v0.25 tuned for <5% high-rate: word-boundary eval(/exec(, negation awareness (no eval, without shell), docs-vs-code gates (deploy --force, API allowlists, table pipes, re.compile), per-line wordlist gate.
• Risk score 0–100 SAFE / CAUTION / DO_NOT_INSTALL + exit 0/1/2. 171 skills → 139 zero / 20 low / 9 med / 3 high after tuning (was 12 critical).
• 3 binaries (~144KB each): GUI scanner, CLI, MCP server (stdio + HTTP 127.0.0.1). PEVerify 100% clean.
• GUI (SkillSpector-TKV.exe): 7-column ListView, continuous progress bar (1000px, progDone*100/progTotal), status line Scanning: path (45%) (blue during scan, black after), sortable headers (click toggle asc/desc, numeric for Score), live filter box (Filter...), Export → CSV (Excel), Browse/SCAN/LLM buttons, Information/MIT/Scan rules links, black owner line, empty-target MessageBox (no crash).
• Offline-first + LLM: 11 providers via popup (skill_llm.json) or env (OPENAI_API_KEY/ANTHROPIC_API_KEY...). When LLM ON, scan_path_llm filters FP via DROP:IDs and rescues score; scan_perf.log records target|flen|ms|drop per skill, tick_ms() timing, skip when findings empty, HttpWebRequest 30s timeout (fail-open).
• Windows native, Linux/macOS via Mono (mono bin/skill-scan-gui.exe).

🚀 Quick start (Windows)

:: 1. Build (needs tkvc.exe, included) — kills stale exe, PEVerify
build.bat
:: 2. GUI: double-click SkillSpector-TKV.exe, Browse... → SCAN
::    Filter: type in Filter box • Sort: click header • Export: Export button
:: 3. CLI:
bin\skill-scan-cli.exe scan D:\my-skill --format json
bin\skill-scan-cli.exe scan D:\ai_skills --recursive --format json

See USER_GUIDE_EN.md for flags, baseline, SARIF, MCP, Mono.

🧠 Why TokenVector?

Metric	Python (NVIDIA)	TokenVector (this repo)
Install size	~25–100 MB runtime	~144KB per binary
Runtime needed	Python 3.12 + pip	None (Mono only on Linux/mac)
Startup	1–3 s	Instant
Language	Python	TokenVector .tkv (Python syntax, static types, WinForms/.NET interop)

Whole scanner — regex engine, risk scorer, WinForms, MCP — is .tkv in src/, plugins in il_features/, compiled by tkvc.exe. See TokenVector.

📊 Comparison with NVIDIA/SkillSpector

Area	NVIDIA SkillSpector	SkillSpector-TKV	Verdict
Rules	87	101 (87 + 14 exclusive, v25 tuned)	✅ More
Scoring/bands/exit codes	Yes	Identical	✅ Parity
file:line + evidence	Yes	Yes (per-line, snippet, :0 file-level)	✅ Parity
Recursive/multi-skill, baseline, SARIF, OSV, git, MCP	Yes	Yes (lockfile-aware, pinned OSV, lite)	✅ Near parity
LLM semantic analysis	11 providers	11 providers popup + env, wired per-skill DROP filter	✅ Parity
GUI dashboard	No	7-col + progress % + sort + filter + export	✅ Exclusive
Binary size	~25–100 MB	~144KB	✅ ~175x smaller

Full table: docs/COMPARISON.md · matrix: parity/MATRIX.csv · reports: parity/PARITY_REPORT.md.

📁 Project structure

src/            # TokenVector sources (.tkv): engine, patterns, CLI, MCP, scanner
il_features/    # Compiler plugins: WinForms UI, walk, HTTP (30s timeout), colors...
tests/fixtures/ # 18 fixtures (clean/malicious/evil/tricky/nested/newcats/ast_...)
parity/         # Matrix + verification
docs/           # Comparison docs
bin/            # Build output (git-ignored)
scan_perf.log   # Per-skill perf log when scanning (target|flen|ms|drop)

📚 Docs

• USER_GUIDE_EN.md / USER_GUIDE_VI.md — manuals
• HISTORY.md — G0 → v0.25
• CHANGELOG.md — v0.25
• PLAN.md / DEV_RULES.md — architecture & TKV rules
• LICENSE — MIT

👤 Author

Tran Nguyen Hung — nguyen.hung.tran.18@gmail.com Inspired by NVIDIA SkillSpector · Built with TokenVector