docs/AGENT_ESSENCE.md

# ThreatHunter Agent 本質說明書

> **版本**：v1.0 | **更新日期**：2026-04-23  
> **用途**：給團隊成員理解每個 Agent 本質上在做什麼

---

## 總覽：Pipeline 資料流

```
使用者輸入（程式碼 / 套件 / 設定檔）
       │
       ▼
┌──────────────────┐
│   Orchestrator   │ ← 指揮官：決定走哪條路（A/B/C/D）、誰要上場
└──────┬───────────┘
       │ 並行 Layer 1
       ▼
┌──────────────┐  ┌───────────────┐  ┌──────────────────┐
│Security Guard│  │ Intel Fusion  │  │ L0/L1 Scanner    │
│（程式碼消毒） │  │（六維情報融合）│  │（正則預掃描）     │
└──────┬───────┘  └───────┬───────┘  └────────┬─────────┘
       │                  │                   │
       └──────────┬───────┘───────────────────┘
                  ▼
          ┌──────────────┐
          │    Scout     │ ← 偵察兵：組裝最終漏洞清單，重用 Intel Fusion 情報
          └──────┬───────┘
                 ▼
          ┌──────────────┐
          │   Analyst    │ ← 分析師：KEV 驗證 + 連鎖攻擊分析
          └──────┬───────┘
                 ▼
          ┌──────────────┐
          │ Debate Engine│ ← 辯論：Analyst vs Critic（最多 3 輪）
          │  + Critic    │
          │  + Judge     │
          └──────┬───────┘
                 ▼
          ┌──────────────┐
          │   Advisor    │ ← 顧問：產出可執行的行動報告
          └──────────────┘
                 │
                 ▼
              UI 顯示
```

---

## 1. Orchestrator（指揮官）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/orchestrator.py` (518 行) |
| **本質** | **不用 LLM 做推理的確定性路由器**。根據輸入類型決定走哪條路、跳過哪些 Agent、走哪些捷徑 |
| **LLM 使用** | 幾乎不用。路由邏輯全是 if/else 確定性程式碼 |
| **核心函式** | `classify_input()` → 決定 Path A/B/C/D |
| | `check_shortcuts()` → MacNet Small-World 捷徑 |
| | `review_worker_output()` → 審閱各 Agent 輸出品質 |

### 四條掃描路徑

| 路徑 | 觸發條件 | 啟動的 Agent |
|------|---------|-------------|
| **A** 套件掃描 | 輸入只有 `package==version` | Intel Fusion → Scout → Analyst → Debate → Judge |
| **B** 完整程式碼 | 有 `def`/`class` 等程式碼 | Security Guard + Intel Fusion + L0 → Scout → Analyst → Debate → Judge |
| **C** 文件掃描 | `.env`/`.yaml` 等設定檔 | Doc Scanner + Intel Fusion → Scout → Judge |
| **D** 回饋迴路 | Judge 信心不足時觸發 | Intel Fusion → Analyst → Debate → Judge（最多 2 次） |

### Small-World 捷徑（省 Token 機制）

| 捷徑 | 觸發條件 | 效果 |
|------|---------|------|
| `kev_to_analyst_direct` | CISA KEV 命中 | 跳過 Scout 重新評分 |
| `skip_l2_llm` | L0 正則零發現 | 跳過 L2 LLM 分析 |
| `debate_phase2_skipped` | 辯論第一輪就共識 | 省 6 次 LLM 呼叫 |
| `skip_debate_all_low` | 全部 CVSS < 4.0 | 跳過整個辯論 |

---

## 2. Security Guard（程式碼消毒員）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/security_guard.py` (1174 行) |
| **本質** | **完全確定性的靜態分析引擎**。用正則 + AST 從使用者程式碼中提取函式、危險模式、硬編碼密碼。**絕不使用 LLM 判斷** |
| **LLM 使用** | **零**。這是唯一完全不依賴 LLM 的 Agent |
| **設計依據** | Dual LLM Pattern (Simon Willison 2024) + OWASP LLM01:2025 |

### 核心函式：`extract_code_surface(code: str)`

**輸入**：使用者提交的原始程式碼（任何語言）  
**輸出**：結構化 JSON，包含：

```json
{
  "functions": ["eval", "exec", "os.system"],    // AST 提取的函式呼叫
  "patterns": [                                   // 正則匹配的危險模式
    {"type": "CMD_INJECTION", "cwe": "CWE-78", "severity": "CRITICAL", "snippet": "os.system(cmd)"}
  ],
  "hardcoded": [                                  // 硬編碼密碼/金鑰
    {"type": "HARDCODED_SECRET", "snippet": "api_key = 'sk-xxx'"}
  ],
  "language": "python",                           // 偵測到的語言
  "stats": {"loc": 150, "function_count": 12}
}
```

