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

Tóm tắt nhanh
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.
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.
NVIDIA/SkillSpector
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.
I.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ờ
--recursivevà 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.
II.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.
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ọ.
III.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.
- Chọn cách càiuv, từ mã nguồn, hoặc Docker nếu không muốn cài Python
- Cài SkillSpectorchạy một lệnh uv hoặc make install, hoặc build ảnh Docker
- Quét thử bằng --no-llmchạ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
A.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.
uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspectorLệ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:
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à ].
B.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.
# 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 installgit 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.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.
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:
docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llmThay ./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:
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm --format json --output report.jsonCó thể đặt alias cho đỡ gõ:
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llmD.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:
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOFThay sk-ant-... bằng key thật của bạn. Rồi chạy Docker kèm --env-file:
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.
IV.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:
skillspector scan ./my-skill/ --no-llmNế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:
skillspector scan https://github.com/user/my-skillThay user/my-skill bằng repo thật bạn muốn kiểm tra.
V.Dùng vào việc thật
A.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:
skillspector scan https://github.com/user/my-skill --no-llmCô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
B.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ơ:
skillspector scan ./my-skills/ --recursive --max-skills 100 --no-llm --format jsonMặ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:
python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.jsonC.Đư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:
skillspector scan ./my-skill/ --format sarif --output report.sarifKhi đã 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:
skillspector baseline ./my-skill/ -o .skillspector-baseline.yamlCác lần quét sau chỉ báo cáo phát hiện mới:
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yamlThê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 đủ.
D.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:
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:
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.jsonBá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ê.
VI.Lỗi hay gặp và cách xử lý
- Báo thiếu lệnh
skillspectorhoặcmake installlỗ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--excludenên phạm vi chỉ quét một phần. Khi đó báo cáo không cho nhãnSAFE. Tăng--max-skillshoặ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-registrytừ 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.
VII.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 đủ.


