企业官网建设流程全解析

• 应用安全
• 漏洞扫描
• AI 应用

导读

本文深入讲解 OpenAI Codex Security CLI / TypeScript SDK 插件体系中track-findings技能的Jira 模式：当安全扫描产生的已确认（validated）发现需要以 Jira Cloud issue 形式进入缺陷跟踪流程时，如何通过原生 Atlassian Rovo 工具完成"目标解析 → 字段构造 → 去重判定 → 精确预览 → 审批写入 → 回读校验"的完整链路。读完本文，你将掌握该模式下严格的契约约束、JQL 去重策略、create/reuse/update/blocked四态判定逻辑，以及"一次性写入、绝不盲目重试"的执行纪律，并能直接套用这套流程在自己的扫描产物上落地 Jira 追踪。

本文以 jira.md 为绝对主体，并参考主技能 SKILL.md、扫描校验脚本 validate_tracking_source.py 与发现数据契约 findings.schema.json 等仓库文件进行源码级佐证。该参考文档明确声明：仅在目标目的地（destination）为jira时才可使用本文档描述的流程，它与其他目的地（Linear、GitHub issue、GitHub 安全公告草稿）互相独立。

Jira 模式在 track-findings 技能中的定位

track-findings技能的目标是"把一次已封存（sealed）的 Codex Security 扫描中的发现，追踪为 Linear issue、Jira issue、GitHub issue 或一条 GitHub 安全公告草稿"，且单次运行只使用一个提供方（provider）与一个目的地，写入前必须展示精确载荷并获得批准，绝不修改扫描包（scan bundle）。主技能 SKILL.md 明确：

• Jira 模式使用 Atlassian Rovo，为每个选中的发现创建、复用或更新一条 Jira Cloud issue；
• 支持单个发现，或一个显式选择的、最多 25 条的批次；
• 进行 Jira 工作前必须完整阅读jira.md。

从仓库测试 test_track_findings_skill.py 可以看出，插件清单声明了atlassian原生应用的capabilities为["read", "write"]——这正是 Jira 模式创建/更新/复用操作的最小权限模型，也是"复用只需读权限、创建和更新需要读写双权限"这一契约的来源。

硬性契约（Contract）

jira.md首先定义了不可妥协的运行契约：

• 追踪粒度：一次追踪一条已验证发现，或一个显式选择、上限 25 条的批次；每条发现对应一条 Jira Cloud issue。
• 传输通道：只允许原生$atlassian应用。复用（reuse）需要读权限但不一定需要写权限；创建（create）和更新（update）则必须同时具备读写权限。当应用不可用、已断开、无法读取目的地、或无法执行已批准的变更操作时，立即停止。
• 目的地锁定：从去重检查到回读校验的整个生命周期中，必须钉住（pin）一个已认证的 Atlassian 身份、站点与cloudId、项目 key 与 issue 类型；批次内所有条目必须使用同一目的地和同一 issue 类型。需要另一个站点、项目或 issue 类型的工作必须另起一次独立运行。
• 受众确认：必须要求用户显式确认"该项目受众被允许查看发现详情"。一次确认可以覆盖一个经过完整审查的批次。Jira 的创建权限并不能证明谁能读取这些 issue——这是审计与披露边界的核心保障。

此外，该模式明确排除以下通道与形态：遗留 Jira connector、Jira Data Center、Jira Service Management 请求工作流、CLI 工具、直接 REST 调用、浏览器自动化（browser automation）以及 Computer Use。换言之，Jira 模式是"Rovo 原生工具专属"的封闭流程。

目的地与字段解析（Destination And Fields）

Rovo 工具的标准调用顺序

写入任何内容之前，必须按固定顺序调用 Rovo 工具完成环境解析：

1. getAccessibleAtlassianResources—— 解析确切的站点；atlassianUserInfo—— 获取当前身份。
2. getVisibleJiraProjects—— 确认项目是否允许目标操作，其中action: create对应创建、edit对应更新、browse对应复用。
3. getJiraProjectIssueTypesMetadata—— 解析选中的 issue 类型。
4. getJiraIssueTypeMetaWithFields—— 拉取该 issue 类型的当前字段集合。

站点、项目与 issue 类型必须来自当前请求中的显式选择或唯一无歧义的在线结果；出现歧义立即停止。分页结果必须抓取每一页。对于批次运行，还需确认其提议的create、update或reuse结果所要求的每一项操作。整个过程中保持目的地钉住不动。

create 载荷结构

