---

## クイックスタート

### 前提条件

- 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つのコンテナが起動します：

| Service | Port | Role |
|---|---|---|
| `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

3層のアプローチで実行ファイルとバイナリを分析：

- **Ghidra 12.0.1** (`pyghidra`経由) — すべての関数の完全な逆コンパイルをC擬似コードに
- **`objdump -d`** — アセンブリレベルでの逆アセンブル
- **VirusTotal API v3** — 70以上のAVエンジンによる検出、動作タグ、ファイルのレピュテーション

**対応形式:** `exe`, `dll`, `so`, `elf`, `bin`, `o`, `out` · 最大50 MB · 4 GB 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 blocklist | IPレピュテーション/ブラックリスト |
| `tor` | Tor Project exit list | Tor出口ノード検出 |
| `tranco` | Tranco ranking list | ドメインの人気ランク |
| `threatfox` | abuse.ch ThreatFox | アクティブなIOC/マルウェア関連 |

**フットプリントモード** (メール/電話/ユーザー名)：
- **メール** — XposedOrNot漏洩データベース（漏洩数、深刻度、パスワードリスク）
- **電話** — NumVerifyキャリア+国+回線種別の検証
- **ユーザー名** — ソーシャルプラットフォーム全体でのSagemodeマルチスレッドプロファイル発見

---

### Web脆弱性アナライザー — ポート5005

URLとWebエンドポイントを監査：

- セキュリティヘッダー分析（CSP、HSTS、X-Frame-Optionsなど）
- テクノロジーフィンガープリンティング（サーバー、フレームワーク、CMS）
- HTTPレスポンス分析とリダイレクトチェーンの追跡
- 一般的な設定ミスに対する基本的な脆弱性スキャン

---

### マクロ/Officeアナライザー — ポート5006

悪意のあるマクロを探してOffice文書を解析：

- **oletools (olevba)** — VBA/XLMマクロの抽出と逆コンパイル
- **AutoExec検出** — 開封/クローズ時に自動実行されるマクロをフラグ付け
- **IOC抽出** — マクロコードに埋め込まれたURL、IP、ファイルパス
- **難読化検出** — Base64、Chr()チェーン、16進エンコーディング
- **VirusTotal API v3** — ファイルレピュテーションのクロスチェック

**対応形式:** `doc`, `docx`, `docm`, `xls`, `xlsx`, `xlsm`, `xlsb`, `ppt`, `pptx`, `pptm`, `rtf`

---

## レポート出力

各パイプラインの実行では、`backend/reports/<job_id>/` に保存される **2つのレポート形式** が生成されます：

### HTMLレポート (`report.html`)

任意のブラウザで開きます。**Export PDF** をクリックして印刷 — サーバーサイドのPDFレンダリングは不要、依存関係もありません。

内容: エグゼクティブサマリー · YARAルール · SIGMAルール · MITRE TTP · パスごとの証拠パネル · VirusTotalエンジンバッジ

### JSONレポート (`report.json`)

完全に構造化された機械可読出力。以下の場合に使用：
- 調査結果を別のAIモデルに直接入力してより深い分析を行う
- SIEMやチケッティングシステムに取り込む
- 2つのレポートをプログラムで比較する
- カスタムダッシュボードを構築する

JSONはHTMLを完全にミラーリングします — すべての調査結果、YARAルール、SIGMAルール、IOC、TTPがクリーンで型付けされたスキーマに存在します。

サンプル入力ファイルについては [`examples/`](https://github.com/aradhyacp/secflow/blob/main/examples) を、開発中に生成された実際のレポート出力については [`example_reports`](https://github.com/aradhyacp/secflow/blob/main/example_reports) を参照してください。

---

### エグゼクティブサマリー
AIによるナラティブ (Groq `qwen/qwen3-32b`) がカバー：
- 特定された脅威名とアクタータイプの分類
- 攻撃チェーンの再構築（ステップバイステップ）
- 信頼度評価と全体的なリスクスコア

### YARA検出ルール
**2～5の本番対応YARAルール** が `llama-3.3-70b-versatile` によって生成され、各ルール：
- `SecFlow_[ThreatCategory]_[IndicatorType]` の命名規則
- 有効な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/main/examples) にあります。 — 実際のマルウェアサンプル（`RealMalware.exe`、`ColorBug.exe`、`EarlyEnd.exe`、`.out` ELFバイナリ）および悪意のあるOffice文書（`nuclear_motor_example.docm`）が含まれています。対応するレポート出力は [`backend/reports/`](https://github.com/aradhyacp/secflow/blob/main/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 / ドメイン):**```bash
curl -X POST http://localhost:5000/api/smart-analyze \
  -H "Content-Type: application/json" \
  -d '{"target": "https://suspicious-site.com", "passes": 5}'