SkillSpector: AI 에이전트 스킬을 위한 NVIDIA의 오픈소스 보안 스캐너 #

SkillSpector는 Claude Code, GitHub Copilot, Codex CLI, Gemini CLI 등의 프레임워크를 powering하는 모듈형 플러그인 및 확장 프로그램인 AI 에이전트 스킬을 위해 특별히 설계된 보안 스캔 도구입니다. NVIDIA에서 개발했으며 GitHub에서 10,273개의 스타를 기록했으며, 프로덕션 환경에서 검증되지 않은 에이전트 스킬을 설치하는 것과 관련된 급증하는 보안 문제를 해결합니다.

이 문서에서는 설치 방법, 스캔 기능, 취약점 감지, 에이전트 프레임워크와의 통합, AI 에이전트 생태계 보안을 위한 모범 사례를 다룹니다.

TL;DR #

AI 에이전트 스킬이 점점 더 인기를 얻으면서 검증되지 않은 스킬을 설치하는 보안 위험도 함께 증가하고 있습니다. SkillSpector는 800개 이상의 사이버보안 스킬에 대해 자동 스캔을 제공하며, 이러한 위험이 시스템에 도달하기 전에 취약점, 악성 패턴 및 보안 위험을 감지합니다. 모든 주요 에이전트 프레임워크를 지원하며 실행 가능한 복구 지침을 제공합니다.

SkillSpector란? #

SkillSpector은 중요한 관찰에서 탄생했습니다: AI 에이전트 스킬이 개발자 워크플로우 전반에 확산되면서 보안 공격 표면이 극적으로 확대되고 있습니다. 엄격한 코드 검토를 거치는 전통적인 소프트웨어 패키지와 달리 많은 에이전트 스킬은 간단한 텍스트 파일(SKILL.md)로, 임의의 작업을 수행하도록 LLM에게 지시합니다 — 셸 명령 실행, API 접근, 파일 수정 등을 포함합니다.

이 도구는 다음을 제공합니다:

• AI 에이전트 스킬 파일에 대한 자동화된 취약점 스캔
• 패턴 기반 악성 동작 감지 — 명령 삽입, 데이터 유출, 권한 상승 포함
• 프레임워크별 분석 — Claude Code, GitHub Copilot, Codex CLI 등 지원
• 복구 지침 — 감지된 취약점에 대한 구체적인 수정 사항 제공
• CI/CD 통합 — 자동 파이프라인에서 설치 전 스캔 지원

설치 가이드 #

사전 요구사항 #

• Python: 3.12+ (비동기 스캔 기능 필수)
• 운영 체제: Linux, macOS 또는 Windows WSL2
• 디스크 공간: 500MB (스캐너 + 스킬 데이터베이스)
• 네트워크: 스킬 데이터베이스 및 업데이트 다운로드에 필요

옵션 1: Pip 설치 #

# PyPI에서 SkillSpector 설치
pip install skillspector

# 설치 확인
skillspector --version

# 최신 스킬 데이터베이스 다운로드
skillspector update-db

옵션 2: 소스에서 설치 #

# 저장소 복제
git clone https://github.com/NVIDIA/SkillSpector.git
cd SkillSpector

# 가상 환경 생성
python -m venv .venv
source .venv/bin/activate

# 개발 모드 설치
pip install -e .

# 스캐너 초기화
skillspector init --download-database

옵션 3: Docker 배포 #

# 공식 이미지 가져오기
docker pull nvcr.io/nvidia/skillspector:latest

# 스캔 실행
docker run --rm \
  -v ${PWD}/skills:/app/skills \
  nvcr.io/nvidia/skillspector:latest \
  scan /app/skills

# 정기 스캔 예약
docker run -d \
  --name skillspector \
  -v ${PWD}/skills:/app/skills \
  -v ${PWD}/reports:/app/reports \
  nvcr.io/nvidia/skillspector:latest \
  daemon --interval 3600

스캔 기능 #

취약점 감지 카테고리 #

SkillSpector는 여러 카테고리에서 취약점을 감지합니다:

기본 스캔 #

# 단일 스킬 파일 스캔
skillspector scan my_skill.md

# 스킬 디렉토리 스캔
skillspector scan ./skills/

# 상세 출력으로 스캔
skillspector scan ./skills/ --verbose

