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

> SkillSpector là công cụ quét bảo mật dành cho skill của AI agent (Claude Code, Codex, MCP...). Bạn đưa vào một thư mục, file SKILL.md, repo Git hoặc file zip, nó trả về điểm rủi ro 0-100 kèm danh sách phát hiện. Cài bằng một lệnh uv hoặc dùng Docker, quét tĩnh không cần API key.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-31 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/skillspector-quet-rui-ro-skill-ai-truoc-khi-cai

SkillSpector là công cụ quét bảo mật cho các "skill" của AI agent, do NVIDIA phát triển, viết bằng Python, giấy phép Apache-2.0. Bạn đưa cho nó một skill (thư mục, file SKILL.md, repo Git, đường link hoặc file zip), nó đọc toàn bộ nội dung và báo lại skill đó có dấu hiệu nguy hiểm hay không. Hiện repo có khoảng 25.745 sao và 2.278 fork.

Vấn đề nó giải quyết rất thực tế. Skill của Claude Code, Codex CLI, Gemini CLI... chạy với mức tin cậy cao nhưng gần như không ai kiểm tra. README dẫn một nghiên cứu trên tập 31.132 skill: khoảng 26,1% skill có lỗ hổng và khoảng 5,2% có dấu hiệu cố ý độc hại. Nói đơn giản, tải skill về cài bừa cũng giống chạy file lạ trên máy công ty.

Ai nên dùng? Dev hay thử skill mới, người làm văn phòng hoặc chủ doanh nghiệp nhỏ đang cho nhân viên dùng AI agent, và đội IT muốn chặn skill xấu trước khi vào máy. Điểm đáng giá nhất: chế độ quét tĩnh chạy nhanh, không cần key, rồi bạn mới thêm bước phân tích bằng LLM nếu muốn kỹ hơn.

```repo
- repo | NVIDIA/SkillSpector
- kind | CLI
- desc | SkillSpector là công cụ dòng lệnh của NVIDIA, quét skill cho Claude Code, Codex và MCP để phát hiện mã độc, prompt injection, rò rỉ dữ liệu 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.** Quét thư mục, file SKILL.md đơn lẻ, repo Git, URL hoặc file zip. Bạn không phải tải và giải nén thủ công rồi mới kiểm tra.
- **71 mẫu lỗ hổng, 17 nhóm.** Gồm prompt injection, đánh cắp dữ liệu, leo thang quyền, rủi ro chuỗi cung ứng, quyền hạn quá mức (excessive agency), rò rỉ system prompt, đầu độc bộ nhớ, dùng sai công cụ, mã nguy hiểm (phân tích AST), theo dõi luồng dữ liệu (taint), chữ ký YARA, và hai nhóm riêng cho MCP (quyền tối thiểu, đầu độc mô tả công cụ). Bạn không cần thuộc các tên này, chỉ cần biết nó soi khá rộng.
- **Hai tầng phân tích.** Tầng một là phân tích tĩnh, nhanh. Tầng hai là LLM đọc ngữ nghĩa (tùy chọn) để bắt những chiêu mà luật cứng khó thấy, ví dụ câu chữ ngụy trang trong hướng dẫn.
- **Tra cứu lỗ hổng trực tuyến.** Nhóm kiểm tra chuỗi cung ứng hỏi OSV.dev để lấy dữ liệu CVE mới, mất mạng thì tự quay về chế độ offline.
- **Nhiều định dạng báo cáo.** Terminal, JSON, Markdown, SARIF. SARIF dùng được cho CI/CD và công cụ trong IDE.
- **Điểm rủi ro 0-100** kèm nhãn mức độ và khuyến nghị rõ ràng, nên người không chuyên cũng đọc được.
- **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 phát hiện mới.
- **Quét hàng loạt.** Có chế độ `--recursive` và script quét song song trong thư mục `contrib/batch_scan/`.
- **Quét danh mục MCP Registry** và so sánh hai thời điểm để thấy server nào thêm, bớt hoặc đổi.

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

- **Python từ 3.12 đến dưới 3.16** (theo `pyproject.toml`), nếu cài trực tiếp. Không muốn cài Python thì dùng Docker.
- **uv hoặc pip.** README khuyên dùng uv; Makefile tự dùng uv nếu có, không thì dùng pip.
- **Git**, nếu bạn cài từ source hoặc quét repo Git.
- **Docker**, chỉ khi chọn cách chạy bằng container (image dựa trên `python:3.12-slim-bookworm`).
- **API key của một nhà cung cấp LLM**, chỉ khi bạn muốn tầng phân tích ngữ nghĩa. Quét tĩnh với `--no-llm` thì không cần.
- **Hệ điều hành:** README chưa nói rõ hỗ trợ hệ điều hành nào. Các lệnh trong README viết theo kiểu shell bash (ví dụ `source .venv/bin/activate`), nên người dùng Windows nên cân nhắc Docker hoặc kiểm tra thêm trong tài liệu của dự án.
- Phần cứng: README không nêu yêu cầu GPU hay RAM.

README cũng nhắc: dự án sẽ tải và cài thêm phần mềm mã nguồn mở của bên thứ ba, bạn nên xem giấy phép của chúng trước khi dùng.

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

```steps
- Mở terminal | Mở terminal ở thư mục bạn muốn làm việc
- Cài SkillSpector | Dùng uv tool install, hoặc cài từ source, hoặc build Docker
- Chuẩn bị skill cần quét | Một thư mục chứa SKILL.md, repo Git hoặc file zip
- Quét thử không dùng LLM | Chạy skillspector scan kèm --no-llm
- Bật LLM (tùy chọn) | Chọn nhà cung cấp và điền key qua biến môi trường
```

### Mở terminal đúng chỗ

Trên Windows, mở PowerShell hoặc Windows Terminal. Trên macOS/Linux, mở Terminal. Các lệnh bên dưới chạy trong cửa sổ này. Lỗi hay gặp của người mới là mở terminal ở thư mục khác rồi không tìm thấy skill cần quét, nên hãy `cd` vào đúng nơi chứa skill.

### Cách 1: cài nhanh bằng uv (chỉ dùng dòng lệnh)

Đây là cách README ghi đầu tiên và gọn nhất:

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

Lệnh đầu cài công cụ từ GitHub. Dòng thứ hai (đang là chú thích) là cách cập nhật sau này, chép nguyên từ README. Nếu bạn định chạy `skillspector mcp`, hãy cài kèm phần MCP ngay từ đầu:

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

Dấu nháy đơn quanh cả cụm là cần thiết, để shell không hiểu nhầm dấu ngoặc vuông.

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

```bash
# Clone the repository
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector

