十、選配功能的設定¶

這章在講什麼：七項「要用才設定」的附加功能怎麼開。

系統的核心功能（專案、稽核、證據、報告）安裝完、開通完就能用，不需要看這一章。本章這七項是選配：需要就照著設定，不需要就完全不用管，不設定不會影響其他任何功能。

什麼時候看：想開 AI 功能、想接 Google 雲端硬碟、想讓系統會寄信、想對貴單位主機做組態檢測、想把系統紀錄送進貴單位的 log 平台、想更新第三方元件風險用的弱點資料的時候。查下面那張表找到對應小節即可，不必整章讀完。

功能	需要什麼	封閉網路可用？
10.1 AI 功能	原廠提供的 API 金鑰	❌ 需連外網
10.2 Google 雲端硬碟整合	原廠提供的憑證	❌ 需連外網
10.3 GCB 檢測內容	出廠已內建，免設定	✅ 可用
10.4 寄信設定	貴單位的郵件伺服器	✅ 可用（內網郵件伺服器）
10.5 檢測 Agent	在被檢測主機安裝 Agent；系統這一側免設定	✅ 可用（連的是貴單位內網主機）
10.6 Log 轉發	貴單位自有的 log 伺服器（rsyslog／Graylog／ELK）	✅ 可用（連的是貴單位內網主機）
10.7 弱點資料更新	原廠更新包（封閉網路）或更新站位址（連網）	✅ 可用（上傳更新包）

封閉網路 指的是這台機器完全連不到網際網路，只在貴單位內部網路裡。表格最後一欄就是在說：這項功能在那種環境下能不能用。

10.1 AI 功能¶

系統的 AI 助理與證據自動分類，需要一把外部 AI 服務的 API 金鑰才能運作。

API 金鑰 是呼叫外部服務時用的一組通行密碼。它同時也是計費憑證——外部服務靠它認人、也靠它算錢，所以外流等於別人可以拿去用、帳算在貴單位頭上。

🔴 金鑰不隨出貨包提供。 出貨包內不含任何金鑰——這是刻意的設計（金鑰一旦進了出貨包，就等於散佈給所有拿到出貨包的人）。金鑰在交付時或裝機後由原廠另行提供給貴單位。

設定步驟¶

向原廠索取 API 金鑰。
編輯設定檔（這一步在做什麼：打開系統的設定檔準備加一行）：

sudo vi /srv/guidant-ai/guidant.env

加入一行（把 <金鑰> 換成原廠提供的值）：

ANTHROPIC_API_KEY=<金鑰>

套用設定（這一步在做什麼：讓剛才加的那一行生效）：

sudo guidantai start

🔴 這裡要用 start，不是 restart。設定值是在容器「建立」的那一刻寫進去的，restart 沒有重建容器，讀到的還是舊值——而且不會有任何錯誤訊息，看起來一切正常。詳見 4.3。（真的誤打了也不要緊：guidantai restart 會偵測到設定比容器新並擋下來。）

成功長什麼樣：重啟後 guidant-api 健康，AI 相關功能可正常回應。

注意事項¶

⚠️ 未設定金鑰時，AI 功能的入口仍然存在。AI 助理會回「尚未設定 AI 服務，此功能暫時無法使用」，其他 AI 功能會回報錯誤——這不代表系統壞了。請告知使用者：未購買／未設定 AI 功能時不要使用該入口。
這項功能需要主機能連上 api.anthropic.com（見第八章）。完全封閉的網路無法使用。
🔴 金鑰是計費憑證，請比照密碼保管。guidant.env 的權限維持 600、納入備份，勿散佈。
升級或重跑安裝不會覆寫您手動加進 guidant.env 的內容。
🔴 guidant.env 裡的 AI_PROVIDER_ENCRYPTION_KEY 不可刪、不可改。這是加密存放 AI 金鑰用的鑰匙，由安裝程式自動產生；缺了或格式不對時，guidant-api 與 guidant-worker 會拒絕啟動，記錄裡印出「AI 相關必要設定缺 N 項」並逐項列出。遺失這把鑰匙，後台「AI 服務設定」已存的金鑰就永遠解不開——請與 guidant.env 一起納入備份。
送給 AI 之前，系統會先遮蔽機敏資料、擋下不該送出的內容；守門規則放在 /srv/guidant-ai/ai-gateway-rules/，可現場調整，見 4.12。每一次 AI 呼叫的用量與處置都記在系統畫面「系統設定 › AI 用量」，額度上限在「系統設定 › AI 額度」。