# 보고서 생성하여 스캔
skillspector scan ./skills/ --output report.json --format json

고급 스캔 옵션 #

# 사용자 지정 심각도 임계값으로 스캔
skillspector scan ./skills/ --min-severity high

# 특정 취약점 카테고리로 스캔
skillspector scan ./skills/ --categories command_injection,data_exfiltration

# 프레임워크별 규칙으로 스캔
skillspector scan ./skills/ --framework claude-code

# 종속성 해석으로 스캔
skillspector scan ./skills/ --resolve-deps --follow-links

# 복구 제안과 함께 스캔
skillspector scan ./skills/ --remediate --output fixes/

Python API 사용법 #

from skillspector.scanner import SkillScanner
from skillspector.report import ReportFormatter

# 스캐너 초기화
scanner = SkillScanner(
    database_path="~/.skillspector/db",
    categories=["all"],
    severity_threshold="medium"
)

# 스킬 파일 스캔
result = scanner.scan("suspicious_skill.md")

# 결과 분석
print(f"발견된 취약점: {result.vulnerability_count}")
print(f"심각도: {result.overall_severity}")

# 상세 발견 항목 가져오기
for finding in result.findings:
    print(f"- [{finding.severity}] {finding.category}: {finding.description}")
    print(f"  위치: {finding.location}")
    print(f"  복구: {finding.remediation}")

# 서식 있는 보고서 생성
formatter = ReportFormatter(format="markdown")
report = formatter.generate(result)
print(report)

프레임워크별 분석 #

Claude Code 스킬 #

Claude Code 스킬은 Claude Code 에이전트에 대한 동작 지침을 정의하는 Markdown 파일입니다. SkillSpector는 다음 항목에 대해 이러한 파일을 분석합니다:

• 지침 내 위험한 셸 명령 패턴
• 스킬 내용 내 API 키 노출
• 의도된 범위를 벗어난 파일 시스템 접근
• 네트워크 연결 요청

# Claude Code 스킬 스캔
skillspector scan ~/.claude/skills/ --framework claude-code

# 위험한 명령 패턴 확인
skillspector check-commands ~/.claude/skills/ --framework claude-code

GitHub Copilot 스킬 #

Copilot 스킬은 Copilot 에이전트를 위한 사용자 지정 동작을 정의합니다. SkillSpector는 다음을 감지합니다:

• 승인되지 않은 코드 저장소 접근 패턴
• API 엔드포인트 조작
• 스킬 정의 내 자격 증명 수집
• Copilot 내장 도구를 통한 데이터 유출

# Copilot 스킬 스캔
skillspector scan ~/.config/github-copilot/skills/ --framework copilot

# 저장소 접근 패턴 확인
skillspector check-repo-access ~/.config/github-copilot/skills/

Codex CLI 스킬 #

Codex CLI 스킬은 Codex 에이전트의 기능을 확장합니다. SkillSpector는 다음을 찾습니다:

• 임의 명령 실행 지침
• 프로젝트 범위를 벗어난 파일 시스템 탐색
• 알려지지 않은 엔드포인트와의 네트워크 통신
• 환경 변수 조작

# Codex 스킬 스캔
skillspector scan ~/.codex/skills/ --framework codex

# 환경 조작 확인
skillspector check-env-manipulation ~/.codex/skills/

Gemini CLI 스킬 #

Gemini CLI 스킬은 Google의 Gemini CLI 에이전트에 대한 사용자 지정 지침을 제공합니다. SkillSpector는 다음을 분석합니다:

• 안전 조치를 우회할 수 있는 도구 사용 패턴
• 스킬 정의 내 프롬프트 삽입 벡터
• 데이터 접근 범위 위반
• 외부 API 호출 패턴

# Gemini CLI 스킬 스캔
skillspector scan ~/.gemini/skills/ --framework gemini

# 프롬프트 삽입 벡터 확인
skillspector check-injection ~/.gemini/skills/

CI/CD 통합 #

GitHub Actions 통합 #

# .github/workflows/skill-security.yml
name: Skill Security Scan
on:
  pull_request:
    paths:
      - 'skills/**'
      - '**/SKILL.md'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install SkillSpector
        run: pip install skillspector

      - name: Update vulnerability database
        run: skillspector update-db

      - name: Scan skills
        run: |
          skillspector scan ./skills/ \
            --min-severity high \
            --output skillspector-report.json \
            --format json

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: skillspector-report
          path: skillspector-report.json

