從警報建立 Jira 問題
連接 Jira 後,操作員只需一次點擊,就能把警報或安全發現轉為 Jira 問題。問題會預先填入 Excubius 所知的所有資訊,其問題鍵會儲存在警報上,而且 Excubius 會追蹤其狀態直到完成。本指南說明如何連接 Jira Cloud、如何把每個客戶導向它自己的專案,以及問題包含哪些內容。
開始之前
- 一個 Jira Cloud 網站。不支援 Jira Server 及 Data Center。
- 供 Excubius 使用的 Atlassian 帳戶,並在目標專案中具備以下權限:Browse projects、Create issues、Add comments 及 Link issues。不需要任何管理權限:Excubius 從不轉換、編輯或刪除問題。
- 功能
collab.jira已在 Settings › Instance 中開啟。它需要collab.assign。由超級管理員切換。 - 若要設定伺服器層級的預設值,你需要能夠存取伺服器設定。若要設定實體自己的 Jira 設定,你需要在該實體上具備 Entity admin 角色。
此版本的控制台中沒有 Jira 設定畫面:預設值在伺服器設定中指定,各實體的設定則透過 API 指定。
選擇 Excubius 如何登入 Jira
auth | 憑證 | 適用情況 |
|---|---|---|
token(預設) | 帳戶的電子郵件地址及 API 權杖 | 一般情況:使用帶有 API 權杖的專用 Atlassian 帳戶 |
oauth | Atlassian 服務帳戶的用戶端 ID 及用戶端密碼,加上網站的雲端 ID | 你的組織使用具備 OAuth 2.0 用戶端憑證的 Atlassian 服務帳戶。此時 API 位於 https://api.atlassian.com/ex/jira/<cloud_id> |
bearer | 原樣傳送的權杖 | 閘道後方的個人存取權杖 |
網站的雲端 ID 可在 https://<site>.atlassian.net/_edge/tenant_info 找到。
在伺服器上設定預設值
預設值適用於所有沒有設定自己的值的實體。
-
連線到伺服器,並以
sudo -iu excubius切換為服務帳戶。 -
把設定新增到
/opt/excubius/.env。預設的token驗證設定如下:JIRA_BASE_URL=https://areito.atlassian.netJIRA_EMAIL=monitoring@areito.exampleJIRA_API_TOKEN=<API token>JIRA_DEFAULT_PROJECT=OPSJIRA_ISSUE_TYPE=Task如果使用
oauth,請改為設定JIRA_AUTH=oauth、JIRA_OAUTH_CLIENT_ID、JIRA_OAUTH_CLIENT_SECRET及JIRA_CLOUD_ID,以取代電子郵件及 API 權杖。 -
重新啟動平台:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
把客戶導向它自己的專案
每個實體都可以為自己設定任何 Jira 設定鍵。設定會按設定鍵逐一向下繼承:設定了該鍵的最近一個實體優先。因此,一個 Jira 網站可以服務所有客戶,每個客戶各有自己的專案和憑證。
-
把 Jira 憑證儲存在實體上:開啟 Settings › Credentials,選擇實體(例如桃花島物流),並新增類型為 HTTP user and password(電子郵件及 API 權杖,或 OAuth 用戶端 ID 及密碼)或 Bearer token 的憑證。密碼會加密儲存,之後不會再顯示。
-
透過 API 設定實體的設定鍵。
$BASE是https://<your server>/api/v1,H存放你的權杖,與快速入門:使用 API 新增 SQL Server 實例相同:curl -s "${H[@]}" -X PUT "$BASE/entities/$CIGUAPA/jira" -d '{"project_key": "CIG", "issue_type": "Task","credential_id": "'"$JIRA_CRED"'", "labels": ["monitoring"]}' -
查看目前適用的設定,以及每個設定鍵來自何處。回應會說明實體是否
configured,如果沒有,則在problem中說明缺少什麼:curl -s "${H[@]}" "$BASE/entities/$CIGUAPA/jira" | jq '{configured, problem, effective, sources}' -
測試連線。測試只進行讀取:憑證在 Jira 中對應的身份、專案及其問題類型。
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/jira/test"
若要把某個設定鍵恢復為繼承的值,請傳送 null。DELETE /entities/{id}/jira 會移除該實體自己的所有設定鍵。
| 設定鍵 | 預設值 | 含義 |
|---|---|---|
base_url | JIRA_BASE_URL | https://<site>.atlassian.net |
auth | JIRA_AUTH,未設定時為 token | token、oauth 或 bearer |
credential_id | 伺服器設定中的電子郵件及權杖,或 OAuth 用戶端 | 此實體或其上層實體的憑證:token 及 oauth 使用 HTTP user and password,bearer 使用 Bearer token |
cloud_id | JIRA_CLOUD_ID | 僅用於 oauth |
project_key | JIRA_DEFAULT_PROJECT | 問題的去向,例如 OPS |
issue_type | JIRA_ISSUE_TYPE,未設定時為 Task | 該專案中的問題類型名稱 |
priority_map | critical → High, warning → Medium, info → Low | 嚴重程度對應到 Jira 優先順序名稱 |
labels | 無 | 額外標籤,不可包含空格 |
summary_prefix | 方括號中的產品名稱 | 摘要之前的文字;留空表示不加前置詞 |
sync | true | 追蹤問題的狀態 |
done_comment | true | 問題完成時在問題上留言,說明狀況是否仍被偵測到 |
resolve_events_on_done | true | 在事件警報(例如特殊權限群組成員的變更)的問題完成時,解決該事件警報 |
建立問題
- 在 Alert inbox 中,選取警報。如果是安全發現,請在 Security posture 頁面上開啟它。
- 選取 Create Jira ticket。你需要具備 Operator 或以上的角色。
Excubius 會確認 Jira ticket OPS-123 created,並把問題鍵儲存在警報上,讓所有人都看到。每個警報最多只有一個問題:再次要求時會傳回既有的問題鍵。
問題包含:
- Summary:前置詞、警報的標題及資源。
- Description:嚴重程度、類別及狀態;首次及最後一次出現;資源及其實體路徑、重要程度、標記,以及主機、版本和可用性群組等識別資訊;檢查的數值與閾值的比較及該閾值的設定位置;如果是發現,則包括其證據;基線參考;最近十個時間軸事件;標示為建議的建議處理方式;以及返回警報和資源的連結。
- Labels:產品名稱、類別(
alert、finding、advisory)、嚴重程度,以及你的額外標籤。 - Priority:依嚴重程度透過
priority_map取得。如果專案不接受優先順序,問題會在不設定優先順序的情況下建立。 - 問題上返回警報的連結。
追蹤問題的狀態
Excubius 每 10 分鐘讀取最多 100 個開啟中問題的狀態,最久沒有檢查的優先。JIRA_SYNC_MINUTES 可以變更間隔。當問題的狀態達到 Done 類別時:
- 警報的時間軸會記錄下來。
- 事件警報(例如
sysadmin成員的變更)會被解決:該項變更已經過審查。 - 其他警報不會因問題完成而解決。它們會在下一次檢查不再偵測到狀況時解決,而問題上的留言會說明狀況是否仍被偵測到。
權杖過期或問題被刪除會被記錄,並在下一次同步時重試。問題完成後就不再追蹤。
限制
- 狀態以輪詢方式取得;尚未使用 Jira 向 Excubius 發送的 Webhook。
- OAuth 2.0 是 Atlassian 服務帳戶的用戶端憑證流程。不支援逐用戶的 OAuth。
- 不支援 Jira Server 及 Data Center。