### 三層偵測架構

| 層級 | 機制 | 覆蓋範圍 |
|------|------|---------|
| **L0 通用正則** | `_DANGER_UNIVERSAL` | SQL Injection、CMD Injection、Path Traversal、XXE、Hardcoded Secret、**Log4Shell JNDI** |
| **L1 語言特化** | `_DANGER_LANG[language]` | Python: Pickle/YAML/Eval/SSRF/SSTI；JS: Prototype Pollution/innerHTML；Java: Deserialization；C#: Process.Start/SqlCommand/BinaryFormatter 等 |
| **L2 AST 分析** | Python `ast.parse()` | 精確函式呼叫提取（不被字串/註解干擾） |

### 支援語言（15 種）

Python、JavaScript、TypeScript、Java、C#、PHP、Ruby、Go、Rust、C/C++、Kotlin、Swift、Scala、Bash、SQL

### 關鍵設計決策

- **為何不用 LLM？** → 防 Prompt Injection。使用者程式碼可能包含 `# Ignore all previous instructions`，如果讓 LLM 分析程式碼，LLM 可能被注入。確定性正則不受此影響。
- **Word Boundary 修補** → `(?<!\w)` lookbehind 防止 `ecosystem` 誤觸 `system\s*\(` 模式。

---

## 3. Intel Fusion（六維情報融合師）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/intel_fusion.py` (792 行) |
| **本質** | **用 LLM 自主決策要查哪些情報源**，然後用**確定性公式**計算複合風險分數 |
| **LLM 使用** | 用於決定查詢順序和解析 API 回傳；**分數計算由程式碼執行** |
| **Tools** | search_nvd、search_osv、check_cisa_kev、search_otx、fetch_epss_score、query_ghsa、read/write_memory |

### 六維評分公式

```
composite_score = (cvss×0.20 + epss×0.30 + kev×0.25 + ghsa×0.10 + attck×0.10 + otx×0.05) × 10
```

| 維度 | 來源 | 權重 | 說明 |
|------|------|------|------|
| CVSS | NVD API | 20% | 理論嚴重性（0-10） |
| EPSS | FIRST.org | 30% | 30 天內被利用的機率（0-1） |
| KEV | CISA | 25% | 已確認在野利用（二元） |
| GHSA | GitHub Advisory | 10% | 生態系專屬告警 |
| ATT&CK | MITRE | 10% | 攻擊戰術分類 |
| OTX | AlienVault | 5% | IoC 威脅情報 |

### 動態加權規則（確定性程式碼）

| 條件 | 調整 |
|------|------|
| `in_kev == True` | EPSS 降至 0（KEV 已是最高事實）→ 權重轉給 KEV |
| `cve_year < 2020` | EPSS 降至 0.10（舊漏洞 EPSS 不準）→ 權重轉給 CVSS |
| `otx_fail_rate > 0.5` | OTX 降至 0.01 → 權重轉給 CVSS |
| `in_kev && composite < 8.0` | 強制拉到 8.0（KEV 品質紅線） |

### Harness 保障

- **Layer 2**：`_verify_and_recalculate()` — LLM 算出的分數與程式碼計算差 >1.5 → 用程式碼的
- **Layer 2.5**：CVE 年份過濾 — `< 2005` 的遠古 CVE 一律濾除

---

## 4. Scout（威脅情報偵察兵）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/scout.py` (794 行) |
| **本質** | **Pipeline 第一個 LLM Agent**。彙整 OSV/NVD 與 Layer 1 情報，產出最終 `vulnerabilities[]` 與 scan-scoped 結果 |
| **LLM 使用** | 使用 LLM 決定查詢順序、解析 API 回傳、合併 Intel Fusion 證據並組裝 JSON 報告 |
| **Tools** | search_osv（主力）、search_nvd（備用）、read/write_memory、history_search |

### 工作流程（SOP 6 步）

1. `read_memory("scout")` — 讀取歷史掃描記錄
2. 對每個套件呼叫 `search_osv()`（OSV.dev ecosystem-aware）→ 無結果則 fallback `search_nvd()`
3. 若 Layer 1 已提供 `intel_fusion_result`，優先重用其 EPSS / OTX / KEV / GHSA 富化證據，不重複查詢
4. 組裝 JSON 報告（CVE ID 必須來自 API，絕不可編造）
5. `write_memory("scout")` — 儲存本次結果
6. 輸出 Final Answer（純 JSON）

### Path-Aware Skill Map

| Path | Skill 檔案 | 用途 |
|------|-----------|------|
| A (pkg) | `threat_intel.md` | NVD CVE 掃描 |
| B (code) | `source_code_audit.md` | OWASP Top10 + CWE |
| B (injection) | `ai_security_audit.md` | OWASP LLM Top10 |
| C (config) | `config_audit.md` | CIS Benchmark |

