通过警报创建 Jira 问题
连接 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 账户 |
oauth | Atlassian 服务账户的客户端 ID 和客户端密码,以及站点的云 ID | 你的组织使用具有 OAuth 2.0 客户端凭据的 Atlassian 服务账户。此时通过 https://api.atlassian.com/ex/jira/<cloud_id> 访问 API |
bearer | 按原样发送的令牌 | 网关后面的个人访问令牌 |
可在 https://<site>.atlassian.net/_edge/tenant_info 找到站点的云 ID。
在服务器上设置默认值
默认值适用于所有未设置自己值的实体。
-
连接到服务器,并使用
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 | 严重 → High,警告 → Medium,信息 → 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由严重性得出。如果项目不接受优先级,则创建的问题不带优先级。 - 问题上指回警报的链接。
跟踪问题的状态
每隔 10 分钟,Excubius 会读取最多 100 个未完成问题的状态,优先读取最久未检查的问题。JIRA_SYNC_MINUTES 可更改该间隔。当问题达到 Done 类别的状态时:
- 警报的时间线会记录这一点。
- 事件警报(例如
sysadmin成员的变更)会被解决:该变更已经过审查。 - 其他警报不会因问题而解决。它们会在下一次检查不再检测到该情况时解决,问题上的评论会说明是否仍检测到该情况。
令牌过期或问题被删除会被记录,并在下次同步时重试。问题完成后不再被跟踪。
限制
- 状态通过轮询获取;尚未使用从 Jira 回调到 Excubius 的 Webhook。
- OAuth 2.0 是 Atlassian 服务账户的客户端凭据流。不支持按用户的 OAuth。
- 不支持 Jira Server 和 Data Center。