## 빠른 시작

### 사전 요구사항

- Docker + Docker Compose
- Groq 및 VirusTotal용 API 키 (무료 티어 사용 가능)

### 1. 저장소 클론```bash
git clone https://github.com/aradhyacp/SecFlow.git
cd SecFlow/backend

`.env` 파일을 당신의 키로 편집하세요:```env
# Required
GROQ_API_KEY=your_groq_api_key_here
VIRUSTOTAL_API_KEY=your_vt_api_key_here

# Optional — unlock additional OSINT capabilities
NUMVERIFY_API_KEY=your_numverify_key      # Phone number lookups
THREATFOX_API_KEY=your_threatfox_key      # Higher ThreatFox rate limits
ipAPI_KEY=your_ipapi_key                  # Higher ip-api.com rate limits

# Pipeline control
MAX_PASSES=3                              # 3 | 4 | 5

다음 6개의 컨테이너가 시작됩니다:

| 서비스 | 포트 | 역할 |
|---|---|---|
| `orchestrator` | `5000` | 파이프라인 컨트롤러 — 주요 진입점 |
| `malware-analyzer` | `5001` | Ghidra 디컴파일 + VirusTotal |
| `steg-analyzer` | `5002` | binwalk + zsteg + steghide + ExifTool |
| `recon-analyzer` | `5003` | ip-api + ThreatFox + OSINT |
| `web-analyzer` | `5005` | HTTP 취약점 스캐너 + 헤더 감사 |
| `macro-analyzer` | `5006` | oletools (olevba) + VirusTotal |

> **참고:** 첫 실행 시 몇 분 정도 소요될 수 있습니다 — Malware Analyzer가 Ghidra 12.0.1 (~500 MB)을 다운로드하며 JDK 21 JVM이 필요합니다.

### 4. 첫 번째 분석 실행

**파일 분석:**```bash
curl -X POST http://localhost:5000/api/smart-analyze \
  -F "file=@/path/to/suspicious.exe" \
  -F "passes=3"

**응답:**```json
{
  "job_id": "a1b2c3d4",
  "findings": [...],
  "report_paths": {
    "json": "/api/report/a1b2c3d4/json",
    "html": "/api/report/a1b2c3d4/html"
  }
}

Open `http://localhost:5173` — React 대시보드를 통해 분석을 제출하고, 파이프라인 진행 상황을 실시간으로 확인하며, 분석기별 결과를 탐색할 수 있습니다.

---

## 분석기

### 악성코드 분석기 — 포트 5001

실행 파일 및 바이너리를 세 가지 계층으로 분석합니다:

- **Ghidra 12.0.1** (`pyghidra` 경유) — 모든 함수를 C 유사 코드로 완전 디컴파일
- **`objdump -d`** — 어셈블리 수준 디스어셈블리
- **VirusTotal API v3** — 70개 이상의 AV 엔진 탐지, 동작 태그, 파일 평판

**지원 형식:** `exe`, `dll`, `so`, `elf`, `bin`, `o`, `out` · 최대 50MB · 4GB RAM 필요 (Ghidra JVM)

---

### 스테가노그래피 분석기 — 포트 5002

여러 방법을 사용하여 이미지에 숨겨진 데이터를 탐지합니다:

- **binwalk** — 바이너리 오프셋에서 임베디드 파일 탐지 및 추출
- **foremost** — 원시 바이너리 스트림에서 파일 카빙
- **zsteg** — PNG/BMP의 LSB 스테가노그래피 탐지
- **steghide** — JPEG/BMP에서 패스프레이즈 기반 스테그 탐지
- **ExifTool** — 메타데이터 추출 및 이상 탐지

**임베디드 아카이브를 추출하고 다음 파이프라인 단계에서 재분석을 위해 대기시킵니다.**

**지원 형식:** PNG, JPG, BMP, GIF, TIFF, WebP

---

### 정찰 분석기 — 포트 5003

네트워크 식별자에 대한 위협 인텔리전스 및 OSINT를 수행합니다:

**스캔 모드** (IP / 도메인):

| 모듈 | 출처 | 확인 사항 |
|---|---|---|
| `ipapi` | ip-api.com | 국가, ISP, ASN, 지리적 위치 |
| `talos` | Cisco Talos 차단 목록 | IP 평판 / 블랙리스트 |
| `tor` | Tor 프로젝트 종료 목록 | Tor 종료 노드 탐지 |
| `tranco` | Tranco 순위 목록 | 도메인 인기 순위 |
| `threatfox` | abuse.ch ThreatFox | 활성 IOC / 악성코드 연관성 |

