# SkillSpector: quét lỗ hổng skill AI trước khi cài — hướng dẫn cài đặt và dùng

> SkillSpector là công cụ dòng lệnh viết bằng Python, do NVIDIA phát hành, dùng để quét bảo mật các skill của AI agent (Claude Code, Codex, MCP…) trước khi cài. Bạn đưa vào một thư mục, file SKILL.md, link Git hoặc file zip, nó trả về điểm rủi ro 0-100 và danh sách vấn đề. Cài bằng một lệnh uv hoặc dùng Docker; chạy chế độ không cần LLM thì không cần API key.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-01 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/skillspector-quet-bao-mat-skill-ai-huong-dan-cai-dat

SkillSpector là một công cụ dòng lệnh của NVIDIA, chuyên quét bảo mật cho các "skill" của AI agent như Claude Code, Codex CLI hay Gemini CLI. Nó trả lời đúng một câu hỏi: "Skill này có an toàn để cài không?". Bạn đưa cho nó một thư mục, một file SKILL.md, một link Git hoặc một file zip, nó sẽ kiểm tra và chấm điểm rủi ro.

Vì sao việc này đáng quan tâm? Skill chạy với quyền khá rộng trên máy bạn, mà thường không ai kiểm tra kỹ trước khi cài. README của repo nêu một nghiên cứu: trong tập 31.132 skill được phân tích, 26,1% có lỗ hổng và 5,2% có dấu hiệu ác ý. Nếu bạn hay tải skill hay MCP server từ GitHub về dùng, đây là bước "soi trước khi cài" rất hợp lý.

Repo hiện có khoảng 25.700 sao và 2.300 fork, giấy phép Apache-2.0, viết bằng Python và vẫn được cập nhật gần đây. Điểm đáng giá nhất: bạn quét được hoàn toàn trên máy mình, không cần API key, bằng chế độ phân tích tĩnh `--no-llm`. Cần soi sâu hơn thì mới bật thêm LLM.

```repo
- repo | NVIDIA/SkillSpector
- kind | CLI
- desc | SkillSpector của NVIDIA quét skill cho Claude Code, Codex, MCP để phát hiện prompt injection, rò rỉ dữ liệu và rủi ro chuỗi cung ứng trước khi bạn cài.
- stars | 26k
- lang | Python
- license | Apache-2.0
```

## SkillSpector làm được gì

**Nhận nhiều kiểu đầu vào.** Bạn quét được repo Git, URL, file zip, thư mục hoặc một file đơn lẻ. Tải skill ở dạng nào cũng quét được, khỏi mất công giải nén hay sắp xếp lại.

**71 mẫu lỗ hổng, chia thành 17 nhóm.** Gồm prompt injection (cài lệnh ẩn để điều khiển AI), rò rỉ dữ liệu, leo thang đặc quyền, rủi ro chuỗi cung ứng, agent làm quá quyền, đầu độc bộ nhớ, dùng sai công cụ, mã nguy hiểm, và các nhóm riêng cho MCP như đầu độc mô tả công cụ hay cấp quyền thừa. Bạn không phải tự nhớ từng kiểu tấn công.

**Hai tầng phân tích.** Tầng một là phân tích tĩnh, nhanh. Tầng hai là nhờ LLM đánh giá ngữ nghĩa, tùy chọn. Tầng tĩnh đủ để sàng lọc nhanh. Tầng LLM giúp hiểu ý đồ của đoạn văn bản, nơi luật cứng dễ bỏ sót.

**Tra lỗ hổng trực tiếp.** Một phần kiểm tra chuỗi cung ứng hỏi OSV.dev để lấy dữ liệu CVE mới, và có chế độ dự phòng ngoại tuyến khi không có mạng.

**Nhiều định dạng báo cáo.** Terminal (mặc định), JSON, Markdown và SARIF. Người không code đọc terminal hoặc Markdown. Dev đưa JSON hay SARIF vào CI hoặc công cụ IDE.

**Điểm rủi ro 0-100.** Kèm nhãn mức độ và khuyến nghị rõ ràng, nên nhân viên không chuyên bảo mật vẫn ra được quyết định.

**Baseline để bỏ qua báo động giả.** Bạn "chấp nhận" các phát hiện đã xem xét, lần quét sau chỉ hiện vấn đề mới.

**Quét hàng loạt và so sánh MCP Registry.** Có chế độ `--recursive`, công cụ quét song song trong `contrib/batch_scan/`, và chế độ quét danh mục MCP Registry để so sánh hai thời điểm.

## Cần chuẩn bị gì

