github/ghas-jira-integration

# 将 GitHub Code Scanning 告警同步至 Jira issues [GitHub 的 REST API](https://docs.github.com/en/rest) 和 [webhooks](https://docs.github.com/en/developers/webhooks-and-events/about-webhooks) 为客户提供了将告警导出到任何 issue 跟踪器的选项，允许用户通过 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。 * 一个用于存储您的 issues 的 [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 issues 的状态。字段 `sync_direction` 有两个同步方向： - `gh2jira` - `jira2gh` 使用 `gh2jira` 意味着告警将从 GitHub 同步到 Jira。如果您将 `sync_direction` 设置为 `jira2gh`，它将朝另一个方向进行同步。 目前，通过该 action 尚无法实现双向集成。如果您需要此功能，请使用 CLI 的 `serve` 命令（见下文）。 #### 使用此 Action 同步 secret scanning 告警 Secret scanning 告警只能在私有仓库中通过 API 查询。对于公共仓库，结果列表将为空。您需要通过 `github_token` 传入一个 PAT，该 PAT 必须具有访问 secret scanning 告警的管理员权限。请确保该 PAT 具有 `security_events` scope： ``` 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 issues 创建标签。通过在您的工作流中使用下面的 yaml 示例，您可以使用多个标签，并且空格将被保留。例如，如果您添加 `red-team, blue team`，将会创建 'red-team' 和 'blue team' 标签。如果工作流中的此输入被更新，现有的 Jira issues 也将使用相同的标签进行更新。 ``` 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)获取专用 token。它必须至少具有 `security_events` scope，并且必须具有访问 secret scanning 告警的管理员权限。 ``` pipenv run ./gh2jira sync \ --gh-url "" \ --gh-token "" \ --gh-org "" \ --gh-repo "" \ --jira-url "" \ --jira-user "" \ --jira-token "" \ --jira-project "" \ --direction gh2jira ``` 注意：除了使用 `--gh-token` 和 `--jira-token` 选项外，您还可以设置 `GH2JIRA_GH_TOKEN` 和 `GH2JIRA_JIRA_TOKEN` 环境变量。上述命令可以通过 cronjob 每隔 X 分钟调用一次，以确保 issues 和告警保持同步。 #### CLI 的其他可选功能 有一个可选参数可用于在您的 Jira issues 中创建标签。如前所述，双引号内的空格将被保留并保存。就像 GitHub Action 方式一样，使用 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 issue 中（这将自动在同一个 Jira 项目中生成并更新一个存储 issue）。如果存储 issue 应该位于单独的 Jira 项目中，您可以指定 `--state-issue KEY-OF-THE-STORAGE-ISSUE`。 ## 其他 CLI 同步选项

serve 命令

## 使用 CLI 的 `serve` 命令 以下方法是最复杂的一种，但目前唯一允许双向集成的方法（即对 Code Scanning 告警的更改会触发对 Jira issues 的更改，反之亦然）。它使用轻量级的 `Flask` 服务器来处理传入的 Jira 和 GitHub webhooks。该服务器旨在作为示例，并非可用于生产环境。 除了[常规要求](#using-the-github-action)之外，您还需要： * 一台可从 GitHub.com 或您的 GitHub Enterprise Server 实例以及您的 Jira Server 实例访问到其地址的机器。此机器将运行该服务器。 * 在 GitHub 和 Jira 上都设置 webhooks。在 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) 这可以是仓库或组织级别的 webhook。将 `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=<在此处插入 WEBHOOK SECRET>`。在 `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 之间的双向集成。注意：除了使用 `--secret` 选项外，您还可以设置 `GH2JIRA_SECRET` 环境变量。

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

标签：GitHub Actions, GPT, Jira, 安全运营, 开源框架, 扫描框架, 持续集成, 漏洞管理, 自动化集成, 自动笔记, 逆向工具