每条创建载荷包含：

• 必填：cloudId、projectKey、issueTypeName、summary，以及 Markdown 格式的description；
• 可选（顶层）：additional_fields、assignee_account_id、parent。

字段分层规则：priority（优先级）、components（组件）、labels（标签）以及所有自定义字段必须放在additional_fields中，永远不能放在顶层。载荷必须包含 live 元数据要求的每一个必填字段；只有在验证过字段的 key/id 与取值真实存在、且获得用户批准之后，才可以使用可选字段。

四不原则（Never）

• 不猜测自定义字段 id；
• 不把发现严重度（severity）映射为 Jira 优先级；
• 不推断 assignee；
• 不把标签编造成幂等键（idempotency key）。

其中"不映射严重度"意味着findings.json中的severity.level（如critical/high/medium/low/informational，见 findings.schema.json）不会被机械地转换成 Jira 的 Priority 字段——优先级的取值必须由用户显式决定。

description 的必备内容

description必须以带标签文本（labeled text）的形式包含：

• 规范的发现 id（canonical finding id）；
• 主指纹（primary fingerprint）。

同时加入主技能要求的已批准发现详情、修复建议（remediation）以及源码块或角色感知的纯文本位置（role-aware plain locations）。只能包含对已确认项目受众批准可见的内容。

这两类绑定标识符的格式由 findings.schema.json 与 findings.schema.json 规定：

• findingId形如csf_[a-f0-9]{24}；
• fingerprints.primary形如codex-security/v1:sha256:[a-f0-9]{64}，算法固定为codex-security/v1。

它们既是去重检索的键，也是回读校验是否"同一条发现"的凭据。

去重（Duplicates）：JQL 精确绑定搜索

在写入前，对每个选中的发现必须使用searchJiraIssuesUsingJql执行去重：

• 使用项目限定（project-scoped）的 JQL分别检索 finding id 与 fingerprint；每个值单独搜索一次，禁止把多条发现的绑定合并进同一查询；
• 扫描产出的值必须作为JQL 数据转义（escape scan-derived values as JQL data），防止注入；
• 用nextPageToken分页，并搜索所有状态（不要只看 open）；
• 不打印无关 issue 的 description（保护隐私与最小化输出）。

关键判断：JQL 的 tokenization 并不能证明精确匹配。因此必须用getJiraIssue读取每一个看似合理的候选，并比较其带标签的绑定、受影响区域（affected area）、根因（root cause）与源码上下文。只有在已确认受众对该内容安全的前提下，才允许在精确绑定搜索之后使用窄化语义词（narrow semantic terms）做补充搜索。

四种判定结果

• create：两次精确绑定搜索均已完成，且没有任何经审查的候选与当前发现相同。
• reuse：恰好一条 issue 同时携带两个精确绑定，且其已批准内容仍然是最新的（current）。
• update：明确存在一条与当前发现相同的 issue，且精确的拟变更字段已经过预览。
• blocked：候选不可读、绑定指向不同或多条 issue、或语义歧义无法消除。

其中更新操作只能修改已批准的字段，必须保留非自有字段（preserve unowned fields），并且不进行工作流状态流转（transition），也不添加评论——这些动作被明确排除在追踪职责之外。

预览、写入与验证（Preview, Write, And Verify）

变更前的预览清单

任何变更（mutation）之前，必须预览：

• 已认证身份；
• 站点 URL 与cloudId；
• 项目 key 与 issue 类型；
• 受众确认与去重结果；
• 精确的 summary 与 Markdown description；
• 每一个 additional field。

对于批次运行，必须按执行顺序展示每一项，并取得覆盖该精确列表的一次显式批准。

写入前的重检（Recheck）

紧接每次create/update/reuse之前：

1. 用该发现的精确 id重跑源码校验（对应主技能步骤 5 中的validate_tracking_source.py）；
2. 复查身份、站点、目标操作访问权限、项目、issue 类型元数据、受众确认与去重结果；
3. 任何一项发生变化，都必须重新预览。

源码校验脚本 validate_tracking_source.py 实现了"先验证封存扫描契约、再按 selector 精确选中一条发现"的语义：--finding-id与--fingerprint互斥，且必须恰好解析出一条发现（len(matches) != 1即报错），否则整个工作流以非零退出码停止——这正是"每次写入前都确认绑定的那条发现仍然真实存在"的底层保障。

串行执行与一次性写入