- **Python:** `pyproject.toml` yêu cầu Python từ 3.12 đến dưới 3.16. Nếu không muốn cài Python, dùng Docker (xem bên dưới).
- **Trình quản lý gói:** README khuyên dùng `uv`, hoặc `pip` cũng được. README nhắc hãy tạo và kích hoạt môi trường ảo (venv) trước.
- **Git:** cần khi cài từ source hoặc quét link Git.
- **Docker (tùy chọn):** image dựng từ Dockerfile có sẵn, dựa trên Python 3.12-slim-bookworm.
- **API key (tùy chọn):** chỉ cần khi bật phân tích bằng LLM. README liệt kê nhiều nhà cung cấp: OpenAI, Anthropic, AWS Bedrock, NVIDIA build, Gemini, Azure OpenAI, Ollama chạy local, endpoint tương thích OpenAI, và một số CLI như `claude_cli`, `gemini_cli`, `opencode_cli`.
- **Hệ điều hành:** README viết lệnh theo kiểu Linux/macOS (ví dụ `source .venv/bin/activate`). Phần tư liệu mình có không nói riêng về Windows. Người dùng Windows có thể thử đường Docker, hoặc xem thêm tài liệu trong repo.
- **Phần cứng:** tư liệu không yêu cầu GPU cho chế độ quét tĩnh.

```note
README lưu ý: dự án sẽ tải và cài thêm một số phần mềm mã nguồn mở bên thứ ba. Bạn nên đọc giấy phép của chúng trước khi dùng. Ngoài ra, khi bật LLM, nội dung skill được gửi đến nhà cung cấp bạn chọn, và API key có thể phát sinh chi phí.
```

## Cài đặt từng bước

```steps
- Mở terminal | Vào thư mục bạn muốn làm việc, có Python 3.12 trở lên và uv
- Cài bằng uv | Một lệnh để có lệnh skillspector (cách nhanh nhất)
- Hoặc cài từ source | Clone repo, tạo venv, chạy make install
- Hoặc dùng Docker | Dựng image rồi chạy không cần Python
- Quét thử | Chạy skillspector scan với --no-llm trên một skill
```

### Cách 1: cài nhanh bằng uv (khuyên dùng)

Đây là cách nhanh nhất nếu bạn chỉ cần dùng lệnh. Mở terminal (PowerShell, Terminal hoặc bất kỳ cửa sổ dòng lệnh nào), rồi chạy:

```bash
uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector
```

Dòng thứ hai trong khối trên là ghi chú cách cập nhật theo README. Nếu máy báo không có lệnh `uv`, bạn cần cài uv trước. README chưa hướng dẫn cài uv, bạn xem trang chủ của uv.

Muốn dùng thêm chế độ `skillspector mcp`, cài kèm phần mở rộng MCP ngay từ lúc cài:

```bash
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'
```

Chỗ hay vấp: nhớ để nguyên dấu nháy đơn quanh cụm `'skillspector[mcp] @ ...'`, vì dấu ngoặc vuông dễ bị shell hiểu sai.

### Cách 2: cài từ source

Cách này hợp với người muốn đọc hoặc sửa code. Trước hết tải repo về và vào thư mục:

```bash
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector
```

Tiếp theo tạo và kích hoạt môi trường ảo. README đưa hai lựa chọn:

```bash
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate
```

Cuối cùng cài bản dùng thật:

```bash
make install
```

README nói mọi mục tiêu `make` đều giả định venv đang được kích hoạt, nên đừng bỏ bước tạo venv. Nếu máy bạn chưa có `make`, README chưa ghi cách thay thế. Bạn có thể xem `Makefile` và `pyproject.toml` trong repo để biết các lệnh cài tương ứng.

### Cách 3: dùng Docker (không cần Python)

Dựng image từ Dockerfile có sẵn trong repo (chạy trong thư mục đã clone):

```bash
make docker-build
# or: docker build -t skillspector .
```

Quét một thư mục trên máy bằng cách gắn thư mục hiện tại vào `/scan` trong container:

```bash
docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm
```

Lưu ý: `my-skill` phải nằm trong thư mục hiện tại của bạn, vì chỉ thư mục đó được gắn vào container. Muốn ghi báo cáo ra máy thật, ghi vào thư mục đã gắn:

```bash
docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --no-llm --format json --output report.json
```

Nếu chạy lệnh Docker thường xuyên, README gợi ý đặt bí danh:

```bash
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm
```

### Tùy chọn: bật phân tích bằng LLM

Chọn nhà cung cấp bằng biến `SKILLSPECTOR_PROVIDER` và điền key tương ứng. Ví dụ với Docker, bạn tạo file `.env` như README:

```bash
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF
```

Rồi chạy kèm file này:

```bash
docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/
```

Thay `sk-ant-...` bằng key thật của bạn. Repo có sẵn file `.env.example` liệt kê tên các biến, bạn xem trong đó để biết biến nào cần cho nhà cung cấp mình chọn. Không bao giờ đưa file `.env` lên GitHub.

