# NVIDIA/SkillSpector: quét lỗ hổng skill AI agent 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 mã nguồn mở của NVIDIA, dành cho các skill của AI agent như Claude Code, Codex CLI, Gemini CLI và MCP. Nó trả lời câu hỏi "skill này có an toàn để cài không?" bằng điểm rủi ro 0-100 và báo cáo chi tiết. Cài bằng một lệnh uv hoặc Docker, chạy được ngay ở chế độ không cần API key.

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

SkillSpector là công cụ dòng lệnh (viết bằng Python) của NVIDIA, dùng để quét bảo mật các "skill" của AI agent như Claude Code, Codex CLI, Gemini CLI hay MCP. 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ó trả về báo cáo cho biết skill đó có lỗ hổng, mẫu mã độc hay rủi ro nào không.

Vì sao việc này đáng quan tâm? Skill chạy trên máy bạn với mức tin cậy ngầm định và gần như không ai kiểm tra trước. README dẫn 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ố ý độc hại. Tải một skill lạ về cài giống như chạy một file lạ trên máy, nhưng nhiều người không để ý.

SkillSpector hợp với dev mới, người làm văn phòng hay chủ doanh nghiệp nhỏ đang bắt đầu dùng AI agent và hay tải skill từ GitHub. Điểm đáng giá nhất: bạn quét được ngay bằng chế độ tĩnh, không cần tài khoản hay API key. Cần phân tích sâu hơn thì gắn thêm một mô hình ngôn ngữ (LLM) sau. Repo hiện có khoảng 25.676 sao và 2.266 fork, giấy phép Apache-2.0.

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

SkillSpector nằm trong quy trình "NVIDIA Verified Skills": quét, đánh giá và ký skill trước khi xuất bản lên catalog skill của NVIDIA.

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

- **Python từ 3.12 đến dưới 3.16** nếu cài bằng uv hoặc từ mã nguồn (theo pyproject.toml).
- **uv hoặc pip.** Makefile dùng uv nếu có, không thì dùng pip.
- **Docker** nếu bạn không muốn cài Python. Ảnh Docker dựa trên Python 3.12-slim-bookworm.
- **Git** nếu cài từ mã nguồn hoặc quét một link Git.
- **Không cần GPU, không cần API key** khi quét tĩnh với `--no-llm`.
- **API key của một nhà cung cấp LLM** chỉ cần nếu bạn muốn phân tích ngữ nghĩa. README liệt kê các lựa chọn như openai, anthropic, bedrock, gemini, azure_openai, ollama (chạy local, không cần key) và một số CLI cục bộ.
- **Hệ điều hành:** README không nêu rõ danh sách hệ điều hành. Các lệnh trong README viết kiểu Linux/macOS (ví dụ `source .venv/bin/activate`, `$PWD`). Nếu bạn dùng Windows, README chưa hướng dẫn riêng.

```note
Phần cài đặt có thông báo: dự án sẽ tải thêm một số phần mềm mã nguồn mở của bên thứ ba. Hãy xem giấy phép của chúng trước khi dùng. Khi điền API key vào file .env, đừng đưa file này lên GitHub hay gửi cho người khác. Gọi LLM qua nhà cung cấp có thể phát sinh phí theo bảng giá của họ.
```

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

Bạn chọn một trong ba cách: uv, từ mã nguồn, hoặc Docker. Với người mới, mình khuyên uv hoặc Docker vì ít bước nhất.

```steps
- Chọn cách cài | uv, từ mã nguồn, hoặc Docker nếu không muốn cài Python
- Cài SkillSpector | chạy một lệnh uv hoặc make install, hoặc build ảnh Docker
- Quét thử bằng --no-llm | chạy trên một thư mục skill, không cần key
- Xem báo cáo | đọc điểm rủi ro, xuất JSON/Markdown/SARIF nếu cần
- (Tuỳ chọn) Gắn LLM | đặt SKILLSPECTOR_PROVIDER và khoá API để phân tích sâu
```

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