10.2 Google 雲端硬碟整合¶

這項功能在做什麼：讓系統自動從貴單位的 Google 雲端硬碟資料夾，把證據檔案同步進系統，不必人工一個個上傳。

需要四項應用程式憑證，由原廠提供（目前使用原廠的應用程式憑證，未來會替換為正式版本；替換時原廠會通知）。這四項改在畫面上設定，不再改設定檔：

前置：在 Google 取得這組應用程式憑證¶

若貴單位要用自己的 Google 應用程式帳號（而非原廠提供的那一組），先在 Google 這一側建立，再把取得的值填回系統。全程在 Google Cloud Console 操作，需要一個 Google 帳號。

應用程式憑證是「本系統」在 Google 那邊的身分證，與「哪一個 Google 帳號的雲端硬碟要被存取」是兩回事——後者是每位使用者稍後各自授權的。

建立一個專案（Google Cloud Console 左上角專案選單 →「新增專案」）。已有專案可直接沿用。
啟用 Google Drive API（左側選單「API 和服務」→「程式庫」→ 搜尋 Google Drive API → 按「啟用」）。
設定 OAuth 同意畫面（「API 和服務」→「OAuth 同意畫面」），依畫面填寫應用程式名稱與聯絡信箱。

🔴 同意畫面若停在「測試中」狀態，必須把要授權的每個 Google 帳號加進「測試使用者」清單。沒加進去的帳號按授權時會被 Google 直接擋下。
建立憑證（「API 和服務」→「憑證」→「建立憑證」→「OAuth 用戶端 ID」），應用程式類型選「網頁應用程式」。
把系統畫面上算好的回呼網址貼進 Google 的「已授權的重新導向 URI」。那串網址在系統的「Google Drive 應用程式設定」頁上，是一個唯讀欄位、旁邊有複製鈕——請用複製鈕，不要手打。

🔴 兩邊必須逐字一模一樣（含通訊協定 https://、埠號、結尾有沒有斜線），差一個字元就不會過。 ⚠️ 在 Google 登記後通常要等幾分鐘才生效。這段期間去按授權會看到 redirect_uri_mismatch，那是正常的，等一下再試，不是設定錯了。
建立完成後，複製「用戶端 ID」與「用戶端密鑰」，回到系統畫面填入。

🔴 用戶端密鑰只在建立當下顯示一次，關掉視窗就看不到了。若已遺失，回到同一個用戶端的頁面按「新增密鑰」重建一組即可（舊的確認新的可用後再刪）。

填入系統¶

備妥四項值（用原廠提供的那一組，或上一節自行建立的）。
登入系統（平台管理員帳號）→ 側邊選單「系統設定」→「Google Drive 應用程式設定」→ 填入四項值 → 儲存。
登入系統（一般租戶管理員即可）→ 選單「系統管理」→「雲端空間整合」→ 依畫面指示完成授權。

OAuth 授權 是「讓系統代您去存取另一個服務」的標準授權流程：您在 Google 的畫面上按同意，Google 就發一張通行證給系統，系統日後拿這張通行證去讀資料夾，全程不需要、也拿不到您的 Google 密碼。第 3 步做的就是這件事。

成功長什麼樣：第 2 步存檔後，第 3 步的「連接 Google Drive」按鈕可以按下去（未設定前是停用狀態並顯示提示文字）；授權流程走完後回到系統畫面，該頁顯示已連結；之後系統就會自動同步指定資料夾的檔案。

