> ## 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.

# 系統架構

> Panguard AI 的技術架構：monorepo 結構、部署層級、元件互動。

# 系統架構

Panguard AI 是一個 TypeScript monorepo，18 個 package 分成三個部署層級。每個元件 -- 從你筆電上的 CLI 到資料中心的 Threat Cloud -- 都共用同一個 `@panguard-ai/core` 基礎。

***

## 三個部署層級

```
  +-------------------------------------------------------+
  |                    Cloud Layer                         |
  |   Threat Cloud (collective intelligence)              |
  |   Cloud AI (Claude / OpenAI)                          |
  |   Web Dashboard                                       |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                   Manager Layer                        |
  |   Fleet orchestration, policy management              |
  |   Agent registration, centralized logging             |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                  Endpoint Layer                        |
  |   Guard agent (real-time protection)                  |
  |   Scan, CLI tools                                     |
  +-------------------------------------------------------+
```

<Tabs>
  <Tab title="Endpoint 層">
    Guard agent 和 CLI 工具直接跑在受保護的機器上。安全事件在這裡被偵測、由 Layer 1 和 Layer 2 AI 分析、即時回應。

    **主要元件：**

    * Guard agent（持續監控）
    * Scan 引擎（按需稽核）
    * 通知系統（Telegram、Slack、Email、LINE、Webhook）
    * Trap 蜜罐（8 種誘餌服務）
    * Report 產生器（PDF、JSON）
    * 本地 AI（Ollama，Layer 2）

    **完全離線運作。** Endpoint 層用 cache 的規則和本地 AI，不需要網路。
  </Tab>

  <Tab title="Manager 層">
    Manager 負責跨機群編排多台機器上的 Guard agent。提供集中式策略管理、agent 註冊、彙總 log。

    **主要功能：**

    * 機群策略部署
    * Agent 健康監控和註冊
    * 集中式 log 彙總
    * WebSocket 即時 dashboard
    * REST API 做程式化控制

    **部署：** 自架在你的基礎設施上。完全免費開源。
  </Tab>

  <Tab title="Cloud 層">
    Cloud 層提供集體情報和深度 AI 分析，處理本地搞不定的威脅。

    **主要服務：**

    * Threat Cloud（社群驅動的 IoC 資料庫）
    * 雲端 AI 分析（Claude / OpenAI，Layer 3）
    * Web dashboard

    **可選的。** Cloud 層加強防護但不是必要的。所有核心功能不需要它就能跑。
  </Tab>
</Tabs>

***

## 13-Package Monorepo

程式碼用 pnpm workspace monorepo 組織，每個 package 負責一件事：

| Package                        | 層級       | 用途                           |
| ------------------------------ | -------- | ---------------------------- |
| `@panguard-ai/core`            | 共用       | 規則引擎、監控器、AI provider、i18n、加密 |
| `@panguard-ai/panguard`        | Endpoint | CLI 入口（`panguard` 指令）        |
| `@panguard-ai/panguard-guard`  | Endpoint | 即時防護 agent（5 階段 AI pipeline） |
| `@panguard-ai/panguard-scan`   | Endpoint | 安全掃描器和風險評分                   |
| `@panguard-ai/panguard-chat`   | Endpoint | 通知系統（5 個頻道、3 種角色格式）          |
| `@panguard-ai/panguard-trap`   | Endpoint | 蜜罐系統（8 種服務類型）                |
| `@panguard-ai/panguard-report` | Endpoint | 合規報告（TCSA、ISO 27001、SOC 2）   |
| `@panguard-ai/threat-cloud`    | Cloud    | 集體情報 API server              |
| `@panguard-ai/website`         | Cloud    | 行銷網站 (panguard.ai)           |

***

## @panguard-ai/core -- 共用基礎

`core` package 是所有其他 package 的基礎，提供：