# Create and activate virtual environment
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate

# Install for production use
make install
```

Những lệnh này tải mã về, vào thư mục dự án, tạo môi trường ảo rồi cài. README nhấn mạnh phải tạo và kích hoạt môi trường ảo trước, vì mọi lệnh `make` đều giả định môi trường đó đang bật. Dòng `source .venv/bin/activate` là cú pháp Linux/macOS; README chưa ghi lệnh tương đương cho Windows.

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

Build image từ Dockerfile có sẵn trong repo:

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

Sau đó quét thư mục hiện tại bằng cách gắn nó vào `/scan` trong container:

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

`-v "$PWD:/scan"` cho container nhìn thấy thư mục bạn đang đứng, còn `--rm` tự xóa container sau khi chạy xong. Nếu muốn lưu báo cáo ra máy thật:

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

Quét nhiều lần thì đặt alias cho ngắn:

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

### Bật phân tích LLM (tùy chọn)

Chọn nhà cung cấp bằng biến `SKILLSPECTOR_PROVIDER`. Với Docker, README hướng dẫn tạo file `.env` rồi truyền vào:

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

```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. README liệt kê nhiều nhà cung cấp: `openai`, `anthropic`, `anthropic_proxy`, `bedrock`, `nv_build`, `gemini`, `ollama`, `azure_openai`, `openai_compatible`, và các loại chạy qua CLI cục bộ như `claude_cli`, `gemini_cli`, `opencode_cli`. Riêng `codex_cli` đang bị vô hiệu hóa. Mỗi loại cần biến key riêng, xem bảng trong README hoặc file `.env.example` ở gốc repo.

```note
Key API là bí mật. Không dán vào file rồi commit lên Git, không gửi lại trong chat. LLM phân tích sẽ đọc nội dung skill bạn quét nên có thể phát sinh chi phí và gửi nội dung đó cho nhà cung cấp; với skill nội bộ nhạy cảm, hãy ưu tiên quét tĩnh hoặc dùng mô hình chạy cục bộ như Ollama.
```

Về Pi extension và OpenCode extension (cài SkillSpector thành công cụ ngay trong phiên agent), README chỉ trỏ tới thư mục `extensions/` chứ phần trích ở đây chưa ghi lệnh cài. Bạn xem hướng dẫn trong thư mục đó.

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