**풋프린트 모드** (이메일 / 전화번호 / 사용자 이름):
- **이메일** — XposedOrNot 침해 데이터베이스 (침해 횟수, 심각도, 비밀번호 위험)
- **전화번호** — NumVerify 통신사 + 국가 + 회선 유형 검증
- **사용자 이름** — Sagemode 멀티스레드 프로필 탐색 (소셜 플랫폼 대상)

---

### 웹 취약점 분석기 — 포트 5005

URL 및 웹 엔드포인트를 감사합니다:

- 보안 헤더 분석 (CSP, HSTS, X-Frame-Options 등)
- 기술 스택 식별 (서버, 프레임워크, CMS)
- HTTP 응답 분석 및 리다이렉션 체인 추적
- 일반적인 잘못된 구성에 대한 기본 취약점 스캐닝

---

### 매크로 / 오피스 분석기 — 포트 5006

악성 매크로를 찾기 위해 Office 문서를 분석합니다:

- **oletools (olevba)** — VBA/XLM 매크로 추출 및 디컴파일
- **자동 실행 탐지** — 열기/닫기 시 자동 실행되는 매크로 플래그 지정
- **IOC 추출** — 매크로 코드에 내장된 URL, IP, 파일 경로
- **난독화 탐지** — Base64, Chr() 체인, 16진수 인코딩
- **VirusTotal API v3** — 파일 평판 교차 확인

**지원 형식:** `doc`, `docx`, `docm`, `xls`, `xlsx`, `xlsm`, `xlsb`, `ppt`, `pptx`, `pptm`, `rtf`

---

## 보고서 출력

모든 파이프라인 실행은 `backend/reports/<job_id>/`에 저장되는 **두 가지 보고서 형식**을 생성합니다:

### HTML 보고서 (`report.html`)

어떤 브라우저에서든 열 수 있습니다. **PDF 내보내기**를 클릭하여 인쇄 — 서버 측 PDF 렌더링이 필요 없으며 종속성도 없습니다.

포함 내용: 요약 · YARA 규칙 · SIGMA 규칙 · MITRE TTP · 패스별 증거 패널 · VirusTotal 엔진 배지

### JSON 보고서 (`report.json`)

완전히 구조화된 기계 판독 가능 출력입니다. 다음 상황에서 사용하세요:
- 분석 결과를 다른 AI 모델에 직접 입력하여 심층 분석
- SIEM 또는 티켓팅 시스템에 수집
- 두 보고서를 프로그래밍 방식으로 비교
- 맞춤형 대시보드 구축

JSON은 HTML을 정확히 반영합니다 — 모든 발견 사항, YARA 규칙, SIGMA 규칙, IOC 및 TTP가 깔끔하고 타입이 명시된 스키마에 존재합니다.