Mở terminal ở bất kỳ thư mục nào. README nhắc nên tạo và kích hoạt môi trường ảo trước, vì các mục `make` đều giả định môi trường ảo đang bật. Với cách `uv tool install` thì uv tự lo phần cô lập.

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

Lệnh này tải SkillSpector thẳng từ GitHub và cài thành một công cụ chạy bằng lệnh `skillspector`. Dòng thứ hai là ghi chú cách cập nhật sau này, chép đúng như README.

Nếu bạn định chạy `skillspector mcp` thì cài kèm phần mở rộng MCP ngay từ đầu:

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

Chỗ hay vấp: dấu nháy đơn ở hai đầu là bắt buộc để terminal không hiểu nhầm dấu `[` và `]`.

### Cách 2: cài từ mã nguồn

Cách này hợp nếu bạn muốn xem mã hoặc đóng góp.

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

`git clone` tải mã về, `cd skillspector` vào thư mục vừa tải. Hai dòng tạo môi trường ảo cho bạn chọn một: dùng uv hoặc dùng python3 có sẵn. Cuối cùng `make install` cài bản dùng thật. Lưu ý quan trọng: phải bật môi trường ảo (dòng `source ...`) trước khi chạy `make install`. Lệnh `source` này là cú pháp Linux/macOS. README chưa ghi lệnh kích hoạt tương đương cho Windows. Người dùng Windows nên chọn Docker hoặc cách 1.

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

Build ảnh từ Dockerfile có sẵn trong repo. Bạn phải đang đứng trong thư mục `skillspector` đã 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
```

Thay `./my-skill/` bằng đường dẫn tới skill của bạn, tính từ thư mục bạn đang đứng. 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
```

Có thể đặt alias cho đỡ gõ:

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

### Tuỳ chọn: gắn LLM để phân tích sâu

Chọn nhà cung cấp bằng biến `SKILLSPECTOR_PROVIDER`. Ví dụ với Anthropic, tạo file `.env` ở thư mục bạn chạy lệnh:

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

Thay `sk-ant-...` bằng key thật của bạn. Rồi chạy Docker kèm `--env-file`:

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

Bạn dùng nhà cung cấp khác thì xem bảng trong README và file `.env.example` trong repo để biết biến nào cần điền. Mục `codex_cli` trong README ghi là đã bị vô hiệu hoá, vì chế độ sandbox của nó vẫn cho đọc file trên máy. Hãy chọn nhà cung cấp API hoặc CLI khác.

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

README không đưa ra lệnh kiểm tra phiên bản riêng. Cách kiểm tra thực tế nhất là quét thử một thư mục skill bất kỳ ở chế độ tĩnh:

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

Nếu cài đúng, terminal in ra báo cáo gồm điểm rủi ro từ 0 đến 100, nhãn mức độ nghiêm trọng và khuyến nghị. Nếu terminal báo không tìm thấy lệnh `skillspector`, nghĩa là cài chưa xong hoặc môi trường ảo chưa bật. Với Docker, bạn chạy lệnh `docker run` ở trên và nhận báo cáo tương tự.

Muốn thử nhanh mà chưa có skill nào, bạn có thể quét một skill công khai bằng link:

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

Thay `user/my-skill` bằng repo thật bạn muốn kiểm tra.

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

### Kiểm tra skill tải từ GitHub trước khi cài

Bạn là dev mới, thấy một skill Claude Code hay trên mạng. Đừng cài vội. Quét trước:

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

Công cụ tự tải repo (có giới hạn kích thước, tối đa 100 MiB) và phân tích. Bạn nhận điểm rủi ro và danh sách phát hiện. Nếu thấy dấu hiệu như gửi dữ liệu ra ngoài hay prompt injection thì bỏ qua skill đó. Nếu sạch, bạn có thêm cơ sở để yên tâm hơn, dù không phải bảo đảm tuyệt đối.

