masriyan/flatscanGo로 작성된 정적 악성코드 트리아지 엔진: 파일 해시를 계산하고, 문자열과 IOC를 추출하며, PE/ELF/Mach-O/APK를 파싱하고, 기능을 점수화하여 JSON, YARA, Sigma, STIX 및 PDF 보고서를 출력합니다.
FlatScan은 순수 Go로 작성된 프로덕션급 정적 악성코드 분석 및 보고 엔진입니다. 빠른 트리아지, IOC 추출, 의심스러운 기능 탐지, 경영진 보고, 헌팅 규칙 전달이 필요한 분석가를 위해 설계되었으며, 이 모든 것을 샘플을 실행하지 않고 수행합니다.
FlatScan은 파일을 읽고, 해시를 계산하고, 형식을 식별하고, 문자열을 추출하고, 의심스러운 인코딩 데이터를 디코딩하고, IOC를 추출 및 분류하고, 실행 파일/컨테이너 메타데이터를 검사하고, 발견 사항을 점수화하고, 이를 악성코드 프로파일로 보강한 뒤, 텍스트, JSON, PDF, HTML, IOC, YARA, Sigma, STIX 2.1, 케이스 데이터베이스, 보고서 팩 출력을 생성합니다.
악성코드 트리아지에는 흔히 두 가지 대상이 있습니다:
| 대상 | 필요한 것 |
|---|---|
| 보안 분석가 | 기술적 증거: 해시, 문자열, 임포트, IOC, 엔트로피, 섹션, 디코딩된 데이터, TTP, 헌팅 규칙 |
| CISO / 경영진 | 위험 맥락: 무엇일 가능성이 있는지, 왜 중요한지, 비즈니스 영향, 권장 조치 |
FlatScan은 두 대상 모두를 지원합니다. 안전성과 속도를 위해 정적 분석을 수행한 뒤, 그 결과를 기계 판독 가능한 출력과 경영진이 바로 사용할 수 있는 보고서로 변환합니다.
graph LR
A[Malware Sample] --> B[FlatScan Engine]
B --> C[Analyst Reports]
B --> D[Executive Reports]
B --> E[Machine-Readable]
B --> F[Hunting Rules]
C -->|HTML, Full Text| G[SOC Team]
D -->|PDF, Executive MD| H[CISO / Board]
E -->|JSON, STIX 2.1| I[SIEM / SOAR]
F -->|YARA, Sigma| J[EDR / Hunt Team]
FlatScan은 병렬 실행, 플러그인 시스템, 그리고 외부 의존성 없음을 특징으로 하는 다단계 분석 파이프라인으로 구축되었습니다. go.mod는 아무것도 요구하지 않으며, 순수 Go 디스어셈블리 엔진은 internal/x86asm으로 트리 내에 벤더링되어 있습니다(golang.org/x/arch/x86/x86asm의 수정되지 않은 사본, BSD-3-Clause). cgo 없음, 런타임 또는 시스템 의존성 없음, 빌드에 네트워크가 필요하지 않습니다.
graph TB
subgraph "Input Layer"
CLI[CLI Parser] --> CFG[Config]
INT[Interactive Mode] --> CFG
SHL[Shell Mode] --> CFG
WCH[Watch Mode] --> CFG
end
subgraph "I/O Layer"
CFG --> MMP{File > 100MB?}
MMP -->|Yes| MMAP[Memory-Mapped I/O]
MMP -->|No| BUF[Buffered Read]
MMAP --> DATA[Raw Bytes + Hashes]
BUF --> DATA
end
subgraph "Analysis Pipeline"
DATA --> DET[File Type Detection]
DET --> ENT[Entropy Analysis]
ENT --> STR[String Extraction]
STR --> IOC[IOC Extraction]
IOC --> DEC[Decoder Pass]
DEC --> CRP[Corpus Build]
CRP --> PAT[Pattern Matching]
PAT --> PG["Parallel Group"]
subgraph PG["⚡ Parallel Stages"]
FMT[Format Analysis]
CRV[Safe Carving]
CRY[Crypto/Config]
SIM[Similarity Hash]
end
PG --> SEQ[Sequential Stages]
SEQ --> PLG[Plugin Engine]
PLG --> SCR[Risk Scoring]
end
subgraph "Output Layer"
SCR --> TXT[Text Report]
SCR --> JSN[JSON]
SCR --> PDF[PDF Report]
SCR --> HTM[HTML Report]
SCR --> YAR[YARA Rule]
SCR --> SIG[Sigma Rule]
SCR --> STX[STIX 2.1]
SCR --> RPK[Report Pack]
end
style PG fill:#1a1a2e,stroke:#e94560,stroke-width:2px
style SCR fill:#0f3460,stroke:#e94560,stroke-width:2px
| 원칙 | 구현 |
|---|---|
| 외부 의존성 제로 | go.mod는 아무것도 요구하지 않으며 go.sum도 없다. Go 표준 라이브러리와 벤더링된 수정되지 않은 패키지 하나 — internal/x86asm은 golang.org/x/arch/x86/x86asm(BSD-3-Clause, 디스어셈블리 엔진)의 복사본으로 트리 내에 보관되어 빌드에 다운로드나 네트워크가 필요 없다. cgo 없음, 네이티브 라이브러리 없음, 런타임 의존성 없음 |
| 정적 분석 전용 | 샘플을 절대 실행하지 않음 — 바이트와 메타데이터만 읽음 |
| 스레드 안전 | 뮤텍스로 보호되는 발견 항목과 함께 parallelRun() 사용, 레이스 검출기로 검증됨. 분석 단계는 패닉을 개별적으로 복구하므로 하나의 잘못된 샘플이 배치 전체를 중단시킬 수 없음 |
| 플랫폼 이식성 | Linux, macOS, Windows용으로 빌드됨; Linux에서는 mmap 사용, 투명한 폴백 지원 |
| 확장 가능 | 재컴파일 없이 사용자 정의 탐지를 위한 플러그인 인터페이스 + JSON 매니페스트 |
| 검사 | 결과 |
|---|---|
go build / go vet / gofmt -l | 깨끗함 |
go test ./... | 189개 테스트(하위 테스트 포함 344개 케이스), 모두 통과 |
go test -race ./... | 깨끗함 |
go test -cover ./... | 문장의 50.6% |
golangci-lint run | 0개 이슈 (errcheck, govet, staticcheck, gosec, errorlint, ineffassign, unused, bodyclose, nilerr, misspell, unconvert, wastedassign) |
govulncheck ./... | 취약점 발견되지 않음 |
테스트 환경. Fedora Linux 44 (x86_64, 커널 7.1.7) 및 Go 1.26.5에서 검증됨.
go.mod의 최소 요구 버전은 Go 1.25이다. CI는 추가로 ubuntu-latest에서 동일한 스위트를 실행한다.
Linux는 이 결과가 측정된 유일한 플랫폼이다: macOS와 Windows는
지원 대상이며 코드가 이들로 크로스 컴파일되지만, 위 수치는
그곳에서 독립적으로 재현되지 않았으며, mmap_linux.go는
구조상 Linux 전용이다(다른 플랫폼은 버퍼링된 읽기 폴백을 사용).
엔진은 독립적인 작업에 대해 병렬 실행을 통해 18개 단계로 파일을 처리한다:
sequenceDiagram
participant CLI as CLI/Interactive
participant IO as I/O Layer
participant Engine as Analysis Engine
participant Parallel as Parallel Group
participant Score as Scoring
participant Output as Output Renderers
CLI->>IO: Config + File Path
IO->>IO: mmap or buffered read
IO->>IO: Compute MD5/SHA1/SHA256/SHA512
IO->>Engine: Raw bytes + Hashes
Engine->>Engine: 1. File type detection
Engine->>Engine: 2. Entropy analysis (incremental)
Engine->>Engine: 3. String extraction (zero-alloc)
Engine->>Engine: 4. IOC extraction + triage
Engine->>Engine: 5. Decoder pass (base64/hex/URL)
Engine->>Engine: 6. Corpus build (shared, single alloc)
Engine->>Engine: 7. Pattern matching
Engine->>Parallel: Launch independent stages
par Format Analysis
Parallel->>Parallel: PE/ELF/Mach-O/APK/MSIX
and Safe Carving
Parallel->>Parallel: Embedded artifacts
and Crypto/Config
Parallel->>Parallel: C2, tokens, mutex, wallets
and Similarity
Parallel->>Parallel: FlatHash, import hash, section hash
end
Parallel->>Engine: Merged results
Engine->>Engine: 8. Rules + Plugins
Engine->>Engine: 9. Family classification
Engine->>Score: Findings
Score->>Score: Deduplicate + Score + Verdict
Score->>Output: Enriched ScanResult
par Output Generation
Output->>Output: Text/JSON/PDF/HTML/YARA/Sigma/STIX
end