注意事項¶

🔴 站台網址欄位必須與貴單位實際的站台網址一致（含通訊協定與埠），否則授權會被 Google 拒絕。
🔴 授權時必須從設定頁填的「系統對外網址」開啟本系統。Google 只會把授權結果送回那個網址；從別的網址（例如直接打 IP）開系統去按授權，系統會先跳出提示請您改用正確網址。
🔴 guidant.env 裡的 FRONTEND_BASE_URL 必須是使用者實際開系統的網址——對外用網域就填網域，不要留安裝時的 IP。它是設定頁未填對外網址時的後備值，填錯的症狀是「授權其實成功、畫面卻顯示連線失敗，重新整理後才看到已連線」。
授權完成後，系統會把存取權杖加密存進資料庫，加密金鑰在 guidant.env 內（DRIVE_TOKEN_ENCRYPTION_KEY，這一項不在畫面上、仍留在設定檔——密文與鑰匙必須分開放）。該檔遺失 = 既有授權永遠解不開，必須重新授權（見第四章 4.7）。
需要連外網（googleapis.com 等）。封閉網路不啟用即可，不影響其他功能。

10.3 政府組態基準（GCB）檢測內容¶

這項功能在做什麼：系統可以檢查一台主機的設定有沒有符合安全規範。判斷依據就叫檢測基準（也稱 profile）——一份「這台機器該符合哪些設定」的檢查清單。

系統出廠就已內建 10 套檢測基準，安裝完成後直接可用，不需要任何匯入步驟：

政府組態基準（TWGCB）8 套：Windows Server 2016／2019／2022、Windows 11、Red Hat Enterprise Linux 8／9（兩版）、Ubuntu 22.04 LTS
dev-sec 公開範例 2 套：Linux 基準、Windows 基準

上面列的是被檢測的目標作業系統，也就是這些基準各自適用於哪一種機器，與 Guidant AI 本身裝在哪裡無關。

確認方式¶

以管理員身分登入 → 選單「合規與稽核」→「掃描設定檔管理」，應看到上述 10 套設定檔，狀態皆為可用；建立檢測任務時，「檢測 Profile 位置」下拉選單也會直接列出它們。

每套基準的控制項數與版本可在該頁查看，也可下載原始基準檔留存。

進階：自行上傳新的基準檔¶

若貴單位需要匯入自有的或更新版的基準檔（.tar.gz），系統支援在「掃描設定檔管理」頁自行上傳。

但請注意：上傳新檔需要主機端具備 CINC Auditor 解析工具。出廠映像檔為了縮減體積並未內含（內建的 10 套基準已在出廠前解析完成，故不受影響）。若需要此功能，請依下列步驟為主機加掛：

在宿主主機安裝 CINC Auditor（自 cinc.sh 取得對應作業系統的套件）。
在部署目錄建立（或編輯）docker-compose.override.yml，為後端服務加上唯讀掛載——這段設定在做什麼：把主機上剛裝好的 CINC Auditor 目錄接進容器裡，讓容器內的程式讀得到（:ro 代表唯讀，容器只能讀不能改）：

services:
  guidant-api:
    volumes:
      - /opt/cinc-auditor:/opt/cinc-auditor:ro

重新啟動後端服務（讓上面的掛載生效）：docker compose up -d guidant-api

成功長什麼樣：重啟後回「掃描設定檔管理」頁上傳基準檔，能成功解析並出現在清單裡。

掛載路徑固定為 /opt/cinc-auditor——系統的解析器原生就會搜尋此路徑，不需要另外設定環境變數。

未加掛 CINC 時，內建的 10 套基準完全不受影響（瀏覽、派送掃描、下載原始檔皆正常），只有「上傳新基準檔」這個動作會失敗。

10.4 寄信（SMTP）設定¶

這項功能在做什麼：系統要寄密碼重設信、到期通知這類信件，得先知道要透過哪一台郵件伺服器寄。這通常是貴單位內網的郵件伺服器，封閉網路一樣可用。