샘플 입력 파일은 [`examples/`](https://github.com/aradhyacp/secflow/blob/HEAD/examples/)를 참조하고, 개발 중 생성된 실제 보고서 출력은 [`example_reports`](https://github.com/aradhyacp/secflow/blob/HEAD/example_reports/)를 참조하세요.

---

### 요약
AI 작성 설명 (Groq `qwen/qwen3-32b`) 포함 내용:
- 식별된 위협 이름 및 공격자 유형 분류
- 공격 체인 재구성 (단계별)
- 신뢰도 평가 및 전체 위험 점수

### YARA 탐지 규칙
`llama-3.3-70b-versatile`로 생성된 **2~5개의 프로덕션 준비 YARA 규칙**, 각 규칙:
- `SecFlow_[위협범주]_[지표유형]` 규칙 명명
- 유효한 YARA 4.x 구문 포함 — 모든 YARA 호환 스캐너로 즉시 가져오기 가능
- 규칙을 생성한 분석의 정확한 증거를 인용하는 `reasoning` 필드 포함
- 별개의 측면 포함: 파일 시그니처, 포함 문자열, C2 지표, 패커 시그니처, 메모리 패턴```yara
rule SecFlow_Trojan_C2StringIndicator {
  meta:
    description = "Detects C2 callback string found in Ghidra decompilation"
    author      = "SecFlow AI"
    severity    = "high"
  strings:
    $c2 = "evil.sh/drop.exe"
    $ua = "Mozilla/4.0 (compatible; MSIE 6.0)"
  condition:
    any of them
}

### MITRE ATT&CK TTPs
식별된 모든 동작이 실제 기술 ID와 전술 이름 및 근거와 매핑됩니다.

### 패스별 증거
각 분석기 패스에 대한 접을 수 있는 패널:
- Ghidra 디컴파일 출력 (어두운 코드 블록, 접을 수 있음)
- objdump 디스어셈블리 (접을 수 있음)
- VirusTotal 엔진 탐지 (색상 코드 심각도 배지)
- 원시 분석기 결과 JSON

### PDF 내보내기
PDF 내보내기를 위해 사전 구성된 원클릭 브라우저 인쇄 대화상자 — 서버 측 PDF 생성이 필요 없습니다.

---

## 예제 파이프라인 실행

샘플 입력 파일은 [`examples/`](https://github.com/aradhyacp/secflow/blob/HEAD/examples/)에 있습니다 — 실제 악성코드 샘플(`RealMalware.exe`, `ColorBug.exe`, `EarlyEnd.exe`, `.out` ELF 바이너리)과 악성 Office 문서(`nuclear_motor_example.docm`)를 포함합니다. 해당 보고서 출력은 [`backend/reports/`](https://github.com/aradhyacp/secflow/blob/HEAD/backend/reports/)에 있습니다.

### 악성 Office 문서```
Input:  invoice.xlsm
Passes: 3

Pass 1 ─ Rule: .xlsm extension → Macro Analyzer
          olevba: AutoExec macro found
          IOC: http://evil.sh/drop.exe
          VT: 12/70 engines flagged

Pass 2 ─ AI: URL found in IOCs → Web Analyzer
          http://evil.sh/drop.exe — alive, 302 redirect to CDN

Pass 3 ─ AI: no further tool, but HTTP URL in raw_output
          Download: drop.exe → Malware Analyzer
          Ghidra: C2 callback string, packed PE
          VT: 45/70 detections — Trojan.GenericKDZ

Report  ─ PWNDoc HTML generated
          YARA: 4 rules (string, byte sig, packer, C2 domain)
          SIGMA: 3 rules (process_creation, network, registry)
          MITRE: T1566.001, T1059.005, T1071.001

### 의심스러운 도메인```
Input:  malicious-domain.ru
Passes: 3

Pass 1 ─ Rule: domain regex → Recon Analyzer
          ipapi: RU, ISP: HostMaster LLC
          Talos: on blocklist
          ThreatFox: linked to Raccoon Stealer, confidence 95

Pass 2 ─ AI: ThreatFox hit → Web Analyzer
          /login endpoint returns 200, harvesting form detected

Pass 3 ─ AI: no futher signals — loop exits early

Report  ─ Executive summary + TTPs + SIGMA network rules

---

## AI 모델

SecFlow는 모든 AI 추론에 **Groq**를 사용합니다. 무료 등급이며, 신용카드가 필요하지 않습니다.

| 역할 | 모델 | 이유 |
|---|---|---|
| **파이프라인 라우팅** | `qwen/qwen3-32b` | 신뢰할 수 있는 구조화된 JSON 출력; `/no_think` 모드는 사고 과정을 생략하여 빠른 라우팅 결정을 내립니다. |
| **위협 인텔리전스** | `llama-3.3-70b-versatile` | YARA/SIGMA 생성 및 MITRE TTP 매핑을 위한 강력한 추론 |
| **보고서 요약** | `qwen/qwen3-32b` | 경영진 요약 + 권장 사항 |

SecFlow는 표준 `openai` Python SDK를 통해 **OpenAI 호환 API 사양**을 사용합니다. 공급업체별 SDK가 필요하지 않습니다. 즉, `base_url`과 모델 이름만 변경하면 모든 OpenAI 호환 모델 제공업체(OpenAI, Groq, Together, Ollama 등)로 전환할 수 있습니다.```python
from openai import OpenAI

# Groq (current — free tier)
client = OpenAI(api_key=GROQ_API_KEY, base_url="https://api.groq.com/openai/v1")

# OpenAI (drop-in swap)
client = OpenAI(api_key=OPENAI_API_KEY)  # base_url defaults to api.openai.com

# Local Ollama (fully offline)
client = OpenAI(api_key="ollama", base_url="http://localhost:11434/v1")

**대상 입력 (URL / IP / domain):**```bash
curl -X POST http://localhost:5000/api/smart-analyze \
  -H "Content-Type: application/json" \
  -d '{"target": "https://suspicious-site.com", "passes": 5}'