
skill-scanner v2.0.13
에이전트 스킬용 보안 스캐너
Skill Scanner
AI Agent Skills를 위한 최선 노력(best-effort) 보안 스캐너로, 프롬프트 인젝션, 데이터 유출, 악성 코드 패턴을 탐지합니다. 패턴 기반 탐지(YAML + YARA-X), AST 및 데이터플로우 분석, 선택적 LLM-as-a-judge, 그리고 타입이 지정된 탐지기 사실(fact)에 대한 제한된 CEL 의사결정 계층을 결합합니다.
중요: 이 스캐너는 최선 노력 탐지를 제공하며, 포괄적이거나 완전한 커버리지를 제공하지 않습니다. 발견 사항이 없는 스캔 결과가 해당 스킬에 모든 위협이 없음을 보장하지는 않습니다. 아래의 범위 및 한계를 참조하세요.
Agent Skills 명세를 따르는 OpenAI Codex Skills 및 Cursor Agent Skills 형식을 지원합니다. --lenient 사용 시 Claude Code .claude/commands/*.md 및 플랫 마크다운 스킬 저장소와 같은 비표준 형식도 스캔합니다.
주요 기능
- 멀티 엔진 탐지 - 정적 분석, 행위 데이터플로우, LLM 의미 분석, 클라우드 기반 스캐닝을 통한 계층적 최선 노력 커버리지
- 타입 지정 CEL 의사결정 - 핵심 스캐너는 공식
cel-gov0.32.0 런타임을 사용하여 결정론적 탐지 이후, 선택적 LLM 분석 이전에 제한된 사실(fact)들을 상호 연관시킵니다 - 측정된 프리셋 -
low-noise및quiet프리셋과 LLM 상한을 제공하며, 각각에 대해 재현율, 오탐률, F1이 공개됩니다 (권장 설정) - CI/CD 지원 - GitHub Code Scanning용 SARIF 출력, 재사용 가능한 GitHub Actions 워크플로, 빌드 실패를 위한 종료 코드
- Pre-commit 훅 - 표준 pre-commit 프레임워크 통합으로 매 커밋 전 스킬 스캔
- 확장 가능 - 사용자 정의 분석기를 위한 플러그인 아키텍처
Cisco AI Discord에 참여하세요 - 토론, 피드백 공유, 팀과의 소통을 위해.
범위 및 한계
Skill Scanner는 탐지 도구입니다. 알려진 그리고 개연성 있는 위험 패턴을 식별하지만, 보안을 인증하지는 않습니다.
주요 한계:
- 탐지 결과 없음 ≠ 위험 없음. "탐지 결과 없음"을 반환하는 스캔은 알려진 위협 패턴이 감지되지 않았음을 의미합니다. 이는 해당 스킬이 안전하거나, 무해하거나, 취약점이 없음을 보장하지 않습니다.
- 탐지 범위는 본질적으로 불완전합니다. 스캐너는 시그니처 기반 탐지, LLM 기반 의미 분석, 동작 데이터 흐름 분석, 선택적 클라우드 서비스, 그리고 구성 가능한 규칙 팩을 결합합니다. 이 접근 방식은 탐지 범위를 향상시키지만, 어떤 자동화 도구도 모든 기법, 특히 신종 또는 제로데이 공격을 탐지할 수는 없습니다.
- 오탐과 미탐이 발생할 수 있습니다. 프리셋, LLM 판정기, 범위 지정 억제 기능은 노이즈를 줄이지만, 어떤 구성도 모든 잘못된 분류를 제거하지는 못합니다. 권장 설정에서 적절한 구성을 선택하고, 위험 허용 범위에 맞게 스캔 정책을 조정하십시오.
- 인간의 검토는 여전히 필수적입니다. 자동화된 스캔은 심층 방어 전략의 한 구성 요소일 뿐입니다. 고위험 또는 프로덕션 배포에서는 스캐너 결과를 수동 코드 검토 및/또는 위협 모델링과 함께 활용해야 합니다.
측정된 결과
홀드아웃 스킬(MaliciousSkillBench의 동결된 테스트 분할, 악성 839개 및 무해 545개)에서:
- 규칙만 사용할 경우 HIGH 등급에서 악성 스킬의 7.7%를 탐지하며, 오탐률은 4.0%입니다.
- LLM 판정기 사용 시(Gemma 4 26B,
balanced), 66.7%가 MEDIUM+ 등급에서 검토 대상에 도달하며(오탐률 15.4%), 33.7%가 HIGH 등급에서 차단됩니다(오탐률 6.4%).
모든 수치는 해당 코퍼스 및 방법론과 함께 측정된 결과와 평가 Space에 있습니다.
문서
문서 웹사이트는 **cisco-ai-defense.github.io/docs/skill-scanner**입니다.
심층 분석 페이지는 docs/에 있습니다.
| 가이드 | 설명 |
|---|---|
| 빠른 시작 | 5분 만에 시작하기 |
| 권장 설정 | 가장 낮은 FPR 또는 가장 높은 F1을 위한 설정을 선택하고, 복사-붙여넣기 가능한 구성을 제공합니다 |
| LLM 제공자 | 모든 제공자, 게이트웨이 또는 로컬 모델에 대해 LLM 판정기를 구성합니다 |
| 결과 및 튜닝 | 발견 사항을 읽고, 검토 큐를 만들고, 오탐을 줄입니다 |
| 아키텍처 | 시스템 설계 및 구성 요소 |
| CEL 결정 계층 | 타입이 지정된 팩트, 안전 경계, 롤아웃 모드 및 텔레메트리 |
| 위협 분류 체계 | 예시와 함께 제공되는 전체 AITech 위협 분류 체계 |
| 분류 체계 참조 | 모든 AITech 및 AISubtech 코드의 정의 |
| LLM 분석기 | LLM 구성 및 사용법 |
| System One 분석기 | 선택적 권고 스크리닝 계층과 이것이 게이트 역할을 할 수 없는 이유 |
| 메타 분석기 | 선택적 2차 검토 (기본적으로 꺼져 있음; 측정된 비용) |
| 행동 분석기 | 데이터 흐름 분석 세부 사항 |
| 스캔 정책 | 사용자 지정 정책, 프리셋 및 튜닝 가이드 |
| 정책 빠른 참조 | 정책 섹션 및 설정 항목에 대한 간결한 참조 |
| 측정된 결과 | 모든 공개 수치와 해당 코퍼스, 모집단 및 모델 |
| 규칙 작성 | 시그니처, YARA 및 Python 규칙을 추가하는 방법 |
| GitHub Actions | CI/CD 통합을 위한 재사용 가능한 워크플로 |
| API 참조 | REST API 문서 |
| 개발 가이드 | 기여 및 개발 환경 설정 |
설치
필수 조건: CPython 3.11–3.14 및 uv (권장) 또는 pip.
휠에는 glibc Linux x86-64/ARM64, macOS 14+ x86-64/ARM64 및 Windows x86-64용 CEL 헬퍼가 포함되어 있습니다. 다른 플랫폼은 Go 1.27.1+가 필요한 소스 배포판에서 빌드합니다. 자세한 내용은 설치 및 구성을 참조하세요.
# Using uv (recommended)
uv pip install cisco-ai-skill-scanner
# As a standalone tool
uv tool install cisco-ai-skill-scanner # or: pipx install cisco-ai-skill-scanner
# Using pip
pip install cisco-ai-skill-scanner
# Using Homebrew (macOS 14+)
brew tap cisco-ai-defense/skill-scanner https://github.com/cisco-ai-defense/skill-scanner
brew install cisco-ai-defense/skill-scanner/skill-scanner
권장 설정의 프리셋과 설정은 2.2.0 이상이 필요합니다(skill-scanner --version).
클라우드 공급자 추가 기능
# AWS Bedrock support (IAM credentials, no API key)
pip install cisco-ai-skill-scanner[bedrock]
# Google AI Studio / Gemini support
pip install cisco-ai-skill-scanner[google]