Phần README mình có không ghi lệnh kiểm tra phiên bản, nên cách chắc chắn nhất là quét thử một skill thật:

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

Nếu cài đúng, terminal sẽ in báo cáo định dạng đẹp, có điểm rủi ro từ 0 đến 100, nhãn mức độ nghiêm trọng, danh sách phát hiện và khuyến nghị. Gặp `command not found` thì xem phần lỗi bên dưới. Nếu bạn chưa có skill nào, thử quét một thư mục skill bất kỳ trên máy hoặc một repo công khai:

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

Chỗ `user/my-skill` là ví dụ trong README, hãy thay bằng repo thật.

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

### Dev kiểm tra skill lạ trước khi cài vào Claude Code

Bạn thấy một skill hay trên mạng. Thay vì cài ngay, hãy quét trước. Có ba cách tùy dạng skill:

```bash
skillspector scan ./my-skill/
skillspector scan ./SKILL.md
skillspector scan ./my-skill.zip
```

Kết quả là điểm rủi ro và các phát hiện cụ thể. Nếu thấy dấu hiệu prompt injection hay đánh cắp dữ liệu, bạn bỏ skill đó, không cần đoán mò.

> Cài skill mà không quét cũng như chạy file lạ người ta gửi qua chat: có khi ổn, nhưng bạn đang đánh cược.
>
> — Ông T

### Chủ doanh nghiệp nhỏ lập quy trình duyệt skill cho nhân viên

Công ty bạn cho vài nhân viên dùng AI agent. Quy tắc đơn giản: skill nào muốn dùng phải được quét và lưu báo cáo trước. Xuất ra Markdown để đính kèm vào tài liệu nội bộ:

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

Bạn có một file báo cáo dễ đọc, người không rành kỹ thuật vẫn nắm được skill có đáng ngờ hay không.

### Đội IT quét cả thư mục skill và đưa vào CI

Có một thư mục chứa nhiều skill, mỗi skill một thư mục con có SKILL.md. Dùng chế độ đệ quy:

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

Mặc định chỉ quét tối đa 32 skill, nên cần `--max-skills` để nâng giới hạn (phải là số nguyên dương, `0` không có nghĩa là không giới hạn). Muốn pipeline CI báo lỗi khi độ phủ chưa đầy đủ, thêm `--fail-on-incomplete`. Báo cáo SARIF cũng có sẵn cho CI và IDE:

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

### Dev dọn báo động giả để lần quét sau chỉ thấy lỗi mới

Skill của bạn có vài phát hiện đã xem xét và chấp nhận được. Tạo baseline một lần, rồi quét theo baseline:

```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
```

Dòng đầu ghi các phát hiện hiện tại vào file baseline. Dòng hai chỉ báo phát hiện mới. Dòng ba cho xem lại những gì đã bị bỏ qua. Lưu ý: baseline theo dấu vân tay gắn với mã nguồn và phiên bản SkillSpector, nên đổi một trong hai thì phát hiện đó hiện lại để bạn duyệt lại.

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

- **Gõ `skillspector` báo không tìm thấy lệnh.** Thường do thư mục cài công cụ của uv chưa nằm trong PATH, hoặc bạn cài từ source nhưng chưa kích hoạt môi trường ảo. Mở lại terminal mới, hoặc kích hoạt lại môi trường ảo rồi chạy lại. Nếu vẫn lỗi, dùng Docker cho nhanh.
- **Python quá cũ hoặc quá mới.** Dự án yêu cầu Python từ 3.12 đến dưới 3.16. Kiểm tra phiên bản bằng `python --version` hoặc để uv/Docker lo giúp.
- **Chạy LLM nhưng báo thiếu key hoặc xác thực lỗi.** Kiểm tra `SKILLSPECTOR_PROVIDER` khớp với biến key bạn điền (ví dụ `anthropic` đi với `ANTHROPIC_API_KEY`). Với Docker, nhớ truyền `--env-file .env` hoặc `-e`. Muốn quét ngay không cần key thì thêm `--no-llm`.
- **Quét repo hoặc zip bị từ chối vì quá lớn.** README nêu hai giới hạn: tối đa 100 MiB cho mỗi lần nhập và 10.000 mục trong một file zip. Vượt giới hạn thì công cụ dừng với `IngestLimitExceededError` (cố tình chặn theo kiểu "an toàn là trên hết"). Hãy quét từng phần nhỏ hơn.
- **Dùng `--recursive` nhưng chỉ thấy một phần skill.** Mặc định chỉ lấy 32 skill. Tăng bằng `--max-skills`, và dùng `--fail-on-incomplete` trong CI để không bỏ sót vì độ phủ chưa đủ.

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

