跳到主要内容
版本:0.4 · 当前版

通过警报创建 Jira 问题

操作指南审阅日期:2026年10月11日
适用于:Excubius 0.4角色: 实体管理员, 安装人员(Linux 管理员)
计划Pro · Enterprise部署自托管

连接 Jira 后,操作员只需一次单击,即可将警报或安全发现转换为 Jira 问题。该问题会预先填入 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 服务账户。此时通过 https://api.atlassian.com/ex/jira/<cloud_id> 访问 API
bearer按原样发送的令牌网关后面的个人访问令牌

可在 https://<site>.atlassian.net/_edge/tenant_info 找到站点的云 ID。

在服务器上设置默认值​

默认值适用于所有未设置自己值的实体。

  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_map严重 → High,警告 → Medium,信息 → 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 由严重性得出。如果项目不接受优先级,则创建的问题不带优先级。
  • 问题上指回警报的链接。

跟踪问题的状态​

每隔 10 分钟,Excubius 会读取最多 100 个未完成问题的状态,优先读取最久未检查的问题。JIRA_SYNC_MINUTES 可更改该间隔。当问题达到 Done 类别的状态时:

  • 警报的时间线会记录这一点。
  • 事件警报(例如 sysadmin 成员的变更)会被解决:该变更已经过审查。
  • 其他警报不会因问题而解决。它们会在下一次检查不再检测到该情况时解决,问题上的评论会说明是否仍检测到该情况。

令牌过期或问题被删除会被记录,并在下次同步时重试。问题完成后不再被跟踪。

限制​

  • 状态通过轮询获取;尚未使用从 Jira 回调到 Excubius 的 Webhook。
  • OAuth 2.0 是 Atlassian 服务账户的客户端凭据流。不支持按用户的 OAuth。
  • 不支持 Jira Server 和 Data Center。