Skip to content
KitploitKITPLOIT
도구블로그
제출
도구블로그
제출

해킹, 침투 테스트 및 사이버 보안 도구를 당신의 보안 무기고에!

Kitploit은 해킹, 사이버 보안 및 침투 테스트 도구 디렉토리입니다. 최신 프로젝트 업데이트를 발견하여 취약점을 찾고, 시스템을 분석하고, 테스트를 자동화하고, 보안을 강화하세요.

··피드·문의·개인정보·© 2026 Kitploit

도구 디렉토리

카테고리

모든 카테고리 보기
Loading categories
Hybrid Submit — Hybrid Analysis(API)에 파일을 자동으로 제출하는 스크립트 | Kitploit
도구/GitLabGitLab/kaysec/hybrid-submit
Scripting & AutomationMalware AnalysisAPI Security
GitLabkaysec/hybrid-submit

Hybrid Submit

Hybrid Analysis(API)에 파일을 자동으로 제출하는 스크립트

저장소 보기
53개월 전아직 검토되지 않음

인기

모두 보기 →

커뮤니티에서 가장 많이 사용되는 도구를 찾아보세요.

모든 도구 탐색

도구 컬렉션을 둘러보세요

모든 도구 보기 →
공유

Hybrid Analysis 배치 제출 스크립트

이 Python 스크립트는 폴더를 재귀적으로 스캔하여 실행 파일, 스크립트, 문서 및 기타 관련 파일을 Hybrid Analysis (Falcon Sandbox)에 제출하여 자동화된 악성코드 분석을 수행합니다.

특징

  • 디렉터리를 재귀적으로 탐색
  • 지원되는 파일 형식만 제출 (아래 목록 참조)
  • 비어 있거나, 너무 크거나, 이전에 제출된 파일은 건너뜀
  • 경로 순회 공격 방지 – 파일이 스캔 루트 내에 있는지 확인
  • 심볼릭 링크 건너뛰기 – 중복되거나 의도하지 않은 제출 방지
  • 지속적인 requests 세션을 사용하여 효율적인 API 통신
  • 캐시를 전용 사용자 디렉터리 (~/.hybrid_analysis_submitter/)에 저장하여 스캔 대상 폴더 오염 방지
  • 로컬 SHA‑256 캐시를 사용하여 중복 제출 방지
  • API 속도 제한 (429 오류)을 우아하게 처리
  • API 할당량이 소진되면 자동 중지
  • 명령줄에서 폴더, 파일 크기 제한, 환경 ID, 캐시 파일 이름 구성 지원
  • 보안을 위해 .env 파일에서 API 키 읽기

요구 사항

  • Python 3.6+
  • 유효한 Hybrid Analysis API 키 (무료 티어 사용 가능)

설치

  1. 스크립트를 복제 또는 다운로드하여 로컬 시스템에 저장합니다.

  2. 필요한 패키지 설치:

root@kitploit:~
pip install requests python-dotenv
  1. .env 파일 생성 (스크립트와 동일한 디렉터리에 API 키 입력):
root@kitploit:~
HYBRID_API_KEY=your_api_key_here

API 키는 Hybrid Analysis에 등록하여 얻을 수 있습니다.

사용법

명령줄에서 스크립트를 실행하고 스캔할 폴더를 지정합니다:

root@kitploit:~
python submit_to_hybrid.py /path/to/folder

명령줄 인자

인자설명
folder_path필수 – 스캔할 폴더 경로 (재귀적)
--max-file-size최대 파일 크기 (MB 단위, 기본값: 250)
--environment-id분석 환경 ID (기본값: 120 = Windows 7 64비트)
--cache-file캐시 파일 이름 (기본값: submitted_cache.json). 파일은 ~/.hybrid_analysis_submitter/에 저장됨

예시

기본 설정으로 폴더 스캔:

root@kitploit:~
python submit_to_hybrid.py C:\suspicious_files

폴더를 스캔하되 크기 제한을 200MB로 늘리고 다른 환경(예: Android) 사용:

root@kitploit:~
python submit_to_hybrid.py /home/user/samples --max-file-size 200 --environment-id 300

사용자 지정 캐시 파일 이름 사용:

root@kitploit:~
python submit_to_hybrid.py ./malware --cache-file my_cache.json

출력 예시

root@kitploit:~
Scanning folder: C:\suspicious_files

Submitting: C:\suspicious_files\malware.exe (2.34 MB)
 -> Success! Job ID: 5f8a9c2d3e4f5a6b7c8d9e0f
Submitting: C:\suspicious_files\document.pdf (0.12 MB)
 -> Success! Job ID: 6g9b0c1d2e3f4a5b6c7d8e9f
Skipping already submitted: C:\suspicious_files\malware.exe
Skipping symlink: C:\suspicious_files\link_to_malware.exe

Finished.
Files found:      42
Files submitted:  35
Files skipped:    6
Files failed:     1

