> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 三層式 AI 漏斗

> Panguard 怎麼用級聯式架構在 1ms 內處理 90% 的安全事件 -- 規則、本地 AI、雲端 AI 三層搞定。

# 三層式 AI 漏斗

Panguard AI 用三層級聯架構分析安全事件。90% 的事件由規則引擎在 1ms 內搞定，只有最難搞的 3% 才會丟到雲端 AI。

## 為什麼要三層？

把每個安全事件都丟給 AI 模型會出三個問題：

1. **太慢** -- AI 推論要好幾秒，攻擊可不會等你。
2. **太貴** -- 每台機器每天幾千個事件，token 費用會失控。
3. **不可靠** -- API 一掛，防護就停擺。

三層漏斗的原則很簡單：**大部分攻擊都是已知 pattern。只有真正未知的威脅才需要 AI 深度推理。**

***

## 架構概覽

```
  Security Events
       |
       v
  +-----------+
  | Layer 1   |  ATR Rule Engine
  | 90% events|  Latency < 1ms | Cost = $0
  +-----------+
       |
    Unmatched (10%)
       |
       v
  +-----------+
  | Layer 2   |  Local AI (Ollama)
  | 7% events |  Latency < 5s  | Cost = $0 (on-device)
  +-----------+
       |
    Needs deeper analysis (3%)
       |
       v
  +-----------+
  | Layer 3   |  Cloud AI (Claude / OpenAI)
  | 3% events |  Latency < 30s | Cost ~ $0.01/event
  +-----------+
```

***

## 各層比較

| 屬性        | Layer 1：規則   | Layer 2：本地 AI   | Layer 3：雲端 AI   |
| --------- | ------------ | --------------- | --------------- |
| **事件佔比**  | \~90%        | \~7%            | \~3%            |
| **延遲**    | \< 1 ms      | \< 5 s          | \< 30 s         |
| **每事件成本** | \$0          | \$0             | \~\$0.01        |
| **需要網路**  | 否            | 否               | 是               |
| **技術**    | ATR 規則       | Ollama (llama3) | Claude / OpenAI |
| **最適合**   | 已知攻擊 pattern | 行為異常            | 新型複雜威脅          |

***

<h2 id="layer-1">
  Layer 1 -- 規則引擎 (90%)
</h2>

零延遲、零成本，處理所有已知攻擊 pattern。

### ATR 規則

ATR (Agent Threat Rules) 是 AI agent 威脅偵測的開放標準。Panguard Guard 內建 768 條 ATR 規則，涵蓋常見 AI agent 攻擊 pattern。

```yaml ATR Rule Example theme={null}
id: ATR-2025-0001
name: Prompt Injection via Tool Response
severity: critical
detection:
  patterns:
    - 'ignore previous instructions'
    - 'system prompt override'
  context: tool_response
action: block
```

**支援的 ATR 功能：**

* Regex pattern matching
* 情境感知偵測（tool 回應、skill manifest、agent 動作）
* 多層偵測：regex、內容指紋、LLM-as-judge
* 嚴重等級：critical、high、medium、low
* AI agent 威脅的 MITRE ATT\&CK 對應

***

<h2 id="layer-2">
  Layer 2 -- 本地 AI (7%)
</h2>

事件沒命中任何規則但看起來可疑時，丟給本地 AI 分析。

* 透過 [Ollama](https://ollama.ai) 本地跑 -- 不需要網路
* 零 API 成本
* 推論延遲約 3-5 秒
* 預設模型：`llama3`

<Info>
  **環境感知路由：** 在 server（VPS、雲端主機）上，事件跑全部三層。在桌機和筆電上，Layer 2
  會被跳過，避免搶使用者資源。未命中的事件直接從 Layer 1 跳到 Layer 3。
</Info>

```
Server:  Layer 1 (90%) -> Layer 2 (7%) -> Layer 3 (3%)
Desktop: Layer 1 (90%) -> Layer 3 (5-8%)  (Layer 2 skipped)
```

***

<h2 id="layer-3">
  Layer 3 -- 雲端 AI (3%)
</h2>

最複雜的未知威脅交給雲端 AI 做完整的動態推理。

* 完整上下文分析
* 跨事件關聯分析
* MITRE ATT\&CK 分類的攻擊鏈推理
* 自動產生修復建議

<Note>就算雲端 AI 掛了（斷網、token 用完），Layer 1 規則引擎照跑。**防護永遠不會停。**</Note>

***

## 優雅降級

三層架構的關鍵設計：任何一層掛掉，上一層自動接手。

| 情境        | 降級行為             |
| --------- | ---------------- |
| 雲端 AI 不可用 | Layer 2（本地 AI）接手 |
| 沒裝 Ollama | Layer 1（規則引擎）接手  |
| 規則檔損壞     | 內建預設規則啟動         |

**Panguard 永遠有防護 -- 只有精準度會變。**

### 依可用來源調整信心度權重

系統根據可用的偵測來源，動態調整每種證據的權重：

| 可用來源           | 規則/情報 | 基線   | 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 |

***

## FunnelRouter

`@panguard-ai/core` 裡的 `FunnelRouter` 元件負責 Layer 2 到 Layer 3 的降級邏輯：

<Steps>
  <Step title="先試本地 AI">把事件丟給 Ollama 做本地分析。</Step>
  <Step title="評估信心度">Ollama 回傳高信心度就採用。Ollama 不可用或信心度太低就往上丟。</Step>
  <Step title="降級到雲端 AI">丟給 Claude 或 OpenAI 做深度推理和 MITRE 分類。</Step>

  <Step title="最終降級">
    所有 AI 都不可用的話，系統改用純規則評分（權重變成 0.6 規則 + 0.4 基線）。
  </Step>
</Steps>

**Provider 自動偵測**（啟動時）：

1. 檢查 `~/.panguard/llm.enc`（加密本地設定，AES-256-GCM）
2. 檢查環境變數：`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`
3. 探測本地 Ollama `http://localhost:11434`
4. 建構對應的 adapter：FunnelRouter（都有）、單一 provider、或 null

***

## 相關內容

<CardGroup cols={2}>
  <Card title="學習模式" icon="graduation-cap" href="/concepts/learning-mode">
    Guard 怎麼在 7 天學習期建立行為基線。
  </Card>

  <Card title="即時防護" icon="shield" href="/guides/real-time-protection">
    設定 Guard 做持續監控和自動回應。
  </Card>
</CardGroup>