github/ghas-jira-integration

# 将 GitHub Code Scanning 警报同步到 Jira 问题 [GitHub 的 REST API](https://docs.github.com/en/rest) 和 [webhooks](https://docs.github.com/en/developers/webhooks-and-events/about-webhooks) 允许用户通过 API 端点获取数据和/或向托管服务器接收 webhook POST 请求，从而让客户可以选择将警报导出到任何问题跟踪器。 ## 此存储库 此存储库提供了一个简短的说明性示例，演示如何将 GitHub Code Scanning 与 Jira 集成。该代码旨在作为一个概念验证，展示了处理来自 GitHub 传入请求所需的基本操作。请随意将此作为您自己集成的起点。 ## 使用 GitHub Action 使用此工具最简单的方法是通过其 GitHub Action，您可以将其添加到您的工作流中。以下是开始之前需要准备的内容： * 一个启用了 Code Scanning 并带有一些警报的 GitHub 存储库。请按照[此指南](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/setting-up-code-scanning-for-a-repository)设置 Code Scanning。 * 您的 Jira Server 实例的 URL。 * 一个用于存储您的问题的 [Jira 项目](https://confluence.atlassian.com/adminjiraserver/creating-a-project-938846813.html)。您需要向 action 提供其 `project key`。（必须是 Scrum 项目类型；Kanban 类型无效。） * 一个对上述项目具有以下权限的 Jira Server 账户（用户名 + 密码）： * `Browse Projects` * `Close Issues` * `Create Issues` * `Delete Issues` * `Edit Issues` * `Transition Issues` * 根据您运行工作流的位置，必须可以从 [GitHub.com IP 地址](https://docs.github.com/en/github/authenticating-to-github/about-githubs-ip-addresses) 或您的 GitHub Enterprise Server 实例的地址访问 Jira Server 实例。 请确保将所有凭据安全地存储为 [GitHub Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets)。为了访问 Code Scanning 警报数据，该 action 使用了为您自动创建的 [GITHUB_TOKEN](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#using-the-github_token-in-a-workflow)，因此您无需提供它。最后，在您的存储库中设置以下工作流，例如，通过添加文件 `.github/workflows/jira-sync.yml`： ``` name: "Sync GHAS to Jira" on: schedule: - cron: '*/10 * * * *' # trigger synchronization every 10 minutes jobs: test_job: runs-on: ubuntu-latest steps: - name: Sync alerts to Jira issues uses: github/ghas-jira-integration@v1 with: jira_url: '' jira_user: '${{ secrets.JIRA_USER }}' jira_token: '${{ secrets.JIRA_TOKEN }}' jira_project: '' sync_direction: 'gh2jira' ``` 此 action 会通过创建、删除或更改相应 Jira 问题的状态，将任何更改（新警报、警报被删除、警报状态更改）推送到 Jira。字段 `sync_direction` 有两个同步方向： - `gh2jira` - `jira2gh` 使用 `gh2jira` 表示警报将从 GitHub 同步到 Jira。如果您将 `sync_direction` 设置为 `jira2gh`，它将反向同步。 目前，通过该 action 尚无法实现双向集成。如果您需要此功能，请使用 CLI 的 `serve` 命令（见下文）。 #### 使用此 Action 同步 secret scanning 警报 在私有存储库中，只能使用 API 查询 Secret scanning 警报。对于公共存储库，结果将只是一个空列表。您需要通过具有管理员权限的 `github_token` 传入 PAT，才能访问 secret scanning 警报。确保该 PAT 具有 `security_events` 范围： ``` with: jira_url: '' jira_user: '${{ secrets.JIRA_USER }}' jira_token: '${{ secrets.JIRA_TOKEN }}' jira_project: '' github_token: '${{ secrets.PERSONAL_ACCESS_TOKEN }}' sync_direction: 'gh2jira' ``` #### 此 Action 的其他可选功能 ##### 标签 您还可以为创建的 Jira 问题创建标签。通过在工作流中使用下面的 yaml 示例，您可以使用多个标签，并且空格将被保留。例如，如果您添加 `red-team, blue team`，将会创建 'red-team' 和 'blue team' 标签。如果在工作流中更新了此输入，现有的 Jira 问题也会更新为相同的标签。 ``` with: jira_labels: 'red-team,blue-team,green-team' ``` ##### 自定义转换状态（结束，重新开启） 如果您的 Jira 工作流不使用默认的关闭/重新开启状态，您可以自定义结束和重新开启状态。 ``` with: issue_end_state: 'Closed' issue_reopen_state: 'red-team-followup' ``` ## 使用 CLI 的 `sync` 命令 ### 安装 运行 CLI 最简单的方法是使用 `pipenv`： ``` pipenv install pipenv run ./gh2jira --help ``` 注意：`gh2jira` 至少需要 `python3.5`。 除了[常规要求](#using-the-github-action)之外，您还需要： * GitHub API 的 URL，即： * 如果您的存储库位于 GitHub.com，则为 https://api.github.com * 如果您的存储库位于 GitHub Server 实例，则为 https://your-hostname/api/v3/ * 一个 GitHub `personal access token`，以便程序可以从您的存储库获取警报。请按照[此指南](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)获取专用令牌。它必须至少具有 `security_events` 范围，并且必须具有管理员权限才能访问 secret scanning 警报。 ``` pipenv run ./gh2jira sync \ --gh-url "" \ --gh-token "" \ --gh-org "" \ --gh-repo "" \ --jira-url "" \ --jira-user "" \ --jira-token "" \ --jira-project "" \ --direction gh2jira ``` 注意：您可以设置 `GH2JIRA_GH_TOKEN` 和 `GH2JIRA_JIRA_TOKEN` 环境变量，以代替 `--gh-token` 和 `--jira-token` 选项。上述命令可以通过 cronjob 每 X 分钟调用一次，以确保问题和警报保持同步。 #### CLI 的其他可选功能 您可以使用一个可选参数在 Jira 问题中创建标签。如前所述，双引号内的空格将被保留并保存。与 GitHub Actions 方式一样，使用 CLI 时自定义转换状态也是可选的。 ``` --jira-labels "red-team,blue-team,green-team" --issue-end-state "Closed" --issue-reopen-state "blue-team-reopen" ``` 以下是一个双向集成的示例： ``` pipenv run ./gh2jira sync \ --gh-url "" \ --gh-token "" \ --gh-org "" \ --gh-repo "" \ --jira-url "" \ --jira-user "" \ --jira-token "" \ --jira-project "" \ --state-file myrepository-state.json \ --direction both ``` 在这种情况下，存储库的状态存储在一个 JSON 文件中（如果该文件尚不存在，将会被创建）。或者，也可以通过 `--state-issue -` 将状态存储在专用的 Jira 问题中（这将在同一 Jira 项目中自动生成并更新一个存储问题）。如果存储问题应该位于单独的 Jira 项目中，您可以指定 `--state-issue KEY-OF-THE-STORAGE-ISSUE`。 ## 其他 CLI 同步选项