### Harness 保障（5 層）

| 層 | 功能 |
|----|------|
| **0** | OSV Batch 預熱：LLM 啟動前批量查所有套件，結果預存快取 |
| **1** | 強制 write_memory：LLM 沒寫 → 程式碼代寫 |
| **2** | Schema 驗證：缺少必要欄位 → 自動補全 |
| **2.5** | Cache 注入：LLM 輸出 0 CVE → 從 OSV/NVD 快取注入 |
| **3** | CVE 驗證：幻覺偵測 — 每個 CVE ID 回 NVD 精確查詢，不存在 → 移除 |
| **3.5** | 年份過濾：`< 2005` 的 CVE 一律移除 |
| **4** | Package 補全：CVE 沒有 package 欄位 → 從 description 推斷 |
| **5** | is_new 校正：比對歷史記憶，修正 LLM 的 is_new 標記 |

---

## 5. Analyst（漏洞連鎖分析師）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/analyst.py` (1045 行) |
| **本質** | **深度分析 + 連鎖攻擊路徑推理**。接收 Scout 的 CVE 清單，驗證 KEV/Exploit 狀態，分析漏洞間的連鎖關係 |
| **LLM 使用** | 重度使用。連鎖攻擊分析需要 LLM 推理 |
| **Tools** | check_cisa_kev、search_exploits、read/write_memory、history_search |

### 3-Task 拆分架構（降低弱模型認知負荷）

| Sub-Agent | 職責 | 擁有的 Tool |
|-----------|------|------------|
| **Collector** | 讀歷史記憶 + 解析 Scout JSON | `read_memory` |
| **Verifier** | KEV 驗證 + Exploit 搜尋 + Chain 分析 | `check_cisa_kev`、`search_exploits` |
| **Scorer** | 計算風險分數 + 寫記憶 + 輸出 JSON | `write_memory` |

### 連鎖攻擊分析規則

| 條件 | 風險調整 |
|------|---------|
| in_kev + exploit + chain | → CRITICAL |
| in_kev + exploit | → CRITICAL |
| chain alone | → 至少維持原始嚴重度 |
| **規則**：風險只能**升高**，絕不能降低 | |

### 風險分數計算

```
risk_score = min(100, Σ(cvss_score × weight))
weight: CRITICAL=3, HIGH=2, MEDIUM=1, LOW=0.5
```

### Harness 保障

| 層 | 功能 |
|----|------|
| **1** | 強制 write_memory |
| **2** | Schema 驗證（scan_id/risk_score/analysis 必須存在） |
| **3** | chain_risk 邏輯驗證（is_chain=true → 必須有 chain_with + chain_description） |
| **3.5** | CVE 年份標記（`< 2005` → confidence=NEEDS_VERIFICATION） |
| **Fallback** | LLM 完全失敗 → 用 Scout 資料建最小可行報告 |

---

## 6. Critic（魔鬼代言人）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/critic.py` (388 行) |
| **本質** | **對抗性審查者**。質疑 Analyst 的每個判斷，驗證假設，輸出 5 維記分卡 |
| **LLM 使用** | 用於生成質疑論點、驗證邏輯 |
| **Tools** | check_cisa_kev、search_exploits、read_memory |
| **可關閉** | `ENABLE_CRITIC=false` → 完全跳過，輸出 SKIPPED |

### 5 維記分卡

| 維度 | 權重 | 說明 |
|------|------|------|
| evidence | 30% | 證據充分度 |
| chain_completeness | 25% | 連鎖分析完整度 |
| critique_quality | 20% | 質疑品質 |
| defense_quality | 15% | 辯護品質 |
| calibration | 10% | 校準準確度 |

### 裁決規則

| 加權分數 | 裁決 |
|---------|------|
| ≥ 70 | **MAINTAIN**（維持 Analyst 判斷） |
| 50–69 | **MAINTAIN**（附帶挑戰筆記） |
| < 50 | **DOWNGRADE**（降級風險評估） |

### 關鍵限制

- **禁止降級 KEV 命中的 CVE**（in_cisa_kev=true → 不可 DOWNGRADE）
- 必須至少呼叫一個 Tool 才能下結論

---

## 7. Debate Engine（辯論引擎）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/debate_engine.py` (478 行) |
| **本質** | **多 Agent 辯論協調器**。讓 Analyst 和 Critic 進行最多 3 輪辯論，無共識時由 Judge 仲裁 |
| **論文依據** | Du et al. (2023) "Improving Factuality and Reasoning in LLMs through Multiagent Debate" (ICML 2023) |

### 辯論流程

