項目|說明
本篇一句話目標|拿著 01 或 02 篇取得的 API Key，從你的設備（或先用工作機）呼叫 POST /api/trigger/form，建出第一張資安案件並在處置中心看到它。
你需要的身分|一把授權範圍含「資安案件」分類（或個別資安表單）的 API Key；驗證畫面時需要能開「開放防禦 ／ 資安案件處置中心」的帳號（例：資安人員 linda.hu@demo-soc.example）。
做完會得到什麼|一張案件編號形如 PROC-20260926-0002 的資安案件、一份你的設備欄位到表單 28 個欄位的對照、一段可直接放進設備或排程的呼叫指令。
預估時間|15 至 30 分鐘（不含把設備接上的部分）。

1. 這一篇要做到什麼

前兩篇拿到的是一組 key_id 與 secret。這一篇把它用起來：由設備端對平台送一個帶簽章的 HTTP 請求，平台就會依你指定的表單建立一張資安案件並啟動它的處置流程，值班人員在「開放防禦 ／ 資安案件處置中心」看到案件、按決策按鈕。

全篇用同一個固定情境，範例指令與回應都照它寫：

指令一律用三個環境變數帶認證，之後每一段都沿用：

export BP_BASE_URL='http://192.168.0.112:8000/beakplatform'
export BP_KEY_ID='ak_a85efc52cc2455a4'
export BP_SECRET='<領取時顯示一次的 secret>'

secret 原樣貼上，不要自己轉碼
畫面顯示的 secret 是 base64url 字串。做 HMAC 時用的是它解碼後的 raw bytes，bp_trigger.py 會自己解碼；第 6 節的純 curl 寫法也有解碼那一行。先自行轉成十六進位或再 base64 一次，結果一律是 401 auth_failed。

2. 兩條事件入口，選對的那條

平台有兩個能用 API Key 建資安案件的入口。本系列只講第一條；第二條是給整合型防禦節點用的，欄位格式與授權方式都不同，這裡只列差別讓你確認自己沒走錯門。

簽章與驗證順序
兩條完全相同：headers X-BP-Key-Id／X-BP-Timestamp／X-BP-Signature，驗證順序 headers → 時間戳 ±300 秒 → Key 狀態 → 來源 IP 白名單 → 簽章；失敗一律 401 auth_failed

判斷方式很簡單：你的設備能不能自己組出「表單欄位名 = 值」這種 JSON？能，就走 /api/trigger/form。它不需要任何路由規則就能建案，設備欄位怎麼對到表單欄位由你在設備端決定（第 4 節）。

3. 先列出你能建的表單

建單工具 <平台安裝目錄>/scripts/bp_trigger.py 是單一檔案、只用 Python 3 標準函式庫，可以直接複製到任何有 python3 的主機。先用 --list 確認這把 Key 看得到哪些表單：

python3 bp_trigger.py --list

它打的是 GET /api/trigger/forms，只回這把 Key 授權範圍內、而且目前有「已發行」版本的表單。DemoSOC 的 Key 勾了「資安案件」分類時，輸出長這樣（field_keys 為節省篇幅只列前幾個）：

列出可發動表單成功（HTTP 200）
{
  "data": [
    {
      "code": "SEC_INCIDENT_RESPONSE",
      "field_keys": ["actor_asn", "actor_country", "actor_ip", "actor_user_agent", "actor_xff", "confidence", "..."],
      "form_code": "SEC_INCIDENT_RESPONSE",
      "is_security": true,
      "name": "資安事件處置",
      "published_secure_code": "<已發行版本的識別碼>",
      "version": "AA"
    },
    { "code": "SEC_IR_SOC_TEAM", "name": "資安事件處置（SOC 團隊版）", "is_security": true, "...": "..." },
    { "code": "SEC_IR_SOLO",     "name": "資安事件處置（小企業單人版）", "is_security": true, "...": "..." }
  ],
  "success": true
}

DemoSOC 出廠有三張資安表單，28 個欄位完全相同，差別只在綁的處置流程：

本篇一律用 SEC_INCIDENT_RESPONSE。要換成另外兩張，只需改 --form-code，欄位對照表不變。

4. 表單欄位對照表