serve 命令

## 使用 CLI 的 `serve` 命令 以下方法是最复杂的一种，但目前是唯一一种允许双向集成（即对 Code Scanning 警报的更改会触发对 Jira 问题的更改，反之亦然）的方法。它使用轻量级的 `Flask` 服务器来处理传入的 Jira 和 GitHub webhook。该服务器仅作示例用途，并非生产就绪。 除了[常规要求](#using-the-github-action)之外，您还需要： * 一台具有可从 GitHub.com 或您的 GitHub Enterprise Server 实例以及您的 Jira Server 实例访问地址的机器。此机器将运行该服务器。 * 在 GitHub 和 Jira 上都设置 Webhook。在 GitHub 上，只有存储库或组织所有者才能执行此操作。在 Jira 上，则需要管理员权限。 * 一个用于验证 webhook 请求的密钥。 首先，[创建一个 GitHub webhook](https://docs.github.com/en/developers/webhooks-and-events/creating-webhooks) 并设置以下事件触发器： * [Code scanning alerts](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#code_scanning_alert) * [Repositories](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#repository) 这可以是存储库范围的或组织范围的 hook。将 `Payload URL` 设置为 `https:///github`，将 `Content type` 设置为 `application/json` 并插入您的 webhook `Secret`。确保 `Enable SSL verification` 被勾选。 其次，[在 Jira 上注册一个 webhook](https://developer.atlassian.com/server/jira/platform/webhooks/#registering-a-webhook)。为您的 webhook 提供一个 `Name` 并输入 `URL`：`https:///jira?secret_token=`。在 `Events` 部分指定 `All issues` 并勾选 `created`、`updated` 和 `deleted` 框。点击 `Save`。 最后，启动服务器： ``` pipenv run ./gh2jira serve \ --gh-url "" \ --gh-token "" \ --jira-url "" \ --jira-user "" \ --jira-token "" \ --jira-project "" \ --secret "" \ --port 5000 \ --direction both ``` 这将启用 GitHub 和 Jira 之间的双向集成。注意：您可以设置 `GH2JIRA_SECRET` 环境变量，以代替 `--secret` 选项。

## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) ## 许可证 [Apache V2](LICENSE)

标签：DevSecOps, FTP漏洞扫描, GitHub Actions, GPT, Jira, Linux 内核安全, REST API, Webhook, 上游代理, 力导向图, 同步, 安全告警, 安全编排, 工作流, 开源, 服务器, 漏洞管理, 网络调试, 自动化, 自动笔记, 软件开发, 逆向工具, 问题追踪, 集成, 项目管理