지원되는 파일 형식

  • Windows 실행 파일 (PE): .exe, .scr, .pif, .dll, .com, .cpl
  • 설치 프로그램 및 패키지: .msi
  • Windows 스크립트: .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, .wsf, .hta, .sct
  • 기타 Windows 파일: .lnk, .chm
  • Office 문서: .doc, .docx, .ppt, .pps, .pptx, .ppsx, .xls, .xlsx, .rtf, .pub
  • 기타 문서: .pdf, .eml, .msg
  • 크로스 플랫폼 실행 파일/스크립트: .jar, .py, .pl
  • 모바일/임베디드: .apk (Android), .elf (Linux)
  • 웹/그래픽: .svg

지원되는 모든 파일 형식의 공식 목록은 Hybrid Analysis FAQ를 확인하세요.

작동 방식

  1. 재귀적 탐색 – 스크립트는 os.walk()를 사용하여 모든 하위 폴더를 탐색합니다.
  2. 보안 검사 – 각 파일이 스캔 루트 내의 경로로 해석되는지 확인하고(경로 순회 방지) 심볼릭 링크를 건너뜁니다.
  3. 파일 필터링 – 파일 확장자, 크기(0바이트 또는 --max-file-size 초과 시 건너뜀), 이전 제출 여부(SHA‑256 캐시)를 확인합니다.
  4. 제출 – 각 파일은 https://hybrid-analysis.com/api/v2/submit/file 엔드포인트로 API 키와 함께 지속적인 requests 세션을 통해 업로드됩니다.
  5. 속도 제한 – 각 제출 후 스크립트는 2초 동안 대기합니다. HTTP 429(Too Many Requests) 응답을 받으면 오류를 카운트합니다. 3회 연속 429 오류 발생 시 스캔이 자동으로 중지됩니다.
  6. 캐시 지속성 – 성공적으로 제출된 파일은 ~/.hybrid_analysis_submitter/ 내의 JSON 캐시 파일에 저장되어 이후 실행 시 재제출되지 않습니다. 캐시는 가독성을 위해 정렬되어 저장됩니다.

속도 제한 및 할당량

  • Hybrid Analysis 무료 계정은 시간당/일일 제출 한도가 있습니다.
  • 스크립트는 HTTP 429 응답을 감지하고 3회 오류 발생 후 중지하여 무한 재시도를 방지합니다.
  • API에 부담을 주지 않기 위해 제출 간 2초 지연이 추가됩니다.

중요 참고 사항

  • API 키는 오직 .env 파일에서 읽어옵니다 – 하드코딩하지 마세요.
  • 빈 파일(0바이트)은 항상 건너뜁니다.
  • --max-file-size보다 큰 파일은 건너뜁니다.
  • ALLOWED_EXTENSIONS에 포함된 확장자를 가진 파일만 제출됩니다.
  • 심볼릭 링크는 건너뛰어 중복 제출 및 경로 혼동을 방지합니다.
  • 경로 순회가 방지됩니다 – 스크립트는 지정된 스캔 디렉터리 외부로 해석되는 파일을 건너뜁니다.
  • 캐시는 여러 실행 간 동일한 파일의 재제출을 방지하며 사용자 디렉터리(~/.hybrid_analysis_submitter/)에 저장됩니다.
  • 스크립트는 각 HTTP 요청에 대해 120초 타임아웃을 사용합니다.
  • 캐시 파일은 전용 디렉터리에 저장되며 스캔 대상 콘텐츠와 혼합되지 않습니다.

문제 해결

문제가능한 해결 방법
ERROR: HYBRID_API_KEY not found스크립트와 동일한 디렉터리에 HYBRID_API_KEY=your_key_here가 포함된 .env 파일을 생성하세요.
'folder_path' is not a valid directory존재하는 폴더의 올바른 경로를 제공하세요.
파일 읽기 권한 거부적절한 읽기 권한으로 스크립트를 실행하세요.
빈번한 429 오류제출 속도를 줄이거나(스크립트에서 time.sleep(2) 증가) API 요금제를 업그레이드하세요.
예상치 못한 파일 건너뜀확장자가 ALLOWED_EXTENSIONS에 포함되어 있는지 확인하세요. 스크립트를 편집하여 확장자를 추가할 수 있습니다.
중복 제출 건너뛰지 않음캐시 파일이 없거나 손상되었을 수 있습니다. ~/.hybrid_analysis_submitter/submitted_cache.json을 삭제하여 새로 시작하거나 --cache-file 인자를 사용하여 다른 캐시 파일 이름을 사용하세요.
스캔 루트 외부의 파일 건너뜀이는 보안을 위한 의도된 동작입니다. 모든 대상 파일이 지정된 폴더 내에 있는지 확인하세요.

라이선스

이 스크립트는 교육 및 보안 분석 목적으로 있는 그대로 제공됩니다. 책임감 있게 사용하고 Hybrid Analysis 서비스 약관을 준수하세요.

면책 조항

파일을 타사 샌드박스에 제출하면 잠재적으로 민감한 콘텐츠가 노출될 수 있습니다. 업로드하기 전에 파일을 공유할 권한이 있는지 확인하세요.

도구 다운로드