這系列連續五篇，講兩種建立API Key用於自己開發程式，讓所有網路設備,主機,其他系統發表單到BeakPlatform，未必是資安，也可以是維運，甚至股票,直播,拍賣,生活應用...就看你的創意了
雖然是以表單為發動媒體，但整個過程可以完全無人員介入簽核，所以其實可以視同機-機流程
正確的說法是以配對為發動媒體，但前面只略提，所以還是講表單發動較為直覺
WAF、防火牆、EDR、弱點掃描器、維運腳本都會產生告警。過去這些告警靠 email 或即時通訊轉給值班人員， 沒有編號、沒有時限、也沒有人知道同一個攻擊來源今天已經被通報過幾次。 這個系列教你用一把 API Key，讓設備在偵測到事件時直接在 BeakPlatform 建立一張「資安案件」， 後續同一群事件會累加到同一張單，值班人員在「資安案件處置中心」審理並下決策。
整條路徑分成四段，各自一篇：
| 篇 | 標題 | 誰要讀 | 讀完能做到 |
|---|---|---|---|
| 01 | 企業管理員直接配發 API Key | 企業管理員 | 在「系統安全 ／ API Key 管理」替一台設備建一把 Key、設授權範圍與來源 IP 白名單、日常暫停與撤銷 |
| 02 | 透過表單中心申請 API Key | 資安人員、企業管理員 | 員工填「API Key 申請單」，管理員核准，系統自動核發，本人到「個人設定」一次性領取金鑰並取得串接範例 |
| 03 | 從你的設備建立第一張資安案件 | 維運工程師、資安人員 | 用建單工具或純 curl 呼叫 POST /api/trigger/form 建出案件；把自家設備的欄位對應到表單 28 個欄位；看懂每個錯誤碼 |
| 04 | 持續事件如何累加到同一張案件 | 同上 | 理解分組鍵與時間視窗、用 case_group_key 把一次掃描的多個 IP 併成一單、在案件上看「持續事件」分頁、調整聚合規則 |
閱讀順序建議
你是管理員、要替一台設備開通：讀 01 → 03 → 04。你是資安人員、自己要接設備：讀 02 → 03 → 04。 只想知道「為什麼第二筆告警沒有開新單」：直接讀 04。四篇都以同一個虛構情境貫穿：示範企業 DemoSOC 的 WAF-01 攔到來源 203.0.113.42 對 www.demo.internal 的 SQL injection。
| 名詞 | 意思 | 在哪一篇 |
|---|---|---|
| key_id ／ secret | 一把 API Key 的兩半。key_id 是公開識別碼（ak_ 開頭），可以寫在設定檔與文件裡； secret 是簽章用的金鑰，只在建立或領取當下顯示一次，之後平台自己也查不到明文。 | 01、02 |
| 授權範圍 | 這把 Key 能建哪些表單。管理員配發時用「表單分類」或「個別表單」勾選；申請單核發的 Key 則固定綁申請時勾的表單。 | 01、02 |
| HMAC 簽章 | 設備每次呼叫都用 secret 對「時間戳＋請求內容」算一個簽章放在 header，平台重算一次比對。不需要 session、不需要登入。 | 03 |
| form_code | 表單的代號，例如 SEC_INCIDENT_RESPONSE。建案時用它指定要建哪一種案件。 | 03 |
| 案件編號 | 同一張案件有兩個編號：處置中心顯示流程執行編號（如 PROC-20260926-0002），表單中心顯示表單序號（如 Form-260900021）。跟同事溝通時要說清楚是哪一個。 | 03 |
| 共同軸線 | 六個所有資安表單都有的欄位：severity_id、actor_ip、target_host、source_system、finding_rule_id、occurred_at。併案判斷、風險分數、處置中心清單都讀這六個。 | 03、04 |
| 分組鍵 | 平台用來判斷「這筆事件跟哪張既有案件是同一群」的值。預設由 actor_ip 與 finding_rule_id 組成；送件端也可以自己指定 case_group_key。 | 04 |
| 項目 | 示範值 |
|---|---|
| 平台網址 | http://192.168.0.112:8000/beakplatform（讀者安裝版的主機 B；換成你自己的，網址一定要帶埠號與 /beakplatform） |
| 設備 | WAF-01，IP 192.168.0.111（主機 A） |
| 企業 | 示範企業 DemoSOC，網域 demo-soc.example |
| 企業管理員 | admin-admin.ops@demo-soc.example |
| 資安人員 | linda.hu@demo-soc.example（角色「資安人員」SECURITY_STAFF） |
| 攻擊來源 | 203.0.113.42（保留給文件用的測試網段，不是真實位址） |
| 被攻擊主機 | www.demo.internal |
| 資安表單 | SEC_INCIDENT_RESPONSE「資安事件處置」（示範企業出廠另有 SOC 團隊版與小企業單人版，欄位完全相同） |
示範企業由平台安裝時的 INSTALL_DEMO=1 建立；沒有示範企業的環境，把上表換成自己企業的帳號與表單即可，步驟不變。
iThome鐵人賽
看影片追技術