Seongmin1223/Malscan
GitHub: Seongmin1223/Malscan
Stars: 0 | Forks: 0
# MalScan
정적 악성코드 분석 자동화 도구
의심 파일 하나를 넣으면 해시 계산, VirusTotal 조회, PE 구조 분석, 문자열 추출, YARA 룰 매칭을 자동으로 수행하고 HTML 보고서를 생성합니다.
## 스크린샷
## 주요 기능
| 기능 | 설명 |
|------|------|
| 해시 계산 | MD5 / SHA1 / SHA256 자동 계산 |
| VirusTotal 조회 | API로 75개 이상 백신 엔진 탐지 결과 조회 |
| PE 구조 분석 | 헤더, 섹션, Import Table, 엔트로피 분석 |
| 문자열 추출 | URL, IP, 이메일, 레지스트리 경로, 의심 명령어 추출 |
| YARA 룰 매칭 | 공개 룰셋 기반 악성코드 패턴 탐지 |
| 위험도 자동 판정 | 분석 결과 종합해서 CLEAN ~ CRITICAL 5단계 판정 |
| HTML 보고서 생성 | 분석 결과를 시각화한 보고서 자동 생성 |
## 프로젝트 구조
malscan/
├── main.py # CLI 진입점 및 분석 오케스트레이터
├── requirements.txt # 의존성 목록
├── analyzer/
│ ├── hash_checker.py # MD5 / SHA1 / SHA256 해시 계산
│ ├── vt_lookup.py # VirusTotal API v3 연동
│ ├── pe_parser.py # PE 파일 구조 분석
│ ├── string_extractor.py # 문자열 추출 및 패턴 매칭
│ ├── yara_scanner.py # YARA 룰 기반 악성코드 탐지
│ └── risk_scorer.py # 위험도 점수 계산 및 등급 판정
├── report/
│ └── report_generator.py # HTML 보고서 생성 (Jinja2)
├── yara_rules/
│ ├── nanocore_rat.yar # NanoCore / AsyncRAT / RemcosRAT 탐지
│ └── suspicious.yar # 인코딩 PowerShell / 코드인젝션 / 지속성 탐지
├── samples/ # 분석 대상 파일 (VM 환경에서만 사용)
└── output/ # 생성된 보고서 저장
## 분석 흐름
의심 파일 입력
↓
[1/5] 해시 계산 (MD5, SHA1, SHA256)
↓
[2/5] VirusTotal API 조회
↓
[3/5] PE 구조 분석 (섹션, Import Table, 엔트로피)
↓
[4/5] 문자열 추출 (URL, IP, 의심 명령어)
↓
[5/5] YARA 룰 매칭
↓
위험도 점수 계산 (0~100점)
↓
HTML 보고서 생성
## 위험도 점수 체계
분석 항목별로 가중치를 부여해 종합 점수를 계산합니다.
| 항목 | 배점 | 설명 |
|------|------|------|
| VirusTotal 탐지율 | 최대 40점 | 75개 백신 엔진 탐지 결과 |
| 의심 API 임포트 | 최대 25점 | 코드인젝션, 안티디버깅 등 위험 API |
| 의심 문자열 | 최대 20점 | C2 주소, 의심 명령어 등 |
| YARA 룰 매칭 | 최대 20점 | 알려진 악성코드 패턴 매칭 |
| 섹션 엔트로피 | 최대 15점 | 패킹/암호화 의심 지표 |
| 점수 | 등급 | 의미 |
|------|------|------|
| 0 ~ 15 | CLEAN | 정상으로 보임 |
| 16 ~ 35 | LOW | 낮은 위험, 추가 검토 권장 |
| 36 ~ 59 | MEDIUM | 중간 위험, 주의 필요 |
| 60 ~ 79 | HIGH | 높은 위험, 격리 권장 |
| 80 ~ 100 | CRITICAL | 매우 위험, 즉시 대응 필요 |
## 설치
git clone https://github.com/Seongmin1223/Malscan.git
cd Malscan
pip install -r requirements.txt
**요구 사항**
- Python 3.8 이상
- pip 패키지: `pefile`, `requests`, `jinja2`, `yara-python`
## 사용법
**기본 분석**
python main.py 파일경로.exe
**VirusTotal 조회 포함**
python main.py 파일경로.exe --vt-api-key YOUR_API_KEY
API_KEY는 https://www.virustotal.com/gui/home/upload에서 sign up -> API_KEY 발급하여 사용 요망
**JSON 형식으로 출력**
python main.py 파일경로.exe --json
**출력 경로 지정**
python main.py 파일경로.exe --output reports/result.html
**실행 예시**
[*] 분석 시작: dontopen.exe
--------------------------------------------------
[1/5] 해시 계산 중...
MD5 : de52c0a0c0b60dee20c4cb43f5b42a80
SHA256: 6f15b90269632ec13a103642699d06159...
[2/5] VirusTotal 조회 중...
탐지율: 60/75
[3/5] PE 구조 분석 중...
PE 파일 확인됨 | 섹션 수: 3
[4/5] 의심 문자열 추출 중...
URL: 0개 | IP: 3개 | 의심 명령어: 1개
[5/5] YARA 룰 스캔 중...
★ 2개 룰 매칭! (로드된 룰: 2개)
└─ Nanocore_RAT
└─ Suspicious_Code_Injection
┌─────────────────────────────────────┐
│ 위험도: HIGH 점수: 72/100 │
│ 높은 위험 — 격리 권장 │
└─────────────────────────────────────┘
[+] HTML 보고서 저장됨: output/dontopen_report.html
## HTML 보고서 포함 내용
- 위험도 배지 및 항목별 점수 바
- 파일 기본 정보 (아키텍처, 컴파일 시각, 진입점)
- 파일 해시 (MD5 / SHA1 / SHA256)
- YARA 매칭 결과 (룰 이름, 작성자, 매칭 패턴)
- VirusTotal 엔진별 탐지 결과 테이블
- PE 섹션 정보 및 엔트로피
- 의심 API 임포트 목록
- 전체 Import Table
- URL / IP / 이메일 / 레지스트리 경로
- Base64 후보 문자열
- 의심 명령어 문자열
## YARA 룰 추가 방법
`yara_rules/` 폴더에 `.yar` 또는 `.yara` 파일을 추가하면 자동으로 로드됩니다.
rule My_Custom_Rule
{
meta:
author = "작성자"
description = "탐지 설명"
strings:
$s1 = "탐지할 문자열" ascii wide
condition:
$s1
}
공개 룰셋 참고:
- [Florian Roth - signature-base](https://github.com/Neo23x0/signature-base)
- [JPCERT - yara_rules](https://github.com/JPCERTCC/jpcert-yara)
- [Elastic Security - protections-artifacts](https://github.com/elastic/protections-artifacts)
## 테스트 샘플
- [MalwareBazaar](https://bazaar.abuse.ch/) — 무료 악성코드 샘플 DB
- 다운로드 압축 해제 비밀번호: `infected`
## 분석 사례
**NanoCore RAT 분석 결과**
| 항목 | 결과 |
|------|------|
| VirusTotal | 60/75 탐지 |
| YARA | Nanocore_RAT 룰 매칭 |
| 섹션 수 | 3개 (패킹 의심) |
| 엔트로피 | 7.4 (암호화 의심) |
| 위험도 | MEDIUM ~ HIGH |
패킹된 악성코드라 Import Table은 숨겨져 있었지만 YARA 룰과 엔트로피 분석으로 탐지 가능했습니다.
## 한계점
- **패킹된 악성코드**: Import Table이 암호화돼 있어 의심 API 탐지가 제한됨
- **정적 분석 한계**: 실제 실행 없이는 동적 행위(C2 통신, 파일 생성 등) 확인 불가
- **YARA 룰 범위**: 기본 제공 룰셋 외 추가 룰 직접 작성 필요
## 향후 개발 계획
- [ ] ssdeep 퍼지 해시 연동 (변종 악성코드 유사도 분석)
- [ ] 폴더 일괄 분석 및 CSV 요약 출력
- [ ] PDF / Office 문서 분석 지원
- [ ] ANY.RUN API 연동 (동적 분석)
- [ ] .env 파일로 API 키 관리
## 개발 환경
- Python 3.12
- Windows 11 / Ubuntu 24 (VMware)
- 분석 환경: VMware Workstation (Host-only 네트워크)
## 참고 자료
- [pefile 라이브러리](https://github.com/erocarrera/pefile)
- [VirusTotal API v3 문서](https://developers.virustotal.com/reference)
- [YARA 공식 문서](https://yara.readthedocs.io/)
- [MalwareBazaar](https://bazaar.abuse.ch/)
- [Florian Roth YARA 룰셋](https://github.com/Neo23x0/signature-base)
- [malapi.io](https://malapi.io/) — 의심 Win32 API 레퍼런스
## 주요 기능
| 기능 | 설명 |
|------|------|
| 해시 계산 | MD5 / SHA1 / SHA256 자동 계산 |
| VirusTotal 조회 | API로 75개 이상 백신 엔진 탐지 결과 조회 |
| PE 구조 분석 | 헤더, 섹션, Import Table, 엔트로피 분석 |
| 문자열 추출 | URL, IP, 이메일, 레지스트리 경로, 의심 명령어 추출 |
| YARA 룰 매칭 | 공개 룰셋 기반 악성코드 패턴 탐지 |
| 위험도 자동 판정 | 분석 결과 종합해서 CLEAN ~ CRITICAL 5단계 판정 |
| HTML 보고서 생성 | 분석 결과를 시각화한 보고서 자동 생성 |
## 프로젝트 구조
malscan/
├── main.py # CLI 진입점 및 분석 오케스트레이터
├── requirements.txt # 의존성 목록
├── analyzer/
│ ├── hash_checker.py # MD5 / SHA1 / SHA256 해시 계산
│ ├── vt_lookup.py # VirusTotal API v3 연동
│ ├── pe_parser.py # PE 파일 구조 분석
│ ├── string_extractor.py # 문자열 추출 및 패턴 매칭
│ ├── yara_scanner.py # YARA 룰 기반 악성코드 탐지
│ └── risk_scorer.py # 위험도 점수 계산 및 등급 판정
├── report/
│ └── report_generator.py # HTML 보고서 생성 (Jinja2)
├── yara_rules/
│ ├── nanocore_rat.yar # NanoCore / AsyncRAT / RemcosRAT 탐지
│ └── suspicious.yar # 인코딩 PowerShell / 코드인젝션 / 지속성 탐지
├── samples/ # 분석 대상 파일 (VM 환경에서만 사용)
└── output/ # 생성된 보고서 저장
## 분석 흐름
의심 파일 입력
↓
[1/5] 해시 계산 (MD5, SHA1, SHA256)
↓
[2/5] VirusTotal API 조회
↓
[3/5] PE 구조 분석 (섹션, Import Table, 엔트로피)
↓
[4/5] 문자열 추출 (URL, IP, 의심 명령어)
↓
[5/5] YARA 룰 매칭
↓
위험도 점수 계산 (0~100점)
↓
HTML 보고서 생성
## 위험도 점수 체계
분석 항목별로 가중치를 부여해 종합 점수를 계산합니다.
| 항목 | 배점 | 설명 |
|------|------|------|
| VirusTotal 탐지율 | 최대 40점 | 75개 백신 엔진 탐지 결과 |
| 의심 API 임포트 | 최대 25점 | 코드인젝션, 안티디버깅 등 위험 API |
| 의심 문자열 | 최대 20점 | C2 주소, 의심 명령어 등 |
| YARA 룰 매칭 | 최대 20점 | 알려진 악성코드 패턴 매칭 |
| 섹션 엔트로피 | 최대 15점 | 패킹/암호화 의심 지표 |
| 점수 | 등급 | 의미 |
|------|------|------|
| 0 ~ 15 | CLEAN | 정상으로 보임 |
| 16 ~ 35 | LOW | 낮은 위험, 추가 검토 권장 |
| 36 ~ 59 | MEDIUM | 중간 위험, 주의 필요 |
| 60 ~ 79 | HIGH | 높은 위험, 격리 권장 |
| 80 ~ 100 | CRITICAL | 매우 위험, 즉시 대응 필요 |
## 설치
git clone https://github.com/Seongmin1223/Malscan.git
cd Malscan
pip install -r requirements.txt
**요구 사항**
- Python 3.8 이상
- pip 패키지: `pefile`, `requests`, `jinja2`, `yara-python`
## 사용법
**기본 분석**
python main.py 파일경로.exe
**VirusTotal 조회 포함**
python main.py 파일경로.exe --vt-api-key YOUR_API_KEY
API_KEY는 https://www.virustotal.com/gui/home/upload에서 sign up -> API_KEY 발급하여 사용 요망
**JSON 형식으로 출력**
python main.py 파일경로.exe --json
**출력 경로 지정**
python main.py 파일경로.exe --output reports/result.html
**실행 예시**
[*] 분석 시작: dontopen.exe
--------------------------------------------------
[1/5] 해시 계산 중...
MD5 : de52c0a0c0b60dee20c4cb43f5b42a80
SHA256: 6f15b90269632ec13a103642699d06159...
[2/5] VirusTotal 조회 중...
탐지율: 60/75
[3/5] PE 구조 분석 중...
PE 파일 확인됨 | 섹션 수: 3
[4/5] 의심 문자열 추출 중...
URL: 0개 | IP: 3개 | 의심 명령어: 1개
[5/5] YARA 룰 스캔 중...
★ 2개 룰 매칭! (로드된 룰: 2개)
└─ Nanocore_RAT
└─ Suspicious_Code_Injection
┌─────────────────────────────────────┐
│ 위험도: HIGH 점수: 72/100 │
│ 높은 위험 — 격리 권장 │
└─────────────────────────────────────┘
[+] HTML 보고서 저장됨: output/dontopen_report.html
## HTML 보고서 포함 내용
- 위험도 배지 및 항목별 점수 바
- 파일 기본 정보 (아키텍처, 컴파일 시각, 진입점)
- 파일 해시 (MD5 / SHA1 / SHA256)
- YARA 매칭 결과 (룰 이름, 작성자, 매칭 패턴)
- VirusTotal 엔진별 탐지 결과 테이블
- PE 섹션 정보 및 엔트로피
- 의심 API 임포트 목록
- 전체 Import Table
- URL / IP / 이메일 / 레지스트리 경로
- Base64 후보 문자열
- 의심 명령어 문자열
## YARA 룰 추가 방법
`yara_rules/` 폴더에 `.yar` 또는 `.yara` 파일을 추가하면 자동으로 로드됩니다.
rule My_Custom_Rule
{
meta:
author = "작성자"
description = "탐지 설명"
strings:
$s1 = "탐지할 문자열" ascii wide
condition:
$s1
}
공개 룰셋 참고:
- [Florian Roth - signature-base](https://github.com/Neo23x0/signature-base)
- [JPCERT - yara_rules](https://github.com/JPCERTCC/jpcert-yara)
- [Elastic Security - protections-artifacts](https://github.com/elastic/protections-artifacts)
## 테스트 샘플
- [MalwareBazaar](https://bazaar.abuse.ch/) — 무료 악성코드 샘플 DB
- 다운로드 압축 해제 비밀번호: `infected`
## 분석 사례
**NanoCore RAT 분석 결과**
| 항목 | 결과 |
|------|------|
| VirusTotal | 60/75 탐지 |
| YARA | Nanocore_RAT 룰 매칭 |
| 섹션 수 | 3개 (패킹 의심) |
| 엔트로피 | 7.4 (암호화 의심) |
| 위험도 | MEDIUM ~ HIGH |
패킹된 악성코드라 Import Table은 숨겨져 있었지만 YARA 룰과 엔트로피 분석으로 탐지 가능했습니다.
## 한계점
- **패킹된 악성코드**: Import Table이 암호화돼 있어 의심 API 탐지가 제한됨
- **정적 분석 한계**: 실제 실행 없이는 동적 행위(C2 통신, 파일 생성 등) 확인 불가
- **YARA 룰 범위**: 기본 제공 룰셋 외 추가 룰 직접 작성 필요
## 향후 개발 계획
- [ ] ssdeep 퍼지 해시 연동 (변종 악성코드 유사도 분석)
- [ ] 폴더 일괄 분석 및 CSV 요약 출력
- [ ] PDF / Office 문서 분석 지원
- [ ] ANY.RUN API 연동 (동적 분석)
- [ ] .env 파일로 API 키 관리
## 개발 환경
- Python 3.12
- Windows 11 / Ubuntu 24 (VMware)
- 분석 환경: VMware Workstation (Host-only 네트워크)
## 참고 자료
- [pefile 라이브러리](https://github.com/erocarrera/pefile)
- [VirusTotal API v3 문서](https://developers.virustotal.com/reference)
- [YARA 공식 문서](https://yara.readthedocs.io/)
- [MalwareBazaar](https://bazaar.abuse.ch/)
- [Florian Roth YARA 룰셋](https://github.com/Neo23x0/signature-base)
- [malapi.io](https://malapi.io/) — 의심 Win32 API 레퍼런스