SkillSpector 설치 방법과 첫 검사
먼저 스캐너를 설치하고 버전을 확인한다. 공식 README는 uv 도구 설치를 안내하며, 확인한 2.12.0 버전은 Python 3.12 이상, 3.15 미만을 요구한다. 다음 첫 줄은 공식 설치 방법이고, 둘째 줄부터는 스킬을 설치하는 대신 검토 폴더를 읽어 보고서로 저장하는 명령이다. uv가 준비된 터미널에서 실행한다.
uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector --version
skillspector scan ./review-skill/ --no-llm --format json --output report.json외부 에이전트 스킬은 설명서 한 장으로 끝나지 않는다. 작업 지침을 담은 SKILL.md에 스크립트와 설정 파일이 함께 들어갈 수 있다. 코딩 에이전트가 이 지침을 따르며 도구를 호출하면, 에이전트에 이미 허용된 프로젝트 파일이나 자격증명에 접근할 수 있다. 스킬을 추가하는 일은 결국 다른 사람이 쓴 지시와 코드를 내 작업 공간에 들이는 결정이다.
엔비디아의 SkillSpector는 이 결정을 앞당겨 검토하는 보안 스캐너다. 스킬을 실행하기 전에 파일을 읽어 의심스러운 지시, 자격증명 접근, 외부 스크립트 실행, 의존성 위험 등을 찾고 보고서를 남긴다. 보고서는 설치 허가증이 아니라 사람이 원문을 열어 볼 위치를 좁히는 도구다. 여러 사람이 외부 스킬을 추가하는 팀이나 고객 자료를 다루는 프로젝트에서 특히 쓸모가 있다.
스킬은 먼저 보관하고, 에이전트에는 아직 연결하지 않는다
도입 후보를 에이전트가 자동으로 읽는 스킬 폴더에 바로 넣지 않는다. 별도 검토 폴더에 내려받아 저장소 주소와 커밋, 파일 목록을 기록한다. “문서 정리”라는 설명인데 SSH 키를 읽거나 원격 설치 스크립트를 실행하도록 요구한다면, 목적과 필요한 권한이 맞지 않는다. 검토를 맡은 PM도 작업 목적, 필요한 데이터, 외부 전송 대상부터 개발자에게 물을 수 있다.
아래는 위험 패턴을 의도적으로 넣은 설명용 파일이다. 실제 악성 패키지가 아니며, 명령을 실행하지 않고 텍스트만 검사했다. example.invalid를 전송 대상 예시로 썼고 실제 비밀값은 넣지 않았다. 7행은 기존 지시를 무시하라고 하고, 8행은 SSH 개인키를 읽어 보내라고 하며, 9행은 내려받은 스크립트를 바로 실행하라고 한다.
검토 폴더를 스캔하고 JSON 보고서를 남긴다
SkillSpector는 로컬 폴더뿐 아니라 Git 저장소 URL, 압축 파일, 단일 파일도 받는다. 처음 검토할 때는 어떤 파일을 검사했는지 남기기 쉬운 로컬 사본을 쓰는 편이 낫다. 보고서는 JSON 외에 터미널, Markdown, SARIF로도 출력할 수 있다. 개발자는 JSON을 자동화에 쓰고, PM이나 보안 검토자는 파일 위치와 설명을 읽으며 승인 여부를 기록하면 된다.
2026년 10월 2일 Linux에서 Python 3.12.13 가상환경에 SkillSpector 2.12.0을 설치해 위 설명용 파일을 검사했다. 사용한 소스 커밋은 2226747e4ca9다. 첫 보고서의 위험 점수는 100, 심각도는 CRITICAL, 권고는 DO_NOT_INSTALL이었다. 활성 탐지는 5건이며 명령 종료 코드는 1이었다. 이 값은 설명용 입력 한 개의 결과이지, 외부 스킬 전체의 위험 비율이 아니다.
점수보다 파일 위치와 실제 동작을 먼저 읽는다
보고서의 issues에는 규칙 ID, 심각도, 파일과 행 번호, 잡힌 문자열, 설명과 수정 제안이 들어 있다. 이번에는 7행에서 P1·RA1·YR4가 함께 잡혔고, 8행에서 PE3, 9행에서 SC2가 잡혔다. 같은 문장을 여러 검사기가 탐지할 수 있으므로 5건을 서로 다른 공격 5개로 읽으면 안 된다. risk_assessment.score 역시 사고 확률을 뜻하지 않는다.
사람의 검토는 “이 문자열이 있는가” 다음 질문을 맡는다. 그 문장이 공격 사례를 설명하는 인용인지 실제 실행 지시인지, 스크립트가 정말 필요한 파일만 읽는지, 전송 대상이 업무상 승인된 곳인지 확인한다. 이번 파일처럼 교육용 문장에도 경보가 생길 수 있다. 오탐이라고 판단하려면 해당 위치의 원문과 실행 경로를 함께 봐야 한다.
실습에서는 의심 문장 3개를 제거하고, 사용자가 고른 로컬 Markdown 파일의 제목만 제안하며 저장 전 승인을 받는 내용으로 다시 썼다. 바꾼 사본을 동일 버전의 정적 검사로 재검사한 결과 활성 탐지는 0건, 점수는 0, 권고는 SAFE, 종료 코드는 0이었다. 아래는 두 실제 JSON 보고서에서 같은 필드를 발췌한 비교다. 문구를 지웠다는 사실과 정적 탐지가 사라졌다는 사실을 함께 보여 준다.
설치 허용은 사람이 정하고, 바뀐 파일은 다시 검사한다
자격증명 수집이나 목적과 무관한 원격 실행이 확인되면 원본 후보를 거절한다. 공급자가 수정했거나 팀이 별도 사본을 고쳤다면, 수정된 정확한 버전을 다시 검사한다. 남은 경보를 수용할 때는 파일·규칙·이유와 승인자를 기록한다. 보고서가 깨끗해도 스킬에 프로젝트 전체 쓰기 권한이나 운영용 비밀값을 자동으로 내줄 이유는 없다. 필요한 폴더와 테스트용 자격증명부터 허용한다.
반복 검사에서는 baseline으로 검토를 마친 탐지를 제외할 수 있다. 공식 문서의 skillspector baseline은 현재 탐지 전체를 baseline으로 만들기 때문에, 결과를 읽지 않고 실행해 경보를 일괄 승인하면 안 된다. 정확한 지문 방식은 소스나 스캐너 버전이 바뀌면 다시 검토하게 한다. 넓은 glob 규칙은 변경 후에도 탐지를 숨길 수 있어 파일과 규칙 범위를 좁혀야 한다. --show-suppressed로 숨긴 탐지도 주기적으로 확인한다.
자동 설치 파이프라인을 연결한다면 종료 코드만 보고 설치하지 않는다. 2.12.0에서는 다음 옵션으로 활성 탐지와 불완전한 분석을 실패로 처리할 수 있다. 실패하면 설치 작업을 멈추고 보고서를 검토 대기열로 넘기도록 팀이 연결해야 한다. 스캐너 자체가 에이전트의 모든 설치 경로를 자동으로 막는 것은 아니다.
skillspector scan ./review-skill/ --no-llm --fail-on-findings --fail-on-incomplete --format json --output report.json이번 수정 사본도 이 두 옵션을 켜서 검사했다. 운영에서는 입력 커밋, 스캐너 버전, 보고서, 승인 이유를 한 묶음으로 남기고, 스킬이 업데이트되거나 동봉 스크립트·의존성이 바뀌면 다시 검사한다. 에이전트 권한 설계에서 공유 서비스 접근을 분리하는 문제도 함께 보면, 파일 검사와 실행 권한 제한을 따로 관리해야 하는 이유가 드러난다.
LLM 검사를 더할 때는 보낼 데이터부터 정한다
선택 기능인 의미 분석은 스킬의 설명과 코드가 하는 일을 비교하고, 정적 경보가 문맥상 오탐인지 살피는 데 도움을 준다. --no-llm을 빼고 공급자를 설정하면 이런 검사를 추가할 수 있다. 해당 분석의 소스에는 스킬 메타데이터, 분석 대상 파일 내용, 정적 탐지와 주변 문맥을 프롬프트에 넣는 경로가 있다. 외부 공급자를 쓰면 그 자료가 모델 엔드포인트로 전달될 수 있다. 사내 코드나 고객 정보가 들어 있는 스킬은 데이터 반출 정책을 먼저 적용하고, 승인된 사내 엔드포인트나 로컬 모델을 선택한다.
--no-llm은 LLM 호출을 생략한다는 뜻이지 네트워크 전체를 차단한다는 뜻이 아니다. 의존성 검사는 OSV.dev에 패키지 생태계·이름·버전을 조회할 수 있고, Git URL을 입력하면 원격 파일을 가져온다. 공식 README는 OSV 조회의 오프라인 대체 경로도 안내한다. 엄격한 반출 금지가 필요하면 로컬 입력을 준비한 뒤 별도 네트워크 정책을 적용하고, 어떤 조회가 빠졌는지 분석 완전성 기록을 확인한다.
정적 점수 0은 검사기가 그 입력에서 활성 패턴을 찾지 못했다는 결과다. 런타임에 내려받는 코드나 새 공격 방식의 안전성을 증명하지 않으며, LLM을 더해도 승인 책임은 사라지지 않는다. 팀이 남겨야 할 마지막 기록은 “점수 0” 하나가 아니라 어느 버전을 어떤 권한으로 쓰기로 했는지다.