<AccordionGroup>
  <Accordion title="規則引擎">
    * ATR 規則 parser 和 evaluator（pattern matching、情境感知偵測、多層分析）
    * 768 條內建 ATR 規則，支援自訂規則載入
  </Accordion>

  <Accordion title="監控器">
    4 個系統監控器收集安全相關事件： - **Log 監控器** -- 系統 log 解析（syslog、journald、Windows
    Event Log） - **Network 監控器** -- 連線追蹤、port scan、DNS 查詢 - **Process 監控器** --
    行程建立、終止、資源用量 - **File 監控器** -- 檔案系統變更、權限修改、新的 binary
  </Accordion>

  <Accordion title="AI Provider">
    * FunnelRouter 做 Layer 2/3 級聯 - Ollama adapter（本地 AI） - Claude 和 OpenAI adapter（雲端 AI）
    * 啟動時自動偵測 provider - AES-256-GCM 加密 key 儲存（`~/.panguard/llm.enc`）
  </Accordion>

  <Accordion title="i18n">
    * 英文和繁體中文 - 所有 CLI 輸出、報告、通知都完整在地化 - 用 `panguard init` 或 `--lang` flag
      選語言
  </Accordion>

  <Accordion title="系統偵察">
    * OS 偵測（macOS、Linux、Windows）
    * 網路介面列舉
    * 執行中服務清單
    * 安全工具偵測（防毒、EDR、IDS）
    * 硬體識別碼收集，用於加密 key 衍生
  </Accordion>
</AccordionGroup>

***

## Tech Stack

| 技術                 | 版本     | 用途                             |
| ------------------ | ------ | ------------------------------ |
| **TypeScript**     | 5.7    | 所有 package 的主要語言               |
| **Node.js**        | 22     | Runtime                        |
| **pnpm**           | 9+     | Workspace-aware 套件管理器          |
| **Vitest**         | Latest | 單元和整合測試                        |
| **esbuild**        | Latest | CLI 發布的快速 bundler              |
| **better-sqlite3** | Latest | Threat Cloud 和 Guard 狀態的嵌入式 DB |
| **Next.js**        | 14     | Web dashboard 和行銷網站            |

***

## 跨平台支援

Panguard 跑在三大 OS 上：

| 平台                     | Guard | Scan | Trap | Manager |
| ---------------------- | ----- | ---- | ---- | ------- |
| **macOS** (ARM64, x64) | Yes   | Yes  | Yes  | Yes     |
| **Linux** (x64, ARM64) | Yes   | Yes  | Yes  | Yes     |
| **Windows** (x64)      | Yes   | Yes  | Yes  | Yes     |

平台特定實作在 `core` 裡透過 interface 抽象化：

* **防火牆：** macOS `pfctl`、Linux `iptables`/`nftables`、Windows `netsh`
* **服務管理：** macOS `launchd`、Linux `systemd`、Windows Services
* **Log 來源：** macOS unified log、Linux `journald`/syslog、Windows Event Log

***

## 資料流

一個典型的安全事件在系統裡的流程：

<Steps>
  <Step title="偵測事件">
    `core` 裡的監控器（process、network、file、log）在 endpoint 偵測到安全相關事件。
  </Step>

  <Step title="Layer 1 評估">
    ATR 規則引擎在 1ms 內評估事件。規則命中的話，事件馬上被分類並觸發回應。
  </Step>

  <Step title="AI 升級（如果需要）">
    沒命中的事件透過 FunnelRouter 丟給 Layer 2（本地 Ollama）或 Layer 3（雲端 AI）做深度分析。
  </Step>

  <Step title="執行回應">
    依分類和信心度，自動回應引擎採取行動：封鎖 IP、隔離檔案、kill 行程、或只通知。
  </Step>

  <Step title="報告和通知">
    透過設定的頻道發通知。事件記錄進 Guard 狀態、安全分數更新、合規報告。
  </Step>

  <Step title="Threat Cloud 上傳（可選）">
    有開 Threat Cloud 的話，匿名化的指標會上傳，貢獻給社群。
  </Step>
</Steps>

***

## 相關內容

<CardGroup cols={3}>
  <Card title="三層式 AI" icon="brain-circuit" href="/concepts/three-layer-ai">
    規則、本地 AI、雲端 AI 漏斗的深入說明。
  </Card>

  <Card title="Guard Pipeline" icon="shield" href="/products/guard/agent-pipeline">
    Guard 裡面的 5 階段 AI agent pipeline。
  </Card>

  <Card title="Manager" icon="server" href="/products/guard/overview">
    機群編排和集中式管理。
  </Card>
</CardGroup>