GitLab CI 통합 #

# .gitlab-ci.yml
skill-security-scan:
  image: python:3.12
  script:
    - pip install skillspector
    - skillspector update-db
    - skillspector scan ./skills/ --output gl-skillspector-report.json --format json
  artifacts:
    reports:
      sast: gl-skillspector-report.json

설치 전 훅 #

#!/bin/bash
# .git/hooks/pre-install-skill

# 새 스킬을 설치하기 전에 SkillSpector 실행
skillspector scan "$1" --min-severity critical
if [ $? -ne 0 ]; then
  echo "오류: 스킬에 치명적 취약점이 포함되어 있습니다. 설치가 차단되었습니다."
  exit 1
fi

echo "스킬이 보안 스캔을 통과했습니다. 설치를 계속합니다."
exit 0

복구 지침 #

자동 수정 제안 #

SkillSpector는 감지된 각 취약점에 대해 구체적인 복구 단계를 제공합니다:

# 수정 제안 생성
skillspector scan ./skills/ --remediate --output-dir ./remediated/

# 복구 세부 정보 보기
skillspector remediation ./skills/suspicious.md

예시 복구 출력:

발견 항목: 셸 명령 내 명령 삽입
심각도: 치명적
위치: 45번째 줄: "Execute: rm -rf /tmp/* && curl..."

복구:
  1. 제한 없는 셸 명령 패턴 제거
  2. 구체적이고 제한된 명령으로 대체
  3. 사용자 제공 매개변수에 대한 입력 유효성 검사 추가
  
  수정 전: rm -rf /tmp/* && curl $EXTERNAL_URL
  수정 후: find /tmp -name "*.log" -mtime +7 -delete
           curl --max-time 30 --connect-timeout 10 "$SANITIZED_URL"

  4. 허용된 외부 도메인에 대한 허용 목록 추가
  5. 외부 요청에 대한 속도 제한 구현

스킬 작성자를 위한 보안 모범 사례 #

1. 셸 명령 범위 최소화: 스킬 목적에 필요한 명령만 포함
2. 모든 입력 검증: 사용자 입력을 셸 명령에 직접 전달하지 않음
3. 자격 증명 처리 피하기: 스킬 파일에 API 키, 비밀번호 또는 토큰 포함하지 않음
4. 파일 시스템 접근 제한: 파일 작업을 프로젝트 디렉토리만으로 제한
5. 데이터 흐름 문서화: 스킬이 어떤 데이터에 접근하고 어디로 보내는지 명확히 기술
6. 허용 목록 사용: 허용된 도메인, 파일 패턴 및 명령 매개변수 지정
7. 종속성 검토: 스킬이 필요로 하는 모든 외부 패키지 감사

비교: SkillSpector vs 전통적 보안 도구 #

한계 #

• 패턴 기반 감지: 일부 정교한 공격은 패턴 매칭을 우회할 수 있음
• 의미론적 이해: 스캐너는 스킬 텍스트를 분석하지만 LLM 행동 영향을 완전히 이해할 수 없음
• 프레임워크 진화: 새로운 에이전트 프레임워크에는 업데이트된 규칙 세트 필요
• 위양성: 정상적인 스킬이 수동 검토가 필요한 경고를 트리거할 수 있음
• 데이터베이스 최신성: 감지 효과성은 정기적인 데이터베이스 업데이트에 의존

시작 체크리스트 #

# 1. SkillSpector 설치
pip install skillspector

# 2. 취약점 데이터베이스 업데이트
skillspector update-db

# 3. 기존 스킬 스캔
skillspector scan ~/.claude/skills/ --framework claude-code

# 4. CI/CD 통합 설정
# 문서에서 GitHub Actions 워크플로우 추가

# 5. 설치 전 훅 구성
# 설치 전 훅을 git 훅 디렉토리에 복사

# 6. 정기 스캔 예약
crontab -e
# 추가: 0 */6 * * * skillspector scan ~/.claude/skills/ --output daily-report.json

결론 #

