Skill Scanner

AI Agent Skills를 위한 최선 노력(best-effort) 보안 스캐너로, 프롬프트 인젝션, 데이터 유출, 악성 코드 패턴을 탐지합니다. 패턴 기반 탐지(YAML + YARA-X), AST 및 데이터플로우 분석, 선택적 LLM-as-a-judge, 그리고 타입이 지정된 탐지기 팩트에 대한 제한된 CEL 결정 계층을 결합합니다.

중요: 이 스캐너는 최선 노력 탐지를 제공하며, 포괄적이거나 완전한 커버리지를 보장하지 않습니다. 결과가 없는 스캔이 해당 스킬에 모든 위협이 없다는 것을 보장하지 않습니다. 아래 범위 및 한계를 참조하세요.

Agent Skills 명세를 따르는 OpenAI Codex Skills 및 Cursor Agent Skills 형식을 지원합니다. --lenient를 사용하면 Claude Code .claude/commands/*.md 및 플랫 마크다운 스킬 저장소와 같은 비표준 형식도 스캔합니다.

주요 기능

다중 엔진 탐지 - 정적 분석, 행위 데이터플로우, LLM 시맨틱 분석, 클라우드 기반 스캐닝을 통한 계층적 최선 노력 커버리지
타입 지정 CEL 결정 - 핵심 스캐너는 공식 cel-go v0.32.0 런타임을 사용하여 결정적 탐지 이후, 선택적 LLM 분석 이전에 제한된 팩트를 상호 연관시킵니다
탐지 결과 검토 - 선택적 메타 분석기가 탐지 결과를 상호 연관시키고, 우선순위를 지정하며, 필터링할 수 있습니다. 짝을 이룬 정확도 검증은 아직 대기 중입니다
CI/CD 지원 - GitHub Code Scanning용 SARIF 출력, 재사용 가능한 GitHub Actions 워크플로, 빌드 실패를 위한 종료 코드
Pre-commit 훅 - 표준 pre-commit 프레임워크 통합으로 모든 커밋 전에 스킬을 스캔
확장 가능 - 사용자 정의 분석기를 위한 플러그인 아키텍처

Cisco AI Discord에 참여하세요 - 논의, 피드백 공유, 팀과의 연결을 위해.

범위 및 한계

Skill Scanner는 탐지 도구입니다. 알려진 그리고 개연성 있는 위험 패턴을 식별하지만, 보안을 인증하지는 않습니다.

주요 한계:

탐지 결과 없음 ≠ 위험 없음. "탐지 결과 없음"을 반환하는 스캔은 알려진 위협 패턴이 탐지되지 않았음을 나타냅니다. 이는 해당 스킬이 안전하거나, 무해하거나, 취약점이 없다는 것을 보장하지 않습니다.
커버리지는 본질적으로 불완전합니다. 스캐너는 시그니처 기반 탐지, LLM 기반 시맨틱 분석, 행위 데이터플로우 분석, 선택적 클라우드 서비스, 구성 가능한 규칙 팩을 결합합니다. 이 접근 방식이 커버리지를 향상시키지만, 어떤 자동화 도구도 모든 기법, 특히 신종 또는 제로데이 공격을 탐지할 수는 없습니다.
오탐과 미탐이 발생할 수 있습니다. 합의 모드와 메타 분석이 탐지 결과 검토에 도움이 될 수 있지만, 어떤 구성도 모든 잘못된 분류를 제거하지는 못합니다. 위험 허용 범위에 맞게 스캔 정책을 조정하세요.
인간의 검토는 여전히 필수적입니다. 자동화된 스캐닝은 심층 방어 전략의 한 구성 요소입니다. 고위험이나 프로덕션 배포에서는 스캐너 결과를 수동 코드 검토 및/또는 위협 모델링과 함께 사용해야 합니다.

현재 현대화 증거

최종 core + CEL 개발 벤치마크는 5,256개의 악성 및 1,338개의 양성 MaliciousSkillBench 패키지를 포함합니다. origin/main과 비교하여 현재 스캐너는 F1을 32.92%에서 47.73%로, 재현율을 19.88%에서 31.43%로 높였으며, 양성 오탐률을 3.59%에서 1.05%로 감소시켰습니다. 정밀도는 99.16%입니다. 5회의 CEL-shadow 실행은 정확하고 결정적이었으며, CEL은 154개의 후보를 평가했고 억제를 제안하거나 폴백하지 않았습니다.

잠긴 소스 분리(source-disjoint) 분할은 더 약합니다: TP=65, FP=42, TN=503, FN=774로 정밀도 60.75%, 재현율 7.75%, F1 13.74%, FPR 7.71%입니다. 이는 origin/main (7.40%)보다 F1을 개선하지만 FPR(3.67%)은 악화시키므로, 승격 게이트를 통과하지 못합니다. 따라서 번들된 모든 CEL 규칙은 shadow에 남아 있으며, 이 변경은 어떤 CEL 억제도 승격하지 않습니다.

호환성 및 보충 검사는 111개의 공식 Codex, Claude Code, Cursor 스킬(30개의 MEDIUM+ 및 8개의 HIGH/CRITICAL 패키지)에서 5회의 안정적인 실행으로 동일한 CEL-OFF/CEL-SHADOW 탐지 결과를 확인했습니다. NotInject 하드 네거티브 세트는 0/339의 실행 가능한 매치를 보였습니다. HarmfulSkillBench는 1개의 격리된 샘플과 함께 7/200의 실행 가능 및 6/200의 HIGH+ 패키지를 보였고, OpenSkillRisk는 2개의 호스트 격리와 함께 76/263의 실행 가능 패키지를 보였습니다. 후자의 두 가지는 양성 전용 재현율 진단이며 정밀도나 FPR을 측정할 수 없습니다. 선택적 ATR 결과는 이 릴리스 범위 밖입니다. 방법론, 출처, 신뢰 구간, 한계에 대해서는 탐지 평가 및 롤아웃을 참조하세요.

문서

가이드	설명
빠른 시작	5분 안에 시작하기
권장 설정	어떤 작업에 무엇을 실행할지, 그 이유, 구성 방법
아키텍처	시스템 설계 및 구성 요소
CEL 결정 계층	타입 지정 팩트, 안전 경계, 롤아웃 모드, 텔레메트리
위협 분류 체계	예시가 포함된 완전한 AITech 위협 분류 체계
LLM 분석기	LLM 구성 및 사용법
System One 분석기	선택적 자문 스크리닝 계층, 그리고 게이트로 사용할 수 없는 이유
메타 분석기	오탐 필터링 및 우선순위 지정
행위 분석기	데이터플로우 분석 세부 사항
스캔 정책	사용자 정의 정책, 프리셋, 튜닝 가이드
정책 빠른 참조	정책 섹션 및 설정에 대한 간결한 참조
측정 결과	코퍼스, 모집단, 모델과 함께 모든 공개된 수치
규칙 작성	시그니처, YARA, Python 규칙을 추가하는 방법
GitHub Actions	CI/CD 통합을 위한 재사용 가능한 워크플로
API 참조	REST API 문서
개발 가이드	기여 및 개발 설정

설치

이 체크아웃 및 이러한 변경 사항을 포함하는 릴리스의 전제 조건: CPython 3.11–3.14 및 uv(권장) 또는 pip

이 브랜치의 CEL 변경 사항을 포함하는 릴리스는 필요한 헬퍼를 휠에 포함합니다. 별도의 CEL extra는 없습니다. 해당 릴리스는 CPython 3.11–3.14용으로 구성되어 있으며, 소스 설치의 경우 추가로 헬퍼를 빌드하기 위해 Go 1.27.1+가 필요합니다. 게시되기 전까지는 현재 PyPI에서 제공되는 패키지가 다른 호환성 계약을 가질 수 있습니다. 자세한 내용은 설치 및 구성을 참조하세요.```bash

Using uv (recommended)

uv pip install cisco-ai-skill-scanner

Using pip

pip install cisco-ai-skill-scanner

<details>
<summary><strong>클라우드 제공자 추가 기능</strong></summary>```bash
# AWS Bedrock support
pip install cisco-ai-skill-scanner[bedrock]

# Google AI Studio / Gemini support
pip install cisco-ai-skill-scanner[google]

# Google Vertex AI support
pip install cisco-ai-skill-scanner[vertex]

# Azure OpenAI support
pip install cisco-ai-skill-scanner[azure]

# All cloud providers
pip install cisco-ai-skill-scanner[all]

빠른 시작

환경 설정 (선택 사항)```bash

For LLM analyzer and Meta-analyzer

export SKILL_SCANNER_LLM_API_KEY="your_api_key" export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"

Optional: disabled, minimal, low, medium, high, xhigh, or max

export SKILL_SCANNER_LLM_REASONING_EFFORT="low"

For VirusTotal binary scanning

export VIRUSTOTAL_API_KEY="your_virustotal_api_key"

skill-scanner v2.0.13