```
Round 1: Analyst 提出初始立場 → Critic 質疑
Round 2: Analyst 更新立場（含 Critic 反饋）→ Critic 再評
Round 3: Analyst 最終立場 → Critic 最終評判
         ↓ 若 3 輪後仍無共識
Final:   Judge sub-agent 仲裁（獨立第三方）
```

### 共識判定

- Critic verdict = MAINTAIN → **直接共識**
- Critic verdict = DOWNGRADE 但 score ≥ 80 → **共識**（Analyst 立場強）
- 其他 → **繼續辯論**

### Judge Sub-Agent

- 獨立第三方，不是 Analyst 也不是 Critic
- 閱讀完整辯論紀錄，選擇最有邏輯支持的立場
- **安全性偏保守原則**：證據相當時，選更嚴重的評級

---

## 8. Advisor（資安顧問 / 最終裁決者）

| 項目 | 說明 |
|------|------|
| **檔案** | `agents/advisor.py` (812 行) |
| **本質** | **Pipeline 終點站**。接收所有前序 Agent 的分析結果，產出面向管理者的可執行行動報告 |
| **LLM 使用** | 使用 LLM 生成修補建議和 executive summary |
| **Tools** | read_memory、write_memory、history_search |

### 輸出格式（Advisor → UI 資料契約）

```json
{
  "executive_summary": "一句話風險摘要",
  "actions": {
    "urgent": [{"cve_id": "...", "command": "pip install --upgrade xxx", ...}],
    "important": [{"cve_id": "...", "action": "...", ...}],
    "resolved": []
  },
  "risk_score": 85,
  "risk_trend": "+12",
  "code_patterns_summary": [...]
}
```

### 三級分類規則

| 級別 | 條件 |
|------|------|
| **URGENT** | CVSS ≥ 9.0 或 in_cisa_kev=true 或有公開 PoC |
| **IMPORTANT** | CVSS ≥ 7.0 或有攻擊鏈風險 |
| **不列入** | MEDIUM/LOW 且無利用跡象 |

### Harness 保障（6.5 層）

| 層 | 功能 |
|----|------|
| **1** | LLM 輸出無法解析 → Fallback 最小可行報告 |
| **2** | Schema 驗證（executive_summary/actions/risk_score 必須存在） |
| **3** | risk_score 範圍驗證（強制 0-100） |
| **4** | URGENT 項目必須有 command（沒有 → 自動補 `pip install --upgrade`） |
| **5** | 歷史比對：重複未修補 CVE → `[REPEATED — STILL NOT PATCHED]` 語氣升級 |
| **6** | 憲法守衛：CODE-pattern（無真實 CVE ID）從 URGENT/IMPORTANT 移至 `code_patterns_summary` |
| **6.5** | CWE 佐證注入：為每個 code pattern 加入 MITRE CWE 官方定義、CVSS、代表性 CVE |

---

## Agent 間的資料契約總表

| 上游 | 下游 | 傳遞的 JSON 欄位 |
|------|------|-----------------|
| Orchestrator | 全部 | `scan_path`, `agents_to_run`, `shortcuts` |
| Security Guard | Scout/Analyst | `functions[]`, `patterns[]`, `hardcoded[]`, `language` |
| Intel Fusion | Scout | `fusion_results[]`, `composite_score`, `kev_hits` |
| Scout | Analyst | `vulnerabilities[]`, `code_patterns[]`, `summary` |
| Analyst | Critic/Debate | `analysis[]`, `risk_score`, `risk_trend` |
| Critic | Debate Engine | `scorecard`, `weighted_score`, `verdict`, `challenges[]` |
| Debate Engine | Advisor | 最終裁決 + `_debate_meta` |
| Advisor | UI | `executive_summary`, `actions{urgent/important/resolved}`, `risk_score` |

---

## 共通機制

### 429 自動輪替（所有 LLM Agent 共用）

```python
for attempt in range(MAX_LLM_RETRIES + 1):
    agent = create_xxx_agent(excluded_models)
    try:
        result = crew.kickoff()
        break
    except Exception as e:
        if "429" in str(e):
            mark_model_failed(current_model)
            excluded_models.append(current_model)
            rate_limiter.on_429(retry_after=...)
            continue
        raise
```

### Graceful Degradation（所有 Agent 共用）

每個 Agent 都有 `_build_fallback_output()` — LLM 完全失敗時，用前序 Agent 的資料建最小可行報告，確保 Pipeline 不中斷。

### CVE 年份過濾（三道防線）

| 位置 | 機制 |
|------|------|
| Scout Harness 3.5 | `< 2005` 的 CVE 從 vulnerabilities 移除 |
| Intel Fusion Harness 2.5 | `< 2005` 的 CVE 從 fusion_results 移除 |
| Advisor Harness 6 | `< 2005` 的 CVE 從 urgent/important 移除 |

---

*本文件僅供團隊內部參考，不需上傳至 Git。*