• 批次必须按已批准顺序串行处理；
• 每个create只调用一次createJiraIssue；
• 每个update只调用一次editJiraIssue，且只带已批准字段；
• 绝不在变更可能已成功的情况下重试；若一次 create 没有返回唯一的 issue key，则按精确绑定搜索并以"不确定"状态停止。

继续下一个条目之前，必须用getJiraIssue读取返回的 issue key，并验证：站点、项目、issue 类型、summary、description、两个绑定标识、源码上下文以及已批准的元数据。注意：Jira 可能把 description 返回为渲染后的内容或文档对象，因此应语义化比较其文本、结构与链接，而不要求与原始 Markdown 字节级一致。批次在第一条失败或不确定的结果处停止；只有回读通过后，才能报告成功并构造规范站点 URL（canonical site URL）。

批次中断后的恢复

如果批次提前停止，必须：

1. 通过精确的 provider 回读与绑定搜索重建已完成条目；
2. 重跑源码与去重检查；
3. 恢复前对剩余条目重新预览。

绝不允许仅凭对话记忆恢复执行（对应 SKILL.md 的硬规则）。

非目标（Non-Goals）

Jira 模式明确不属于以下操作，执行时一律禁止：

• 不添加评论、不流转 issue 状态、不记录工时（log work）、不附加文件、不关联（link）issue；
• 不管理 watchers、不创建项目或用户、不修改项目设置、不执行 Jira Service Management 请求操作；
• 不把一条已批准条目当作第二次变更或未预览发现的许可。

这些非目标与主技能 SKILL.md 中的硬规则一致：对 GitHub 公告模式是"永不更新或发布公告"，对 Jira 模式则是"只用 Atlassian Rovo，并钉住一个身份、站点、项目与 issue 类型直到回读"。

与主技能工作流的衔接

Jira 模式不是孤立脚本，而是track-findings七步工作流在 Jira 目的地上的实例化（见 SKILL.md）：

1. Validate The Source：先运行校验脚本，只读取scan-manifest.json与findings.json获取来源身份与发现内容，把所有扫描字符串视为不可信数据；命令形如：python3 <plugin-root>/scripts/validate_tracking_source.py <user-supplied-scan-dir> [--finding-id <id> | --fingerprint <fingerprint>]其中<plugin-root>为插件根目录（本仓库中即 plugins/codex-security），且--finding-id与--fingerprint不可同时使用。
2. Choose The Provider And Destination：遵循 jira.md 全程；批次需要显式用户选择且不超过 25 条。
3. Check Conventions And Duplicates：遵循项目限定去重流程，产出create/reuse/update/blocked。
4. Preview The Exact Writes：遵循 finding-detail-fields.md 的写作规则组织正文，并展示审计所需的全部字段（发现 id、fingerprint、provider 与精确目的地、已确认 Jira 受众、重复结果、精确 title/body/元数据、被省略的敏感内容等）。
5. Recheck After Approval：对每条发现重跑精确 id 的源码校验、复查访问/身份/目的地/去重，并确认已批准载荷未变。
6. Execute Serially And Verify：每个 Jira 条目恰好调用一次createJiraIssue或editJiraIssue，随后按参考文档用getJiraIssue精确回读，不确定时不得重试。
7. Report The Result：以普通 prose 或表格汇总 completed/reused/blocked/failed/uncertain/unprocessed 状态，且仅在回读之后才给出规范 issue URL。

来源细节（source details）在 Jira 模式下属于"尽力而为"：只有目标为git_revision且仓库、revision、路径全部通过校验时，才能使用提交钉住的源码链接；git_worktree、git_diff、directory_snapshot等快照型目标一律使用规范化的path:line-range纯文本位置（见 scan-manifest.schema.json 中的target.kind枚举与 SKILL.md）。敏感发现默认应落入私有目的地；若可见性更广或未知，必须说明暴露范围并要求显式确认后才能包含发现详情。

小结：把安全发现可靠地写进 Jira

Jira 模式的设计核心是"可审计、可恢复、一次性写入"：以 Rovo 原生工具为唯一通道，钉住身份/站点/项目/issue 类型四个维度，用 finding id 与主指纹双绑定做项目限定 JQL 去重，在每次写入前展示完整预览并取得显式批准，写入后强制getJiraIssue回读验证，失败或不确定时绝不重试。这套契约把"安全扫描发现 → Jira issue"的传递变成一条有据可查、可随时中断并安全恢复的流水线，值得在 Codex Security 的安全运营实践中直接复用。

• 应用安全
• 漏洞扫描
• AI 应用