跳至主要内容
版本:0.4 · 現行版

從警報建立 Jira 問題

操作指南審閱日期:2026年10月11日
適用於:Excubius 0.4角色: 實體管理員, 安裝人員(Linux 管理員)
方案Pro · Enterprise部署自行託管

連接 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 帳戶
oauthAtlassian 服務帳戶的用戶端 ID 及用戶端密碼,加上網站的雲端 ID你的組織使用具備 OAuth 2.0 用戶端憑證的 Atlassian 服務帳戶。此時 API 位於 https://api.atlassian.com/ex/jira/<cloud_id>
bearer原樣傳送的權杖閘道後方的個人存取權杖

網站的雲端 ID 可在 https://<site>.atlassian.net/_edge/tenant_info 找到。

在伺服器上設定預設值​

預設值適用於所有沒有設定自己的值的實體。

  1. 連線到伺服器,並以 sudo -iu excubius 切換為服務帳戶。

  2. 把設定新增到 /opt/excubius/.env。預設的 token 驗證設定如下:

    JIRA_BASE_URL=https://areito.atlassian.net
    JIRA_EMAIL=monitoring@areito.example
    JIRA_API_TOKEN=<API token>
    JIRA_DEFAULT_PROJECT=OPS
    JIRA_ISSUE_TYPE=Task

    如果使用 oauth,請改為設定 JIRA_AUTH=oauth、JIRA_OAUTH_CLIENT_ID、JIRA_OAUTH_CLIENT_SECRET 及 JIRA_CLOUD_ID,以取代電子郵件及 API 權杖。

  3. 重新啟動平台:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    systemctl --user restart excubius.service

把客戶導向它自己的專案​

每個實體都可以為自己設定任何 Jira 設定鍵。設定會按設定鍵逐一向下繼承:設定了該鍵的最近一個實體優先。因此,一個 Jira 網站可以服務所有客戶,每個客戶各有自己的專案和憑證。

  1. 把 Jira 憑證儲存在實體上:開啟 Settings › Credentials,選擇實體(例如桃花島物流),並新增類型為 HTTP user and password(電子郵件及 API 權杖,或 OAuth 用戶端 ID 及密碼)或 Bearer token 的憑證。密碼會加密儲存,之後不會再顯示。

  2. 透過 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"]
    }'
  3. 查看目前適用的設定,以及每個設定鍵來自何處。回應會說明實體是否 configured,如果沒有,則在 problem 中說明缺少什麼:

    curl -s "${H[@]}" "$BASE/entities/$CIGUAPA/jira" | jq '{configured, problem, effective, sources}'
  4. 測試連線。測試只進行讀取:憑證在 Jira 中對應的身份、專案及其問題類型。

    curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/jira/test"

若要把某個設定鍵恢復為繼承的值,請傳送 null。DELETE /entities/{id}/jira 會移除該實體自己的所有設定鍵。

設定鍵預設值含義
base_urlJIRA_BASE_URLhttps://<site>.atlassian.net
authJIRA_AUTH,未設定時為 tokentoken、oauth 或 bearer
credential_id伺服器設定中的電子郵件及權杖,或 OAuth 用戶端此實體或其上層實體的憑證:token 及 oauth 使用 HTTP user and password,bearer 使用 Bearer token
cloud_idJIRA_CLOUD_ID僅用於 oauth
project_keyJIRA_DEFAULT_PROJECT問題的去向,例如 OPS
issue_typeJIRA_ISSUE_TYPE,未設定時為 Task該專案中的問題類型名稱
priority_mapcritical → High, warning → Medium, info → Low嚴重程度對應到 Jira 優先順序名稱
labels無額外標籤,不可包含空格
summary_prefix方括號中的產品名稱摘要之前的文字;留空表示不加前置詞
synctrue追蹤問題的狀態
done_commenttrue問題完成時在問題上留言,說明狀況是否仍被偵測到
resolve_events_on_donetrue在事件警報(例如特殊權限群組成員的變更)的問題完成時,解決該事件警報

建立問題​

  1. 在 Alert inbox 中,選取警報。如果是安全發現,請在 Security posture 頁面上開啟它。
  2. 選取 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。