這是本篇的核心。三張出廠資安表單的 28 個欄位分成五組（畫面上是五個折疊面板，標題與下表的組名相同）。「畫面標籤」是案件在處置中心與表單裡顯示的欄位名，「你的設備通常對到什麼」是建議的對應方式，依你的設備調整。

六條共同軸線
表中標「軸線」的六個欄位——severity_id、actor_ip、target_host、source_system、finding_rule_id、occurred_at——是平台判斷事件是否併入既有案件、計算風險分數、顯示案件摘要時讀的欄位。其中 actor_ip 與 finding_rule_id 是預設的分組鍵：兩個都有值，同來源同規則的後續事件才會併進同一張案件；任一缺值就各自開案（細節見 03 篇）。其他四條軸線可在「事件路由設定」的聚合區塊勾為分組鍵。

4.1 事件資訊

4.2 攻擊者

4.3 受攻擊目標

4.4 偵測規則

4.5 情報彙整（系統自動填寫）

這一組送件時不要填
下列 8 個欄位由平台在建案與併案時寫入。它們出現在 field_keys 裡，技術上送了不會被 400 擋下，但建案時會被平台算出的值覆蓋，或者留下誤導值。

三張出廠表單都沒有設定任何必填欄位，所以只帶一個欄位也能建案。但少了 actor_ip 或 finding_rule_id，之後同一波攻擊的每筆告警都會各自開一張單，第 9 節的「最小欄位集」就是為了避免這件事。

5. 建立第一張案件

照第 1 節的情境，把 WAF-01 這筆告警送進去。--subject 是案件在處置中心清單上顯示的標題，必填；每個 --field 是「欄位 key=值」：

python3 bp_trigger.py --form-code SEC_INCIDENT_RESPONSE \
  --subject 'WAF-01 SQL injection 203.0.113.42 -> www.demo.internal' \
  --field finding_title='SQL injection attempt on /login' \
  --field finding_summary='WAF 攔截到 /login 的 POST 參數含 UNION SELECT，10 秒內 3 次' \
  --field event_class='web_attack' \
  --field source_system='waf-01' \
  --field severity_id=4 \
  --field confidence=90 \
  --field occurred_at='2026-09-26T14:02:11Z' \
  --field actor_ip=203.0.113.42 \
  --field actor_country=XX \
  --field actor_user_agent='sqlmap/1.8' \
  --field target_host=www.demo.internal \
  --field target_url='/login' \
  --field target_service=https \
  --field finding_rule_id=WAF-SQLI-001 \
  --field finding_rule_set=owasp-crs \
  --field detector_hint_action=block \
  --field detector_hint_ttl_sec=3600

成功時工具印出「建單成功（HTTP 201）」與平台回應：

建單成功（HTTP 201）
{
  "data": {
    "execution_code": "PROC-20260926-0002",
    "form_instance_secure_code": "<表單實例識別碼>",
    "serial_number": "Form-260900021",
    "workflow_instance_secure_code": "<流程實例識別碼>"
  },
  "message": "表單已送出，流程已啟動",
  "success": true
}

同一事件再送一次時不會多開一張單：只要 actor_ip 與 finding_rule_id 相同、且在聚合視窗內，平台回 200 並帶 merged: true，工具會印「事件已併入既有案件 PROC-20260926-0002（累計 2 筆）」。這是 04 篇的主題。

5.1 用 --json 整包送

設備端已經組好 JSON 時，用 --json 一次帶入整包 form_data；仍可用 --field 覆蓋或追加單一欄位（--field 優先）：

python3 bp_trigger.py --form-code SEC_INCIDENT_RESPONSE \
  --subject 'WAF-01 SQL injection 203.0.113.42 -> www.demo.internal' \
  --json '{"finding_title":"SQL injection attempt on /login","source_system":"waf-01","severity_id":4,
           "occurred_at":"2026-09-26T14:02:11Z","actor_ip":"203.0.113.42","target_host":"www.demo.internal",
           "target_url":"/login","finding_rule_id":"WAF-SQLI-001"}' \
  --field finding_rule_set=owasp-crs

--field 送出的值一律是字串（severity_id=4 送出去是 "4"），平台照樣接受；要送真正的數字用 --json。

5.2 工具的參數與退出碼

6. 不用工具，直接 curl

設備或 SIEM 上沒有 Python 時，自己組請求。簽章規格如下：