> Cài skill mà không quét giống như chạy file lạ trên máy: thường ổn, nhưng một lần không ổn là mất nhiều.
>
> — Ông T

### Rà cả thư mục skill của team

Bạn phụ trách IT cho một nhóm nhỏ, mọi người đã gom skill vào một thư mục `my-skills/`. Dùng `--recursive` để quét từng thư mục con có SKILL.md như một skill độc lập, và xuất JSON để lưu hồ sơ:

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

Mặc định chỉ quét tối đa 32 skill. Cờ `--max-skills` nâng hoặc hạ 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). Nếu có skill bị bỏ lại do vượt giới hạn, báo cáo tổng vẫn ghi rõ phần đó chưa được quét. Muốn quét nhanh nhiều skill song song thì README có script batch:

```bash
python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json
```

### Đưa vào CI và bỏ qua cảnh báo đã duyệt

Bạn là dev có repo chứa skill riêng, muốn mỗi lần đẩy code đều được quét. Xuất SARIF cho CI/IDE:

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

Khi đã xem xét và chấp nhận một số cảnh báo, tạo baseline một lần rồi commit file này:

```bash
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml
```

Các lần quét sau chỉ báo cáo phát hiện mới:

```bash
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml
```

Thêm `--show-suppressed` nếu muốn xem lại những gì đang bị bỏ qua. Trong CI, thêm `--fail-on-incomplete` để pipeline báo lỗi khi phạm vi quét chưa đầy đủ.

### Theo dõi một máy chủ MCP thay đổi ra sao

Bạn cần biết một máy chủ MCP trong registry chính thức có đổi gì giữa hai thời điểm. Quét một máy chủ theo tên:

```bash
skillspector scan 'ac.inference.sh/mcp' --mcp-registry --format json --output current.json
```

Để so sánh, lưu hai bản chụp registry rồi quét lần lượt:

```bash
skillspector scan registry-before.json --mcp-registry --format json --output previous.json
skillspector scan registry-after.json --mcp-registry --format json --mcp-registry-compare previous.json --output compared.json
```

Báo cáo có mục `comparison` liệt kê máy chủ thêm mới, bị gỡ và trường thay đổi. Công cụ không tải hay chạy các endpoint của máy chủ được liệt kê.

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

- **Báo thiếu lệnh `skillspector` hoặc `make install` lỗi.** Thường do môi trường ảo chưa bật, hoặc Python ngoài khoảng 3.12 đến dưới 3.16. Kiểm tra phiên bản Python, bật lại môi trường ảo rồi cài lại. Nếu vẫn vướng, dùng Docker để tránh chuyện phiên bản.
- **Báo cáo xuất bằng Docker không ghi được hoặc thuộc quyền root.** Chạy với `--user "$(id -u):$(id -g)"` như ví dụ ở trên, và ghi vào thư mục đã gắn qua `-v`.
- **Gặp `IngestLimitExceededError`.** Đầu vào vượt giới hạn: 100 MiB cho mỗi lần nạp, hoặc quá 10.000 mục trong một file zip. Công cụ cố ý dừng để chống zip bomb. Hãy quét phần nhỏ hơn thay vì cố nới giới hạn.
- **Quét bộ sưu tập mà báo "chưa đầy đủ".** Có thể do vượt `--max-skills`, hoặc do bạn dùng `--exclude` nên phạm vi chỉ quét một phần. Khi đó báo cáo không cho nhãn `SAFE`. Tăng `--max-skills` hoặc quét từng skill riêng, và đừng coi kết quả là sạch hoàn toàn.
- **Chế độ registry trả mã thoát 2.** Chế độ `--mcp-registry` từ chối các cờ dành riêng cho skill như `--transitive`, `--use-shipped-baseline`. Bỏ các cờ đó đi khi quét registry.
- **Phân tích LLM không chạy hoặc báo thiếu key.** Kiểm tra `SKILLSPECTOR_PROVIDER` đã đặt đúng tên và biến key tương ứng đã điền (xem bảng trong README và `.env.example`). Nếu chỉ cần quét nhanh, thêm `--no-llm`.

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