### Phần mở rộng cho Pi và OpenCode

README có nhắc hai phần mở rộng để quét skill ngay trong phiên làm việc với agent: Pi extension (gói npm tên `skillspector-pi`) và OpenCode extension (có lệnh `/skillspector`). README phần mình có chưa ghi lệnh cài cụ thể, bạn xem thư mục `extensions/` trong repo.

## Kiểm tra đã chạy được chưa

Cách chắc nhất là quét thử một skill thật bằng chế độ không cần LLM:

```bash
skillspector scan ./my-skill/ --no-llm
```

Nếu lệnh chạy và in ra báo cáo trên terminal gồm điểm rủi ro 0-100, nhãn mức độ và khuyến nghị, là cài thành công. Tư liệu mình có không mô tả chính xác giao diện màn hình, nên bạn cứ đối chiếu với các thành phần trên.

Nếu dùng Docker, lệnh tương ứng là `docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm`. Chưa có skill nào để thử thì bạn quét thư mục chứa SKILL.md của một skill bạn đang định cài.

## Dùng vào việc thật

### Chủ shop kiểm tra skill trước khi cho nhân viên cài

Bạn nhờ nhân viên tìm skill trên GitHub để tự động hóa việc viết mô tả sản phẩm. Trước khi cài vào máy làm việc, hãy quét link repo đó:

```bash
skillspector scan https://github.com/user/my-skill --no-llm
```

Bạn nhận được điểm rủi ro 0-100 cùng danh sách phát hiện. Điểm cao hoặc có cảnh báo về rò rỉ dữ liệu thì chưa cài, hỏi lại tác giả hoặc chọn skill khác.

> Cài skill giống như mời người lạ vào nhà: soi trước vài giây rẻ hơn rất nhiều so với dọn dẹp sau.
>
> — Ông T

### Nhân viên văn phòng xuất báo cáo gửi sếp

Sếp muốn có bằng chứng skill đã được kiểm tra. Bạn xuất báo cáo Markdown để dán vào tài liệu nội bộ:

```bash
skillspector scan ./my-skill/ --format markdown --output report.md
```

Nhận được file `report.md` đọc như tài liệu thường, không cần biết lập trình. Thêm `--no-llm` nếu bạn chưa có API key.

### Dev đưa bước quét vào CI

Bạn quản lý một kho skill chung của nhóm. Mỗi lần có skill mới, cho CI quét và xuất SARIF để công cụ IDE hay nền tảng code hiển thị:

```bash
skillspector scan ./my-skill/ --format sarif --output report.sarif
```

Với thư mục chứa nhiều skill, README có chế độ quét đệ quy (mặc định tối đa 32 skill, có thể tăng bằng `--max-skills`):

```bash
skillspector scan ./my-skills/ --recursive --max-skills 100 --no-llm --format json
```

Thêm `--fail-on-incomplete` nếu muốn CI báo lỗi khi việc quét chưa phủ hết.

### Giảm báo động giả cho skill tự viết

Skill của bạn có vài cảnh báo đã xem xét và chấp nhận được. Tạo baseline một lần, rồi quét lại chỉ để thấy vấn đề mới:

```bash
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed
```

Lệnh cuối cho bạn xem lại những gì đã được bỏ qua. Hãy chỉ đưa vào baseline những phát hiện bạn đã thật sự đọc, đừng "chấp nhận hết" cho nhanh.

## Lỗi hay gặp và cách xử lý

**Không tìm thấy lệnh `skillspector`.** Thường do chưa cài `uv`, hoặc đường dẫn của công cụ do uv cài chưa nằm trong PATH. Mở lại terminal sau khi cài. Nếu vẫn lỗi, dùng cách cài từ source hoặc Docker.

**Python không đủ phiên bản.** Dự án yêu cầu Python từ 3.12 đến dưới 3.16. Nếu máy đang dùng bản cũ hơn, hãy cài Python phù hợp, hoặc chạy bằng Docker để khỏi phụ thuộc Python.

**`make install` báo lỗi hoặc cài lung tung vào hệ thống.** README nhắc mọi lệnh `make` giả định venv đang bật. Hãy tạo và kích hoạt venv trước rồi chạy lại.

**Docker không thấy thư mục skill, hoặc ghi báo cáo bị từ chối quyền.** Container chỉ thấy thư mục bạn gắn vào `/scan`, nên skill phải nằm trong thư mục hiện tại. Với báo cáo, dùng thêm `--user "$(id -u):$(id -g)"` như README. Trên Windows, lệnh `id` không có sẵn, bạn cần thử trong môi trường dạng Linux.

**Quét bằng LLM không chạy.** Thường do chưa đặt `SKILLSPECTOR_PROVIDER` hoặc thiếu biến key tương ứng (ví dụ `ANTHROPIC_API_KEY`). Mở `.env.example` đối chiếu tên biến. Muốn quét trước thì cứ thêm `--no-llm`.