下面這段 bash 與「個人設定 ／ 我的 API Key」的「查看串接範例」視窗產生的格式相同，用第 5 節的欄位改寫；需要 openssl、base64、xxd、curl：

BASE='http://192.168.0.112:8000/beakplatform'
KEY_ID='ak_a85efc52cc2455a4'
SECRET="$BP_SECRET"
BODY='{"form_code":"SEC_INCIDENT_RESPONSE","subject":"WAF-01 SQL injection 203.0.113.42 -> www.demo.internal","form_data":{"finding_title":"SQL injection attempt on /login","source_system":"waf-01","severity_id":4,"occurred_at":"2026-09-26T14:02:11Z","actor_ip":"203.0.113.42","target_host":"www.demo.internal","target_url":"/login","finding_rule_id":"WAF-SQLI-001","finding_rule_set":"owasp-crs"}}'
TS=$(date +%s)
KEY_HEX=$(printf '%s' "$SECRET" | tr '_-' '/+' | base64 -d | xxd -p | tr -d '\n')
SIG=$(printf '%s\n%s' "$TS" "$BODY" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$KEY_HEX" -hex | awk '{print $NF}')
curl -s -X POST "$BASE/api/trigger/form" \
  -H 'Content-Type: application/json' \
  -H "X-BP-Key-Id: $KEY_ID" \
  -H "X-BP-Timestamp: $TS" \
  -H "X-BP-Signature: sha256=$SIG" \
  -d "$BODY"

逐行說明：

• SECRET="$BP_SECRET" 一定用雙引號。單引號不展開變數，會拿 $BP_SECRET 這七個字元去解碼，恆得 401。
• KEY_HEX=…：把 base64url 的 _、- 換回 /、+ 後解碼，再轉成十六進位交給 openssl 當金鑰。這一行就是「secret 要先解碼」的實作。
• SIG=…：printf '%s\n%s' 產生「時間戳＋一個換行＋body」，交給 HMAC-SHA256，取最後一欄的十六進位值。
• -d "$BODY"：送出的 body 必須與簽章時的位元組完全相同。不要在簽完之後再用工具重新排版、排序 key 或改縮排；平台是拿收到的原始 bytes 驗章，多一個空白就是 401。

在其他語言實作時
只有三件事：(1) secret 用 base64url 解碼成 bytes；(2) 先把 body 序列化成最終要送的 bytes，再用同一份 bytes 算 HMAC；(3) 時間戳用 Unix 秒的字串。bp_trigger.py 用的序列化是 json.dumps(body, ensure_ascii=False, separators=(',', ':'))，但這不是要求，任何序列化都可以，只要簽的與送的是同一份。

7. 到畫面上找到這張案件

用能開處置中心的帳號登入（DemoSOC 出廠的 SEC_INCIDENT_RESPONSE 流程指派給角色「資安人員」，linda.hu@demo-soc.example 持有它），開「開放防禦 ／ 資安案件處置中心」：

1. 左側案件清單每一列顯示：案件標題（就是你送的 subject）、嚴重度徽章（S4）、案件編號（PROC-20260926-0002）、送單時間、SLA 狀態。清單可依「時間」「案件編號」「緊急度」「逾時」排序。
2. 點進去，右側標題旁再次顯示案件編號與狀態（RUNNING），右上是「風險」分數與「建議」處置。
3. 「案件摘要」分頁列出：攻擊者 IP、嚴重度、偵測來源、規則 ID、聚合事件數、來源 IP 數、建立時間、處置流程，以及簽核歷程（前手判斷）與決策按鈕。第一張案件的「聚合事件數」是 1。
4. 「原始欄位」分頁以「欄位名／值」表格列出案件其餘的欄位（已在摘要呈現的六條軸線、風險分數、建議處置，以及 correlation_id、actor_xff 與 od_ 開頭的系統欄位不在這張表），可用來核對第 4 節的對照有沒有送錯欄。
5. 「持續事件」分頁在案件有事件摘要時才出現：帶了 actor_ip 與 finding_rule_id 建的案件從第一筆就有，欄位是收到時間、發生時間、來源、嚴重度、來源 IP、目標主機、規則 ID、標題。

僅我可簽核」預設是開著的
清單頂端的「僅我可簽核」按鈕預設啟用，只列輪到你這一關簽核的案件。上方統計「進行中案件」有數字、清單卻空的，通常是你的帳號沒有這張表單流程簽核節點要求的角色（預設流程是「資安人員」），不是建單失敗。按掉「僅我可簽核」可以看到全部案件；要能按決策按鈕仍然要有角色。

兩件容易誤判的事：

• 資安案件不會出現在「表單中心」。表單中心的待簽核與追蹤清單刻意過濾掉資安案件分類，所以回應裡的表單序號 serial_number（Form-260900021）在畫面上看不到；處置中心顯示的一律是案件編號 execution_code。
• 「系統安全 ／ API Key 管理」列表的「最後使用」欄會更新。平台在每次驗章成功後（包含 --list）就寫入時間，所以管理員可以從這一欄確認設備真的打進來了；值一直是空的代表請求根本沒通過驗章。

8. 錯誤碼對照

平台的錯誤回應是 JSON，主要看 error；驗章失敗的回應只有 {"error": "auth_failed"}，其餘還多一個 success: false。工具遇到非 2xx 印「建單失敗（HTTP …）」並以退出碼 3 結束。

三個實際回應範例：

# 欄位打錯名（src_ip）
建單失敗（HTTP 400）
{"details": {"allowed_keys": ["actor_asn", "actor_country", "actor_ip", "..."], "unknown_keys": ["src_ip"]},
 "error": "unknown_field", "success": false}

# secret 錯
列出可發動表單失敗（HTTP 401）
{"error": "auth_failed"}

# 表單不在授權範圍（用了人資表單的 form_code）
建單失敗（HTTP 404）
{"error": "form_not_found", "success": false}

9. 接到你的設備上

先決定「最小欄位集」。不論用哪種接法，每筆事件至少帶這七個欄位，之後的併案、風險分數、案件摘要才會正確：

actor_ip 與 finding_rule_id 為什麼非帶不可，03 篇有實際跑出來的對照（帶了併成一單、缺了各自開單）。

9.1 設備本身能發 webhook

條件是設備的 webhook 功能要能自己算 HMAC-SHA256 並放進 header——多數設備的「HTTP 通知」只能填固定 URL 與固定 header，算不出隨時間變動的 X-BP-Signature，這種就不能直接接。能寫腳本的設備（例如有 Lua、Python 或 shell hook 的 WAF）照第 6 節的三個步驟實作：解碼 secret、用送出的 body bytes 算簽章、帶三個 header。secret 放在設備的密碼庫或只有 root 可讀的設定檔，不要寫在通知規則的畫面裡。

9.2 設備只會寫 log

最常見的情況。在設備旁或能讀到 log 的主機放一支輪詢腳本，做三件事：讀新增的告警行、把欄位對到第 4 節的 key、呼叫 bp_trigger.py。範例（以每筆告警已整理成一行 JSON 為前提）：

#!/bin/bash
# 由排程每分鐘執行；環境變數 BP_BASE_URL / BP_KEY_ID / BP_SECRET 放在 root 0600 的檔案裡 source 進來
set -u
. /etc/waf-01/bp.env
LOG=/var/log/waf-01/alerts.jsonl
OFFSET_FILE=/var/lib/waf-01/bp.offset
done_lines=$(cat "$OFFSET_FILE" 2>/dev/null || echo 0)   # 上一輪已處理的行數
n=$done_lines
while read -r line; do
  python3 /usr/local/bin/bp_trigger.py --form-code SEC_INCIDENT_RESPONSE \
    --subject "WAF-01 $(echo "$line" | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d["rule"],d["client_ip"])')" \
    --json "$(echo "$line" | python3 -c '
import sys, json
d = json.load(sys.stdin)
print(json.dumps({
  "finding_title": d["msg"], "source_system": "waf-01", "severity_id": d["sev"],
  "occurred_at": d["ts"], "actor_ip": d["client_ip"], "target_host": d["host"],
  "target_url": d["uri"], "finding_rule_id": d["rule"], "finding_rule_set": d.get("ruleset", ""),
}))')"
  rc=$?
  if [ "$rc" -eq 4 ]; then break; fi              # 連不上平台：停在這一行，offset 不推進，下一輪從這裡重送
  if [ "$rc" -eq 3 ]; then echo "line $((n + 1)) rejected rc=3" >&2; fi   # 4xx：內容或授權問題，記錄後跳過
  n=$((n + 1))
done < <(tail -n +"$((done_lines + 1))" "$LOG")
echo "$n" > "$OFFSET_FILE"

要點：退出碼 4（連不上）不推進讀取位置，下一輪重送；退出碼 3 的 4xx 是內容或授權問題，重送也不會過，記錄下來人工處理。重送同一筆事件不會多開單，所以偶爾重複送是安全的。

9.3 SIEM／SOAR 有 HTTP 動作

多數 SIEM／SOAR 的 HTTP 動作允許在送出前跑一段腳本或表達式。把第 6 節的三步驟放進那段腳本（大部分平台內建 HMAC-SHA256 函式），body 用 SIEM 的告警欄位對到第 4 節的 key。留意兩點：SIEM 常會替你「美化」JSON——要確定簽章算的是最終送出的那份；以及 SIEM 主機的時鐘要 NTP 同步，否則整批 401。一個 SIEM 規則可能同時涵蓋多台設備，這時 source_system 填原始設備名，不要填 SIEM 名，案件摘要才看得出來源。

10. 注意事項

時鐘差超過 5 分鐘，整台設備的請求全部 401
症狀：昨天還好好的，今天每一筆都 auth_failed，secret 沒改過。　
原因：平台只接受與自己相差 300 秒內的 X-BP-Timestamp，設備時鐘飄掉就整批失敗，而且回應不會告訴你是時間問題。　
正確做法：設備與平台都做 NTP 同步；排除 401 時先比對 date +%s 與平台主機的差值。

secret 自行轉碼或被引號吃掉，恆 401
症狀：用 --selftest 第 1 項就 401。　
原因：secret 要原樣交給工具（它自己解 base64url）；純 curl 時 SECRET 用了單引號包 $BP_SECRET，或把畫面上的 secret 又 base64 一次、轉成 hex。　
正確做法：複製畫面上的字串原樣放進 BP_SECRET；純 curl 照第 6 節那段，不要改 KEY_HEX 那行。

主旨缺少 → 400 missing_subject；欄位打錯名 → 400 unknown_field
這兩個是接新設備時最先遇到的。前者是 body 沒有 subject（工具會在本機就擋下）；後者照回應裡的 allowed_keys 改欄位名。欄位名區分大小寫，且不能用畫面標籤（「攻擊者 IP」）代替 key（actor_ip）。

表單分類勾了，建案卻 404 form_not_found
Key 的授權範圍是對的，但那張表單目前沒有「已發行」版本時，平台回的是 422 form_not_published；若 form_code 根本不在授權範圍才是 404。先跑 --list：列得出來的表單一定建得了；列不出來，不是 Key 沒授權那個分類，就是表單沒發行或不在該分類下。

同一事件重送不會多開單
只要 actor_ip 與 finding_rule_id 相同且在聚合視窗內，第二筆會回 200 merged:true 併進第一張案件，「聚合事件數」+1。這是設計，不是漏建；設備端重試機制可以放心重送。什麼情況會併、什麼情況不會，見 04 篇。

「事件路由設定」的規則不會把 trigger 事件改送到別張表單
DemoSOC 出廠有一條「高嚴重度走 SOC 團隊版」規則，但它只對 /api/open_defense/intake 路徑生效。你在 form_code 指定哪張表單，案件就建在哪張；規則只拿來讀該表單的聚合設定。要讓 WAF 的高嚴重度事件走 SOC 團隊版，設備端自己依嚴重度改 --form-code。

「情報彙整」那組欄位不要送
risk_score、recommended_action、od_event_count 等 8 個欄位由平台寫；送了不會報錯，但會被覆蓋或留下誤導值（第 4.5 節）。

11. 下一步

第一張案件建好之後，設備會持續送第二筆、第三筆。哪些會併進同一張案件、哪些會開新單、怎麼用 case_group_key 把一次掃描的多個 IP 併成一單、在案件上看到什麼，見 04 持續事件如何累加到同一張案件。

還沒有 API Key 的讀者回 02 企業管理員直接配發 API Key 或 03 透過表單中心申請 API Key。