登入系統 → 選單「系統設定」→「郵件伺服器設定」→ 填入郵件伺服器位址、連接埠、帳號密碼、寄件者位址與名稱、是否使用 TLS。

填完請按該頁的「寄送測試信」，輸入一個收得到的信箱驗證真的寄得出去。

成功長什麼樣：那個信箱幾秒內收到一封測試信。這一步千萬別跳過——比等到有人忘記密碼才發現寄不出去好得多。

不設定的話系統不會寄任何信——使用者忘記密碼時需要由管理員在「系統管理」→「帳號管理」重設。

這一頁全系統共用同一組設定，不論由哪個單位維護，改的都是同一份。

這一頁與「LDAP伺服器設定」自 1.15.0 起可以下放給貴單位的管理員自行維護，不再限於原廠帳號；權限指派方式見第三章 3.9。

「通知設定」是另一頁，管的是 Discord／Telegram 這類即時通知管道，與寄信無關。兩頁不要混淆。

10.5 檢測 Agent（選用）¶

這項功能在做什麼：要對貴單位的主機做組態檢測（政府組態基準等基準掃描），或要讓上傳的檔案留在貴單位自己的主機上，就需要在那些主機安裝「檢測 Agent」——一支小程式，負責跑檢測與收送檔案。

系統這一側不需要任何設定：安裝程式在裝機時就已把對接金鑰、認證模式與對外位址備妥（見第二章 2.3 ④-3）。

接一台 Agent 的步驟¶

登入系統 → 選單「系統管理」→「Agent 管理」→ 產生一組註冊 token（一次性的通行碼，用來證明這台 Agent 是您授權接進來的；彈窗會一併顯示要填的雲端位址）。
到要安裝 Agent 的那台主機，執行 Agent 安裝程式，填入該 token 與雲端位址。
回到「Agent 管理」確認該台已出現且狀態為在線。

成功長什麼樣：第 3 步在清單裡看到那台主機，狀態顯示在線。

Agent 能做什麼是它自己回報的：Agent 上線後會隨著定期回報告訴系統它具備哪些能力（檔案儲存、組態檢測）。不需要任何人工開通步驟——裝對版本、正常上線，該用到它的地方（派送檢測任務、儲存設定的「使用 Agent 服務」選項）就會出現它。

派送檢測任務時若顯示「本租戶尚無可用的檢測 Agent」，代表沒有任何在線 Agent 回報過檢測能力。請確認 Agent 已上線，並確認它的版本夠新（過舊的版本不會回報能力，請向原廠索取新版）。

接不上時¶

這一步在做什麼：在系統主機上把這一側所有相關設定檢查一遍，找出是哪裡沒接好。

sudo guidantai agent-check

成功長什麼樣：所有項目都標通過。有問題時它會逐項指出問題與修法，詳見第四章 4.9。

要備份的¶

Agent 對接金鑰在 <資料目錄>/pki/agent/，不在兩份設定檔內，請確認備份有涵蓋（見第四章 4.7）。遺失的後果是所有已註冊的 Agent 全部離線並需逐台重新註冊。

10.6 Log 轉發（選用）¶

這項功能在做什麼：把系統的紀錄自動送一份到貴單位自己的集中 log 平台（rsyslog／Graylog／ELK 這類）。接 SIEM 的客戶通常要的是「稽核事件」那一項——誰登入、誰改了什麼。這連的是貴單位內網的機器，封閉網路一樣可用。

系統這一側不需要任何安裝步驟，全部在畫面上設定，存檔後不必重啟服務。

設定步驟¶

先在貴單位的 log 伺服器上把接收端開好（rsyslog 的 input、Graylog 的 GELF／Syslog input、Logstash 的 syslog pipeline）。設定範例見《Log 轉發設定使用指南》第三章。
登入系統 → 選單「系統設定」→「Log 轉發設定」→ 填入協定（Syslog／GELF）、傳輸方式（UDP／TCP）、log 伺服器位址與連接埠，並勾選要送的內容（應用程式 log／稽核事件）。
按儲存，再按發送測試 log。
到 log 伺服器確認那則測試訊息真的收到了。

