SkillSpector 소개
Claude Code, Codex CLI, Gemini CLI 같은 코딩 에이전트는 "스킬(skill)"이라는 형태로 외부 지시문과 스크립트를 가져와 실행합니다. 문제는 이 스킬들이 대체로 암묵적 신뢰를 받으며 거의 검증 없이 설치된다는 점입니다. SkillSpector는 NVIDIA가 공개한 보안 스캐너로, 스킬을 설치하기 전에 "이 스킬을 설치해도 안전한가?"라는 질문에 답하는 것을 목표로 합니다.
SkillSpector가 인용하는 연구에 따르면 대규모 마켓플레이스에서 수집한 스킬 가운데 26.1%가 최소 한 개 이상의 취약점을 포함하고, 5.2%는 악의적 의도를 보이는 것으로 나타났습니다. 즉 사용자가 무심코 가져오는 스킬 상당수가 프롬프트 인젝션(Prompt Injection), 자격 증명 탈취, 공급망(Supply Chain) 위험 같은 문제를 안고 있을 수 있습니다. SkillSpector는 이런 스킬을 설치 시점 이전에 정적·의미 분석으로 걸러내는 게이트 역할을 합니다.
설치 대상은 단일 SKILL.md 파일부터 디렉토리, zip 파일, Git 저장소, 원격 URL까지 다양한 형태를 지원합니다. 검사 결과는 0부터 100까지의 위험 점수와 심각도 라벨, 그리고 설치 여부 추천으로 정리되며, 사람이 읽는 터미널 출력뿐 아니라 CI 파이프라인이나 에디터 도구가 그대로 소비할 수 있는 기계 판독 형식으로도 출력됩니다. 본 게시물에서는 SkillSpector가 풀려는 문제, 2단계 검사 파이프라인, 탐지 범주, 설치·통합 방법, 그리고 도구의 신뢰 모델과 한계를 정리합니다.
SkillSpector가 다루는 문제: 검증되지 않은 스킬의 위험
SkillSpector의 출발점은 에이전트 스킬 생태계에 대한 실증 연구입니다. 저장소는 Liu 등(2026)의 "Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale" 연구를 근거로 들며, 주요 마켓플레이스에서 수집한 42,447개 스킬을 분석한 결과를 인용합니다. 이 데이터셋에서 26.1%의 스킬이 취약점을 하나 이상 포함했고, 5.2%는 악의적 의도를 보였으며, 실행 가능한 스크립트를 포함한 스킬은 그렇지 않은 스킬보다 취약할 확률이 2.12배 높았습니다.
스킬은 사람이 일일이 코드를 읽기에는 양이 많고, 코딩 에이전트가 자동으로 설치·실행하기 때문에 위험이 빠르게 전파됩니다. SkillSpector는 이 지점을 겨냥해, 스킬을 실제로 실행하지 않고도 위험 신호를 미리 드러내는 사전 점검 도구로 설계되었습니다.
SkillSpector의 2단계 검사 파이프라인
SkillSpector는 두 단계로 나뉜 탐지 파이프라인을 사용합니다.
1단계 정적 분석 (Static Analysis) 은 11개의 정적 분석기로 스킬의 모든 파일을 빠르게 훑습니다. 정규식 기반 패턴 매칭, 위험한 호출(exec, eval, subprocess 등)을 잡아내는 AST 기반 행위 분석, 알려진 악성코드·웹셸 시그니처를 찾는 YARA 매칭, 그리고 의존성의 알려진 취약점(CVE)을 조회하는 OSV.dev 연동이 여기에 포함됩니다. 저자는 이 단계가 재현율(recall)은 높지만 정밀도(precision)는 중간 수준이라 일부 오탐(false positive)이 발생할 수 있다고 설명합니다.
2단계 LLM 의미 분석 (LLM Semantic Analysis) 은 선택 사항으로, 정적 분석이 잡은 후보를 맥락과 의도 관점에서 다시 평가합니다. 이 단계는 오탐을 걸러내고 사람이 읽을 수 있는 설명을 덧붙이며, 저자에 따르면 정밀도를 약 87%까지 끌어올립니다. LLM에 보내는 프롬프트에는 악성 스킬이 분석 자체를 조작하지 못하도록 안티 탈옥(anti-jailbreak) 보호 장치가 들어 있습니다. LLM 분석을 끄고 정적 분석만 빠르게 돌리려면 --no-llm 옵션을 사용합니다.
검사가 끝나면 SkillSpector는 위험 점수를 계산합니다. CRITICAL 항목은 +50점, HIGH는 +25점, MEDIUM은 +10점, LOW는 +5점이 더해지고, 실행 가능한 스크립트가 있으면 1.3배 가중치가 적용됩니다. 점수 구간에 따라 심각도와 추천이 결정됩니다.
| 점수 | 심각도 | 추천 |
|---|---|---|
| 0-20 | LOW | SAFE (설치 가능) |
| 21-50 | MEDIUM | CAUTION (주의) |
| 51-80 | HIGH | DO NOT INSTALL (설치 금지) |
| 81-100 | CRITICAL | DO NOT INSTALL (설치 금지) |
SkillSpector가 탐지하는 취약점 범주
SkillSpector는 17개 범주에 걸쳐 총 68개의 취약점 패턴을 탐지합니다. 각 패턴에는 고유 ID(예: P1, E2, SC4)와 심각도가 부여되어 있어, 검사 결과에서 어떤 규칙이 걸렸는지 추적할 수 있습니다. 대표적인 범주는 다음과 같습니다.
| 범주 | 예시 패턴 | 설명 |
|---|---|---|
| 프롬프트 인젝션 | 지시 무력화, 숨겨진 지시문 | 안전 제약을 무시하게 하거나 주석·비가시 텍스트에 악성 지시를 숨김 |
| 데이터 유출 | 환경 변수 수집, 컨텍스트 유출 | API 키·시크릿을 모으거나 대화 컨텍스트를 외부로 전송 |
| 공급망 | 원격 스크립트 실행, 알려진 취약 의존성 | curl | bash 패턴, OSV.dev로 확인한 CVE 보유 의존성 |
| 위험한 코드 (AST) | exec(), 동적 실행 체인 |
임의 코드 실행을 가능케 하는 호출과 그 연쇄 |
| 오염 추적 (Taint Tracking) | 자격 증명 유출 체인 | 시크릿·파일 내용이 네트워크 출력 싱크로 흘러가는 흐름 |
| MCP 도구 오염 | 숨겨진 지시문, 유니코드 기만 | 도구 메타데이터에 숨긴 지시나 동형 문자(homoglyph) 위장 |
이 밖에도 권한 상승(Privilege Escalation), 과도한 자율성(Excessive Agency), 출력 처리(Output Handling), 시스템 프롬프트 유출, 메모리 오염(Memory Poisoning), 도구 오용(Tool Misuse), 로그(rogue) 에이전트, 트리거 남용, 거부 무력화(Anti-Refusal), YARA 시그니처, MCP 최소 권한(Least Privilege) 등의 범주가 포함됩니다. 공급망 점검의 SC4 패턴은 OSV.dev API를 호출해 PyPI·npm 의존성의 실시간 CVE 정보를 조회하며, API 키가 필요 없고 네트워크 접근이 불가능할 때는 내장 폴백 목록으로 동작합니다.
SkillSpector 설치 및 사용법
SkillSpector는 Python 3.12 이상에서 동작하며, uv 또는 pip로 설치할 수 있습니다. CLI만 빠르게 설치하려면 다음과 같이 합니다.
uv tool install git+https://github.com/NVIDIA/skillspector.git
기본 사용법은 검사 대상을 scan 명령에 넘기는 것입니다. 로컬 디렉토리, 단일 파일, Git 저장소, zip 파일을 모두 같은 방식으로 받습니다.
# 로컬 스킬 디렉토리 검사
skillspector scan ./my-skill/
# 단일 SKILL.md 파일 검사
skillspector scan ./SKILL.md
# Git 저장소 검사
skillspector scan https://github.com/user/my-skill
검사 결과는 네 가지 형식으로 출력할 수 있습니다. 기본값인 터미널 출력은 사람이 읽기 좋게 표로 정리되며, JSON·Markdown·SARIF 형식은 각각 자동화, 문서화, CI/IDE 도구 연동에 적합합니다.
# JSON 출력 (기계 판독용)
skillspector scan ./my-skill/ --format json --output report.json
# SARIF 출력 (CI/CD·IDE 연동용)
skillspector scan ./my-skill/ --format sarif --output report.sarif
이미 확인을 마친(triage) 발견 항목을 기준선(baseline)으로 저장해두면, 이후 재검사에서는 새로 등장한 문제만 점수에 반영됩니다. Python이 없는 환경을 위해 저장소에 포함된 Dockerfile로 컨테이너 이미지를 빌드해 실행하는 방법도 제공됩니다.
SkillSpector를 설치 게이트로 통합하기
SkillSpector는 단독 감사 도구로 쓰는 것뿐 아니라 다른 도구가 호출하는 구성요소로 설계되었습니다. scan 명령의 종료 코드와 JSON 출력이 안정적인 계약(contract) 역할을 합니다. 종료 코드는 위험 점수가 50 이하면 0, 50을 초과하면 1, 입력 오류 등 실패면 2를 반환합니다. 다만 종료 코드는 SAFE와 CAUTION을 모두 0으로 묶기 때문에, 둘을 다르게 처리하려면 JSON 출력의 recommendation 필드를 읽는 편이 정확합니다.
특히 SkillSpector는 Model Context Protocol 서버로 실행할 수 있어, MCP를 지원하는 에이전트가 검사를 도구처럼 호출하고 그 결과에 따라 스킬·MCP 설치를 차단할 수 있습니다. 이렇게 하면 별도의 감사 단계가 아니라 런타임 가드레일로 동작합니다. 서버는 scan_skill이라는 단일 도구를 노출하며, 위험 점수와 심각도, 추천, 설치 가능 여부, 발견 항목을 구조화해 돌려줍니다.
# MCP extra 설치 후 Claude Code에 등록
claude mcp add skillspector -- skillspector mcp
Python 코드에서 직접 호출할 때는 내부 LangGraph 워크플로를 실행하는 API를 사용합니다.
from skillspector import graph
result = graph.invoke({
"input_path": "/path/to/skill",
"output_format": "json", # terminal, json, markdown, sarif
"use_llm": True, # False면 정적 분석만 수행
})
설치 게이트로 쓸 때 권장되는 매핑은 SAFE는 허용, CAUTION은 사용자에게 경고, DO_NOT_INSTALL은 차단입니다. 다만 게이트를 얼마나 엄격하게 적용할지는 통합하는 쪽의 정책 결정에 맡겨져 있습니다.
SkillSpector의 신뢰 모델과 한계
SkillSpector는 샌드박스가 아니라 다층 방어(defense-in-depth)의 한 겹입니다. 저자는 도구가 무엇을 하고 무엇을 하지 않는지 분명히 밝혀 둡니다. SkillSpector는 검사 대상 스킬을 실행하지 않으며, 모든 분석은 정적(정규식, Python AST, YARA)으로 이뤄지고 LLM은 파일 내용만 평가합니다. LLM 분석을 켜면 파일 내용이 설정된 LLM 제공자 엔드포인트로 전송되므로, 내용을 로컬에만 두려면 --no-llm을 사용해야 합니다. 공급망 점검(SC4)은 의존성 이름과 버전을 OSV.dev로 보내며, 이는 --no-llm에서도 동작합니다.
한계도 명시되어 있습니다. 정적 분석은 영어 외 언어로 작성된 패턴을 놓칠 수 있고, 이미지 안의 텍스트나 암호화·컴파일된 코드는 분석할 수 없으며, 런타임 동작은 다루지 않습니다. 즉 SkillSpector는 설치 전에 위험 패턴을 드러내 줄 뿐, 사용자가 설치를 강행한 스킬을 격리하거나 차단해주지는 않습니다.
SkillSpector의 라이선스
SkillSpector는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
SkillSpector 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 