SkillSpector는 AI 에이전트 보안 영역에서 중요한 격차를 메웁니다. 에이전트 스킬이 AI 코딩 어시스턴트의 표준 확장 메커니즘이 되면서 전용 보안 스캔의 필요성이 매우 중요해지고 있습니다. SkillSpector는 자동화된 취약점 감지, 프레임워크별 분석, CI/CD 통합을 제공하여 개발자가 안전한 에이전트 생태계를 유지할 수 있도록 지원합니다.

NVIDIA에서 개발하고 사이버보안 연구 커뮤니티의 지원을 받는 SkillSpector는 부상하는 AI 에이전트 스킬 생태계를 위한 최초의 전용 보안 도구입니다. 오픈소스 특성은 투명성과 커뮤니티 주도 개선을 보장하며, 프로덕션에서 AI 에이전트 스킬을 배포하는 모든 사람에게 필수적인 도구입니다.

출처 #

• SkillSpector GitHub 저장소
• NVIDIA AI 보안 연구
• OWASP AI 보안 및 개인정보 보호 가이드
• 에이전트 보안 모범 사례

CTA #

오늘 바로 AI 에이전트 생태계를 보호하세요. SkillSpector GitHub 저장소를 방문하여 시작하세요. 보안 스캔 인프라 호스팅을 위해서는 저렴한 CI/CD 러너를 위한 HTStack이나 관리형 GitHub Actions 러너를 위한 DigitalOcean을 고려하세요.

대규모 기업용 보안 스캔이 필요하시면 ProxyShard가 에이전트 스킬 실행 환경을 격리하기 위한 보안 프록시 인프라를 제공합니다.

FAQ #

q: 취약점 데이터베이스는 얼마나 자주 업데이트해야 하나요? #

a: NVIDIA는 데이터베이스를 매주 업데이트할 것을 권장하며, 이상적으로는 각 스캔 전에 업데이트해야 합니다. SkillSpector에는 새 시그니처가 사용할 수 있을 때 사용자에게 알림을 제공하는 자동 업데이트 확인 기능이 포함되어 있습니다. CI/CD 파이프라인의 경우, 데이터베이스 업데이트를 스캔 단계의 일부로 구성하세요.

q: SkillSpector는 사용자 지정 또는 독점 에이전트 프레임워크와 작동하나요? #

a: SkillSpector의 스캔 엔진은 프레임워크 독립적입니다. Claude Code, Copilot, Codex CLI, Gemini CLI에 대해 사전 구성된 규칙을 포함하고 있지만, 지원되는 형식의 규칙 파일을 만들어 모든 에이전트 프레임워크에 대한 사용자 지정 규칙 세트를 정의할 수 있습니다.

q: SkillSpector가 에이전트 스킬 내 공급망 공격을 감지할 수 있나요? #

a: 네. SkillSpector는 스킬 종속성, 외부 패키지 참조 및 네트워크 통신 패턴을 분석하여 잠재적인 공급망 공격을 감지합니다. 검증되지 않은 패키지에 의존하거나 알려지지 않은 엔드포인트에 연결하는 스킬을 표시합니다.

q: 스킬 디렉토리의 예상 스캔 시간은 어떻게 되나요? #

a: 일반적으로 100개의 스킬 파일이 있는 디렉토리의 경우 SkillSpector는 10초 이내에 전체 스캔을 완료합니다. 큰 디렉토리(1000개 이상 파일)의 경우 30-60초가 소요될 수 있습니다. 스캔 시간은 파일 내용이 아닌 파일 수에 따라 선형적으로 증가합니다.

q: SkillSpector는 팀 협업 기능을 지원하나요? #

a: 현재 SkillSpector는 개인 스캔과 보고에 중점을 두고 있습니다. 공유 취약점 데이터베이스 및 협력적 복구의 팀 기능은 향후 릴리스에 계획되어 있습니다. JSON 보고서 형식은 팀 협업 플랫폼과의 쉬운 통합을 위해 설계되었습니다.

q: SkillSpector는 위양성을 어떻게 처리하나요? #

a: SkillSpector는 각 발견 항목에 대한 신뢰 점수를 할당하며 심각도 임계값으로 필터링할 수 있습니다. 구성에 제외 패턴을 추가하여 위양성을 억제할 수 있습니다. NVIDIA는 커뮤니티 피드백을 기반으로 감지 정확도를 지속적으로 검토하고 개선하고 있습니다.