YaraFlux MCP 서버
YARA 스캐닝을 위한 MCP(모델 컨텍스트 프로토콜) 서버로, LLM에 YARA 규칙이 적용된 파일을 분석하는 기능을 제공합니다.
📋 개요
YaraFlux MCP 서버는 AI 지원팀이 표준화된 모델 컨텍스트 프로토콜(Model Context Protocol) 인터페이스를 통해 YARA 규칙 기반 위협 분석을 수행할 수 있도록 지원합니다. 이 서버는 YARA 스캐닝을 최신 AI 지원팀과 통합하여 모듈형 아키텍처를 통해 포괄적인 규칙 관리, 안전한 스캐닝 및 상세 결과 분석을 지원합니다.
🧩 아키텍처 개요
지엑스피1
YaraFlux는 다음과 같은 문제를 분리하는 모듈형 아키텍처를 따릅니다.
- MCP 통합 계층 : AI 어시스턴트와의 통신을 처리합니다.
- 도구 구현 계층 : YARA 스캐닝 및 관리 기능을 구현합니다.
- 저장 추상화 계층 : 유연한 저장 옵션 제공
- YARA 엔진 통합 : 스캐닝 및 규칙 관리를 위해 YARA 활용
자세한 아키텍처 다이어그램은 아키텍처 문서를 참조하세요.
✨ 특징
- 🔄 모듈형 아키텍처
- MCP 통합, 도구 구현 및 스토리지의 명확한 분리
- 표준화된 매개변수 구문 분석 및 오류 처리
- 로컬 및 S3/MinIO 옵션을 갖춘 유연한 스토리지 백엔드
- 🤖 MCP 통합
- 포괄적인 기능을 위한 19개의 통합 MCP 도구
- Claude Desktop 통합에 최적화됨
- 대화 내에서 직접 파일 분석
- 최신 MCP 프로토콜 사양과 호환
- 🔍 야라 스캐닝
- URL 및 파일 콘텐츠 스캐닝
- 컨텍스트를 포함한 자세한 경기 정보
- 스캔 결과 저장 및 검색
- 성능 최적화된 스캐닝 엔진
- 📝 규칙 관리
- YARA 규칙 생성, 읽기, 업데이트, 삭제
- 자세한 오류 보고를 통한 규칙 검증
- ThreatFlux 저장소에서 규칙 가져오기
- 출처별 분류(사용자 정의 대 커뮤니티)
- 📊 파일 분석
- 이진 분석을 위한 16진수 뷰
- 구성 가능한 매개변수를 사용한 문자열 추출
- 파일 메타데이터 및 해시 정보
- 안전한 파일 업로드 및 저장
- 🔐 보안 기능
- API 액세스를 위한 JWT 인증
- 루트가 아닌 컨테이너 실행
- 안전한 스토리지 격리
- 구성 가능한 액세스 제어
🚀 빠른 시작
Docker 이미지 사용
# Pull the latest Docker image
docker pull threatflux/yaraflux-mcp-server:latest
# Run the container
docker run -p 8000:8000 \
-e JWT_SECRET_KEY=your-secret-key \
-e ADMIN_PASSWORD=your-admin-password \
-e DEBUG=true \
threatflux/yaraflux-mcp-server:latest
### Using Docker building from source
```bash
# Clone the repository
git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/
# Build the Docker image
docker build -t yaraflux-mcp-server:latest .
# Run the container
docker run -p 8000:8000 \
-e JWT_SECRET_KEY=your-secret-key \
-e ADMIN_PASSWORD=your-admin-password \
-e DEBUG=true \
yaraflux-mcp-server:latest
소스에서 설치
# Clone the repository
git clone https://github.com/ThreatFlux/YaraFlux.git
cd YaraFlux/
# Install dependencies (requires Python 3.13+)
make install
# Run the server
make run
🧩 Claude 데스크톱 통합
YaraFlux는 Model Context Protocol을 통해 Claude Desktop과 원활하게 통합되도록 설계되었습니다.
- Docker 이미지를 빌드합니다.
docker build -t yaraflux-mcp-server:latest .
- Claude Desktop 구성에 추가(
~/Library/Application Support/Claude/claude_desktop_config.json ):
{
"mcpServers": {
"yaraflux-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--env",
"JWT_SECRET_KEY=your-secret-key",
"--env",
"ADMIN_PASSWORD=your-admin-password",
"--env",
"DEBUG=true",
"--env",
"PYTHONUNBUFFERED=1",
"threatflux/yaraflux-mcp-server:latest"
],
"disabled": false,
"autoApprove": [
"scan_url",
"scan_data",
"list_yara_rules",
"get_yara_rule"
]
}
}
}
- 서버를 활성화하려면 Claude Desktop을 다시 시작하세요.
🛠️ 사용 가능한 MCP 도구
YaraFlux는 19개의 통합 MCP 도구를 제공합니다.
규칙 관리 도구
- list_yara_rules : 필터링 옵션을 사용하여 사용 가능한 YARA 규칙을 나열합니다.
- get_yara_rule : 특정 YARA 규칙의 콘텐츠 및 메타데이터를 가져옵니다.
- validate_yara_rule : 자세한 오류 보고를 통해 YARA 규칙 구문을 검증합니다.
- add_yara_rule : 새로운 YARA 규칙을 만듭니다.
- update_yara_rule : 기존 YARA 규칙을 업데이트합니다.
- delete_yara_rule : YARA 규칙 삭제
- import_threatflux_rules : ThreatFlux GitHub 저장소에서 규칙 가져오기
스캐닝 도구
- scan_url : 지정된 YARA 규칙을 사용하여 URL에서 콘텐츠를 스캔합니다.
- scan_data : 지정된 규칙에 따라 제공된 데이터(base64 인코딩)를 스캔합니다.
- get_scan_result : 이전 스캔의 자세한 결과를 검색합니다.
파일 관리 도구
- upload_file : 분석이나 스캐닝을 위해 파일을 업로드합니다.
- get_file_info : 업로드된 파일에 대한 메타데이터를 가져옵니다.
- list_files : 페이지 매김 및 정렬을 통해 업로드된 파일을 나열합니다.
- delete_file : 업로드된 파일을 삭제합니다
- extract_strings : 파일에서 ASCII/Unicode 문자열을 추출합니다.
- get_hex_view : 파일 내용의 16진수 보기를 가져옵니다.
- download_file : 업로드된 파일을 다운로드합니다
스토리지 관리 도구
- get_storage_info : 스토리지 사용 통계 가져오기
- clean_storage : 오래된 파일을 제거하여 저장 공간을 확보합니다.
📚 문서
자세한 내용은 docs/ 디렉토리에서 확인할 수 있습니다.
🗂️ 프로젝트 구조
yaraflux_mcp_server/
├── src/
│ └── yaraflux_mcp_server/
│ ├── app.py # FastAPI application
│ ├── auth.py # JWT authentication and user management
│ ├── config.py # Configuration settings loader
│ ├── models.py # Pydantic models for requests/responses
│ ├── mcp_server.py # MCP server implementation
│ ├── utils/ # Utility functions package
│ │ ├── __init__.py # Package initialization
│ │ ├── error_handling.py # Standardized error handling
│ │ ├── param_parsing.py # Parameter parsing utilities
│ │ └── wrapper_generator.py # Tool wrapper generation
│ ├── mcp_tools/ # Modular MCP tools package
│ │ ├── __init__.py # Package initialization
│ │ ├── base.py # Base tool registration utilities
│ │ ├── file_tools.py # File management tools
│ │ ├── rule_tools.py # YARA rule management tools
│ │ ├── scan_tools.py # Scanning tools
│ │ └── storage_tools.py # Storage management tools
│ ├── storage/ # Storage implementation package
│ │ ├── __init__.py # Package initialization
│ │ ├── base.py # Base storage interface
│ │ ├── factory.py # Storage client factory
│ │ ├── local.py # Local filesystem storage
│ │ └── minio.py # MinIO/S3 storage
│ ├── routers/ # API route definitions
│ │ ├── __init__.py # Package initialization
│ │ ├── auth.py # Authentication API routes
│ │ ├── files.py # File management API routes
│ │ ├── rules.py # YARA rule management API routes
│ │ └── scan.py # YARA scanning API routes
│ ├── yara_service.py # YARA rule management and scanning
│ ├── __init__.py # Package initialization
│ └── __main__.py # CLI entry point
├── docs/ # Documentation
├── tests/ # Test suite
├── Dockerfile # Docker configuration
├── entrypoint.sh # Container entrypoint script
├── Makefile # Build automation
├── pyproject.toml # Project metadata and dependencies
├── requirements.txt # Core dependencies
└── requirements-dev.txt # Development dependencies
🧪 개발
지역 개발
# Set up development environment
make dev-setup
# Run tests
make test
# Code quality checks
make lint
make format
make security-check
# Generate test coverage report
make coverage
# Run development server
make run
CI/CD 워크플로
이 프로젝트에서는 지속적인 통합 및 배포를 위해 GitHub Actions를 사용합니다.
- CI 테스트 : 메인 및 개발 브랜치에 대한 모든 푸시 및 풀 요청에서 실행됩니다.
- 테스트, 포맷팅, 린팅 및 유형 검사를 실행합니다.
- Docker 이미지를 빌드하고 테스트합니다.
- Codecov에 테스트 적용 범위 보고서 업로드
- 버전 자동 증가 : 메인 브랜치에 푸시할 때 버전이 자동으로 증가합니다.
- pyproject.toml, setup.py 및 Dockerfile의 버전을 업데이트합니다.
- 새 버전에 대한 git 태그를 생성합니다.
- 릴리스 게시 : 버전 자동 증가 성공 후 트리거됨
- 여러 단계에 대한 Docker 이미지를 빌드합니다.
- git 커밋에서 릴리스 노트를 생성합니다.
- 아티팩트를 사용하여 GitHub 릴리스를 생성합니다.
- Docker Hub에 Docker 이미지를 게시합니다.
이러한 워크플로는 코드 품질을 보장하고 릴리스 프로세스를 자동화합니다.
상태 확인
다음 상태 확인은 풀 리퀘스트에서 실행됩니다.
- ✅ 형식 검증 : 코드가 Black 및 isort 형식 표준을 따르는지 확인합니다.
- ✅ Lint 검증 : 코드 품질과 코딩 표준 준수 여부를 검증합니다.
- ✅ 테스트 실행 : 기능을 검증하기 위해 전체 테스트 모음을 실행합니다.
- ✅ 커버리지 보고서 : 코드베이스의 충분한 테스트 커버리지를 보장합니다.
🌐 API 문서
대화형 API 문서는 다음에서 확인할 수 있습니다.
자세한 API 문서는 API 참조를 확인하세요.
🤝 기여하기
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
- 저장소를 포크하세요
- 기능 브랜치를 생성합니다(
git checkout -b feature/amazing-feature ) - 변경 사항을 커밋하세요(
git commit -m 'Add some amazing feature' ) - 브랜치에 푸시(
git push origin feature/amazing-feature ) - 풀 리퀘스트 열기
📄 라이센스
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
💖 기부 또는 기능 요청