**Quét thư mục lớn bị dừng hoặc báo thiếu phạm vi.** SkillSpector có các giới hạn kích thước: 100 MiB cho mỗi lần nạp, 10.000 mục trong một file zip, và các mức trần phân tích khác. Vượt ngưỡng nạp thì công cụ dừng với lỗi `IngestLimitExceededError`. Hãy quét từng skill riêng, và đừng coi báo cáo "chưa đầy đủ" là đã an toàn.

## Có nên dùng không

**Điểm mạnh.** Cài nhẹ, chạy tĩnh không cần key, phủ nhiều nhóm rủi ro riêng của skill và MCP mà các công cụ quét mã thông thường ít chú ý. Báo cáo có điểm số, đủ định dạng cho cả người đọc lẫn CI, và có baseline để bớt báo động giả. Repo lại do NVIDIA phát hành và nằm trong quy trình "NVIDIA Verified Skills" của họ.

**Giới hạn.** Quét tĩnh có thể bỏ sót hoặc báo nhầm. Bản thân README cũng chỉ gọi đây là công cụ giúp trả lời câu hỏi "có an toàn không", không phải bảo chứng tuyệt đối. Điểm thấp không có nghĩa là skill chắc chắn sạch, nên với skill quan trọng bạn vẫn nên đọc file SKILL.md và các script đi kèm. Muốn phân tích ngữ nghĩa thì cần LLM, kéo theo chi phí và việc gửi nội dung skill ra dịch vụ bên ngoài (trừ khi bạn chạy mô hình local như Ollama). README cũng ghi chú rằng việc hỗ trợ LLM mặc định và backend phổ quát vẫn đang được cộng đồng cải thiện.

**Khi nào chọn cách khác.** Nếu bạn cần quét bảo mật cho ứng dụng thông thường (web, thư viện), hãy dùng công cụ quét mã nguồn chuyên dụng. Nếu bạn chỉ dùng skill từ nguồn bạn tin hoàn toàn và tự viết, SkillSpector vẫn hữu ích như một lớp kiểm tra thêm, nhưng không bắt buộc. Còn với skill của người lạ, mình khuyên quét trước khi cài.

## Câu hỏi thường gặp

### SkillSpector có miễn phí không?

Bản thân công cụ là mã nguồn mở, giấy phép Apache-2.0. Chế độ quét tĩnh với `--no-llm` không cần API key. Nếu bật phân tích bằng LLM của bên thứ ba (OpenAI, Anthropic…), chi phí tính theo nhà cung cấp đó.

### SkillSpector quét được những loại skill nào?

Mô tả của repo nói nó nhắm tới skill cho Claude Code, Codex và MCP, và README còn nhắc Gemini CLI. Đầu vào có thể là thư mục, file SKILL.md, repo Git, URL hoặc file zip.

### Có cần GPU không?

Tư liệu không yêu cầu GPU. Chế độ quét tĩnh chạy bằng Python hoặc Docker. Nếu bạn muốn dùng mô hình chạy local qua Ollama, vLLM hay llama.cpp thì cấu hình phần cứng phụ thuộc mô hình bạn chọn, và tư liệu chưa nêu chi tiết.

### Chạy được trên Windows không?

README viết lệnh theo kiểu Linux/macOS và không có phần riêng cho Windows. Bạn có thể thử cài bằng uv hoặc dùng Docker, nhưng mình chưa có thông tin xác nhận chi tiết cho Windows. Hãy xem thư mục docs trong repo.

### Dữ liệu của tôi có an toàn không?

Ở chế độ `--no-llm`, việc phân tích tĩnh chạy trên máy bạn, riêng phần tra lỗ hổng chuỗi cung ứng có hỏi OSV.dev và có dự phòng ngoại tuyến. Khi bật LLM qua dịch vụ đám mây, nội dung cần phân tích sẽ được gửi tới nhà cung cấp bạn chọn. Muốn tránh điều này, README nói có thể dùng máy chủ tương thích OpenAI chạy local.

### Điểm rủi ro thấp có nghĩa là skill chắc chắn an toàn không?

Không. Điểm 0-100 và khuyến nghị giúp bạn sàng lọc, nhưng quét tự động vẫn có thể bỏ sót. Với skill quan trọng, bạn nên đọc thêm nội dung skill. Báo cáo cũng ghi rõ khi phạm vi quét chưa đầy đủ.

### SkillSpector khác gì công cụ quét mã thông thường?

Theo README, nó có các nhóm kiểm tra riêng cho skill và MCP như prompt injection, đầu độc mô tả công cụ, agent làm quá quyền và đầu độc bộ nhớ. Tư liệu chưa so sánh trực tiếp với từng công cụ cụ thể khác.
