---
title: 'Agent Pipeline（DARE）'
description: '4-agent Detect-Analyze-Respond-Report pipeline 的完整拆解。'
icon: 'arrow-right-arrow-left'
---

Guard 引擎把每個安全事件送進一條線性的 4-agent 鏈，叫做 DARE pipeline：**Detect**、**Analyze**、**Respond**、**Report**。每個 agent 只做一件事，產出有型別的輸出給下一個 agent 吃。

## Pipeline 流程

```
SecurityEvent
     |
     v
[DetectAgent] ──> DetectionResult | null
     |
     v
[AnalyzeAgent] ──> ThreatVerdict
     |
     v
[RespondAgent] ──> ResponseResult
     |
     v
[ReportAgent] ──> Updated baseline + anonymized data
```

如果 DetectAgent 回傳 `null`（沒有規則命中、沒有威脅情報 hit），這個事件就被當良性跳過。不然的話，完整 pipeline 會跑下去。

---

## DetectAgent

**原始碼**：`packages/panguard-guard/src/agent/detect-agent.ts`

| 欄位     | 值                          |
| -------- | --------------------------- |
| **輸入** | `SecurityEvent`             |
| **輸出** | `DetectionResult` 或 `null` |

### 做什麼

1. **ATR 規則比對** -- 透過 `RuleEngine` 拿事件去跑所有已載入的規則
2. **威脅情報查詢** -- 比對來源/目的 IP 是否在 5 個 feed 和 Threat Cloud blocklist 裡（IPv4 + IPv6 都支援）
3. **去重** -- 60 秒內相同的偵測直接跳過（dedup map 最多 500 筆）
4. **事件關聯** -- 包括傳統 IP-based 關聯（5 分鐘內同一來源 IP 3+ 事件）和進階 pattern-based 關聯（透過 `EventCorrelator`，7 種攻擊 pattern）

### 內部狀態

| Buffer      | 容量       | 時間窗口 |
| ----------- | ---------- | -------- |
| 關聯 buffer | 1,000 事件 | 5 分鐘   |
| Dedup map   | 500 筆     | 60 秒    |

---

## AnalyzeAgent

**原始碼**：`packages/panguard-guard/src/agent/analyze-agent.ts`

| 欄位     | 值                                                       |
| -------- | -------------------------------------------------------- |
| **輸入** | `DetectionResult` + `EnvironmentBaseline`                |
| **輸出** | `ThreatVerdict`（結論：benign / suspicious / malicious） |

### 證據來源與權重

AnalyzeAgent 從多個來源蒐證，算出加權信心分數（0--100）：

| 來源          | 權重       | 備註                            |
| ------------- | ---------- | ------------------------------- |
| ATR 規則命中  | 0.40       | 會被 feedback loop 調整         |
| 威脅情報      | --         | 命中時固定信心 85               |
| Baseline 偏差 | 0.30       | 有時段感知（00:00--05:59 加成） |
| eBPF/DPI 證據 | 0.20--0.25 | kernel 層 monitor 啟用時才有    |
| 攻擊鏈關聯    | +5/事件    | 最高 +25                        |
| AI 分析       | 0.30       | AI provider 可用時              |

權重會根據可用來源自動調配：

| 可用來源         | 規則/情報 | Baseline | AI   | eBPF |
| ---------------- | --------- | -------- | ---- | ---- |
| 只有規則         | 0.60      | 0.40     | --   | --   |
| 規則 + AI        | 0.40      | 0.30     | 0.30 | --   |
| 規則 + eBPF      | 0.40      | 0.35     | --   | 0.25 |
| 規則 + AI + eBPF | 0.30      | 0.20     | 0.30 | 0.20 |

### Feedback Loop

AnalyzeAgent 維護每條規則的 feedback 紀錄：

- **誤報率高** -- 信心值最多降 30%
- **真陽性率高** -- 信心值最多升 10%

### 矛盾偵測

如果高嚴重度規則觸發了，但 baseline 沒有偏差，信心值會被扣 10 分。這樣就不會對「符合規則 pattern 但在這個環境其實是正常」的事件過度警報。

---

## RespondAgent

**原始碼**：`packages/panguard-guard/src/agent/respond-agent.ts`

| 欄位     | 值               |
| -------- | ---------------- |
| **輸入** | `ThreatVerdict`  |
| **輸出** | `ResponseResult` |

### 信心分數對應的動作

| 信心值  | 做什麼                           |
| ------- | -------------------------------- |
| >= 90%  | 自動執行，事後通知               |
| 70--90% | 發確認請求到通知頻道，等人工核准 |
| < 70%   | 只通知，不動作                   |

### 可用動作

| 動作              | 說明                  | 平台                                             |
| ----------------- | --------------------- | ------------------------------------------------ |
| `block_ip`        | 在防火牆層封鎖來源 IP | macOS (pfctl)、Linux (iptables)、Windows (netsh) |
| `kill_process`    | 砍掉惡意 process      | 全平台（先 SIGTERM，5 秒後 SIGKILL）             |
| `isolate_file`    | 隔離可疑檔案          | 全平台                                           |
| `disable_account` | 鎖定帳戶              | 全平台                                           |
| `notify`          | 發警報到通知頻道      | 全平台                                           |
| `log_only`        | 只記 log 不動作       | 全平台                                           |

安全規則和 escalation 細節請看[自動回應](/products/guard/auto-response)。

---

## ReportAgent

**原始碼**：`packages/panguard-guard/src/agent/report-agent.ts`

| 欄位     | 值                                                                           |
| -------- | ---------------------------------------------------------------------------- |
| **輸入** | `SecurityEvent` + `ThreatVerdict` + `ResponseResult` + `EnvironmentBaseline` |
| **輸出** | 更新的 baseline + 匿名化威脅資料（選擇性）                                   |

### 做什麼

1. **JSONL Log** -- 寫完整事件記錄，搭配 log rotation（每檔 50 MB、10 個 rotation、90 天保留）
2. **Baseline 更新** -- 學習模式期間持續用觀察到的 pattern 更新行為 baseline
3. **匿名化** -- IP 做 /16 匿名（最後兩個 octet 歸零）再上傳 Threat Cloud
4. **摘要產出** -- 每日（24h）和每週（7d）摘要，包含主要攻擊來源、動作統計、verdict 分佈

### Log 格式

每筆 log 是一行 JSON：

```json
{
  "timestamp": "2025-01-15T14:23:01.000Z",
  "event": { "type": "network", "sourceIp": "203.0.113.50" },
  "verdict": { "conclusion": "malicious", "confidence": 95 },
  "response": { "action": "block_ip", "success": true },
  "baseline": { "deviation": true, "score": 0.85 }
}
```