**Điểm mạnh.** Cài dễ, quét tĩnh chạy ngay không cần key hay GPU. Báo cáo rõ (điểm 0-100, nhiều định dạng), hỗ trợ CI qua SARIF, có baseline để giảm cảnh báo lặp, và chấp nhận nhiều kiểu đầu vào. Công cụ do NVIDIA phát hành theo giấy phép Apache-2.0 và vẫn được cập nhật trong những tháng gần đây.

**Giới hạn.** Đây là công cụ hỗ trợ, không phải bảo đảm. Báo cáo sạch không có nghĩa skill chắc chắn an toàn, và có thể có cảnh báo dương tính giả, nên mới có tính năng baseline. Muốn phân tích sâu bằng LLM thì bạn phải cấu hình nhà cung cấp và có thể mất phí. Tài liệu chưa có hướng dẫn riêng cho Windows ở phần cài đặt. Các giới hạn dung lượng, số skill và thời gian khiến những bộ sưu tập rất lớn có thể chỉ được quét một phần.

**Khi nào chọn cách khác.** Nếu bạn chỉ dùng skill do chính mình viết, công cụ này ít cần thiết. Nếu bạn cần kiểm thử bảo mật toàn bộ ứng dụng hay hạ tầng, đây không phải công cụ phù hợp, vì nó chuyên về skill của AI agent và máy chủ MCP. Còn nếu bạn hay cài skill của người khác, thêm một bước quét trước khi cài là thói quen rẻ và đáng giữ.

## 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, nên dùng miễn phí. Chế độ quét tĩnh với `--no-llm` không cần key. Nếu bạn gắn một nhà cung cấp LLM trả phí thì chi phí tính theo nhà cung cấp đó; README không nêu giá.

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

Tư liệu không yêu cầu GPU. Quét tĩnh chạy bình thường trên máy thường. Nếu muốn LLM chạy cục bộ, README nhắc đến Ollama, vLLM và llama.cpp, nhưng phần cứng cụ thể thì chưa có thông tin.

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

README chưa ghi rõ danh sách hệ điều hành hỗ trợ, và các lệnh mẫu viết theo kiểu Linux/macOS. Người dùng Windows có thể thử cài bằng uv hoặc dùng Docker, nhưng README chưa có hướng dẫn riêng cho Windows.

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

Với `--no-llm`, README mô tả đây là phân tích tĩnh. Khi bật phân tích LLM, bạn chọn nhà cung cấp và endpoint, nên mức độ riêng tư phụ thuộc vào lựa chọn đó. README cho biết có thể dùng máy chủ cục bộ như Ollama. Riêng việc tra cứu CVE thì công cụ hỏi OSV.dev và có chế độ dự phòng offline.

### SkillSpector khác gì việc tự đọc mã skill?

Nó tự động hoá việc rà soát theo 71 mẫu lỗ hổng trong 17 nhóm, chấm điểm rủi ro 0-100 và xuất báo cáo nhiều định dạng. Bạn vẫn nên đọc những phát hiện quan trọng. README chưa so sánh trực tiếp với công cụ khác.

### Quét được những loại đầu vào nào?

Thư mục skill, một file SKILL.md, repo Git, URL và file zip. Ngoài ra còn quét hàng loạt bằng `--recursive` hoặc script batch, và quét dữ liệu MCP Registry bằng `--mcp-registry`.

### Có dùng được trong CI/CD không?

Có. Bạn xuất SARIF bằng `--format sarif`, dùng baseline để chỉ thấy phát hiện mới, và thêm `--fail-on-incomplete` để pipeline báo lỗi khi phạm vi quét chưa đầy đủ.