**Điểm mạnh:** miễn phí, mã nguồn mở (Apache-2.0), quét tĩnh chạy ngay không cần key, nhận nhiều dạng đầu vào, báo cáo xuất được ra JSON/Markdown/SARIF, có baseline và chế độ quét hàng loạt. Việc nó nằm trong quy trình NVIDIA Verified Skills cũng cho thấy dự án được đầu tư nghiêm túc.

**Giới hạn cần biết:** điểm số chỉ là tín hiệu, không phải bảo chứng. Công cụ dựa trên 71 mẫu và LLM, nên vẫn có thể báo nhầm hoặc bỏ sót; README cũng cho phép "chấp nhận" phát hiện bằng baseline, nghĩa là quyết định cuối cùng vẫn là của bạn. Tầng LLM cần key và có thể tốn tiền, đồng thời nội dung skill được gửi tới nhà cung cấp bạn chọn. Hỗ trợ Windows chưa được README nói rõ. Phần ghi chú trong README cũng thừa nhận backend LLM mặc định (DeepSeek) có thể ngừng và chưa kiểm thử với mô hình cục bộ, nên bạn nên tự thử với nhà cung cấp mình dùng.

**Khi nào chọn cách khác:** nếu bạn chỉ cần soi nhanh vài file nhỏ, đọc tay là đủ. Nếu bạn cần kiểm toán bảo mật chính thức cho cả công ty, hãy xem SkillSpector như một lớp lọc đầu vào chứ không thay cho đánh giá của chuyên gia. Còn nếu bạn chỉ dùng skill từ nguồn tin cậy và hiếm khi cài mới, mức đầu tư này có thể chưa cần thiết.

Tóm lại: nếu bạn hay cài skill hoặc MCP từ nguồn bên ngoài, thêm một bước `skillspector scan` trước khi cài là thói quen rẻ và đáng có.

## 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, dùng không mất phí. Chế độ quét tĩnh với `--no-llm` không cần key. Nếu bật phân tích LLM, bạn có thể tốn phí theo nhà cung cấp mình chọn; README không nêu mức giá cụ thể.

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

README không nêu yêu cầu GPU. Quét tĩnh chạy bằng Python thông thường. Nếu bạn muốn dùng mô hình cục bộ qua Ollama, vLLM hay llama.cpp thì phần cứng phụ thuộc vào mô hình đó, tư liệu chưa có thông tin chi tiết.

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

README chưa nói rõ về hệ điều hành. Các lệnh mẫu viết kiểu bash, ví dụ kích hoạt môi trường ảo bằng `source .venv/bin/activate`. Người dùng Windows có thể thử cài bằng uv hoặc dùng Docker, nhưng nên tự kiểm tra thêm.

### Skill của tôi có bị gửi đi đâu không?

Với `--no-llm`, README mô tả đây là phân tích tĩnh cục bộ, riêng nhóm kiểm tra chuỗi cung ứng có tra cứu OSV.dev và tự chuyển sang offline khi mất mạng. Khi bật LLM, nội dung phân tích sẽ đi qua nhà cung cấp bạn chọn, trừ khi dùng mô hình chạy cục bộ. Hãy cân nhắc khi quét skill nhạy cảm.

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

Mô tả của tác giả nói công cụ nhắm tới skill của Claude Code, Codex và MCP. Đầu vào có thể là thư mục, file SKILL.md, repo Git, URL hoặc file zip. Ngoài ra còn có chế độ quét danh mục MCP Registry.

### Điểm rủi ro được hiểu thế nào?

Báo cáo cho điểm từ 0 đến 100, kèm nhãn mức độ nghiêm trọng và khuyến nghị. README nêu rằng nếu độ phủ quét chưa đầy đủ (ví dụ có file bị loại trừ) thì công cụ không đưa ra khuyến nghị SAFE. Bảng quy đổi điểm chi tiết chưa có trong phần README mình có.

### Dùng trong CI/CD được không?

Được. Công cụ xuất được JSON và SARIF, có tuỳ chọn `--fail-on-incomplete` để làm lỗi pipeline khi độ phủ chưa đầy đủ. Hướng dẫn chi tiết về chặn cài đặt nằm trong trang tài liệu chính thức của dự án trên docs.nvidia.com.