成功長什麼樣：第 4 步在 log 伺服器上看到一行 [Guidant AI] log 轉發測試訊息。

三個要先知道的行為¶

測試按鈕測的是「已儲存」的設定，不是畫面上剛打的字。表單有未儲存的變更時按鈕會反灰。
UDP 送出成功不等於對方收到（UDP 沒有回執）。畫面上會如實這樣寫，不會一律顯示「測試成功」。想要連線層的確認請選 TCP。
存檔後最多 30 秒全面生效（系統有多個服務程序，各自跟上）。存完立刻去 log 伺服器找不到訊息，先等半分鐘。

網路需求¶

貴單位主機之間需放行所選的埠與傳輸方式（UDP 或 TCP）。傳統的 syslog 埠 514 在 Linux 上需 root 權限才能監聽，手冊範例一律用高位埠 5514。

出狀況時¶

log 伺服器連不上、當機或位址填錯，都不會影響系統本身——本機紀錄照常寫入，只有送出去的那份副本會被丟棄。要確認系統這端有沒有在轉發：

sudo grep 'log 轉發' /srv/guidant-ai/log/app.log | tail -20

完整的三家對接範例、送出內容格式與排錯對照表 → 《Log 轉發設定使用指南》（docs/user-manual/log-forwarding-guide.md，隨出貨包附上）。

10.7 第三方元件風險的弱點資料更新¶

這項功能在做什麼：「第三方元件風險」掃描時，是在一個不連網的隔離環境裡，拿本機的弱點資料去比對。安裝程式已經放好一份（見第二章 ⑥-3），但每天都有新弱點公布，建議至少每月更新一次。

更新的方式有兩種，結果完全相同：

方式	適用	怎麼做
上傳更新包	封閉網路（預設）	向原廠取得 `guidant-vulndb-<日期>.tar.zst`（約 480 MB）→ 系統設定「弱點資料庫」→「上傳更新包」。請用 https 網址開啟系統，http 下瀏覽器無法計算檔案指紋。操作細節見《第三方元件風險使用指南》第七章
連網自動更新	可連外網	依下方步驟設定更新站位址，之後在同一頁按「檢查更新」或開啟「每日自動檢查更新」（每天 04:10 UTC 檢查一次）

升級系統時，出貨包內的弱點資料比現場新才會替換；貴單位已從設定頁上傳過較新的一份就保留。

設定更新站（只有要連網自動更新才需要）¶

向原廠索取更新站位址（必須是 https:// 開頭）。
編輯設定檔：

sudo vi /srv/guidant-ai/guidant.env

加入一行：

VULNDB_UPDATE_URL=<原廠提供的位址>

套用設定：

sudo guidantai start

🔴 這裡要用 start，不是 restart，理由同 10.1。

成功長什麼樣：系統設定「弱點資料庫」頁的「檢查更新」按鈕可以按，按下後顯示「目前已是最新資料」或「弱點資料已更新為 YYYY-MM-DD」。

要先知道的事¶

只有背景處理服務會連更新站，系統會取 <位址>/latest.json 判斷有沒有較新的一份，有才下載。分析原始碼的隔離環境自始至終不連網。對外連線清單見第八章 8.4。
空間：弱點資料放在 Docker 資料區（volume guidant_guidant-scan-vulndb），解開約 4.7 GB；每次更新時新舊兩份短暫並存，約 9.5 GB，切換完成後舊的自動刪除。請確認 /var/lib/docker 所在分割區留有空間。
更新包要有原廠簽章，日期也必須比現有資料新，否則會被拒絕，現有資料不受影響。
每次更新（不論哪種方式）都會在「弱點資料庫」頁的更新紀錄留下一列：時間、操作者、來源、資料日期前後、結果。
guidantai uninstall 會連同弱點資料一起刪除；重新安裝時會從出貨包放回。