xygeni/xygeni-action
GitHub: xygeni/xygeni-action
将Xygeni安全扫描器集成到GitHub Actions工作流中，实现CI/CD过程中的自动化代码安全检测与合规审计。
Stars: 5 | Forks: 0
[](https://github.com/xygeni/xygeni-action/releases/latest)
# xygeni-action
Xygeni Scanner 的 GitHub Action。
- [简介](#introduction)
- [使用说明](#usage)
* [在 GitHub 中将 API token 设置为加密 secret](#setting-api-token-as-encrypted-secret-in-github)
* [在 workflow 中添加调用该 action 的步骤](#add-a-step-calling-the-action-to-a-workflow)
* [参数](#parameters)
## 简介
[GitHub Actions](https://docs.github.com/en/actions) 是 GitHub 仓库中用于持续集成的平台。
一个 action 封装了一个带有可配置参数的可复用任务。
Xygeni 提供了一个 `xygeni-action`，用于在 GitHub workflow 中下载并运行 scanner 作为其中一个步骤。
## 使用说明
`xygeni-action` 会在调用该 action 的仓库上下载、配置并执行 Xygeni Scanner。
### 在 GitHub 中将 API token 设置为加密 secret
scanner 需要 *API token* 才能与 Xygeni 平台通信。要在 Xygeni 平台注册，请在 [xygeni.io](https://xygeni.io/book-a-demo) 进行注册。
此类 API token 是一个 secret，可以使用 [GitHub Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) 在适当的作用域（组织、仓库或环境）内安全地注册。
例如，要将 API token 注册为名为 `XYGENI_TOKEN` 的 secret，用于当前工作目录下的仓库，你可以使用 GitHub `gh` 命令：
```
# 该命令将提示您输入 secret 值
gh secret set XYGENI_TOKEN
# 或者，您可以从本地文件读取 API token 的值
gh secret set XYGENI_TOKEN < /path/to/xygeni_token.txt
```
（创建仓库 secret 需要你是仓库所有者。）
要在个人账户仓库的环境作用域内创建加密 secret（你需要是仓库所有者），请添加 `--env ENV_NAME`：
```
# 设置 secret 仅对私有 repositories 可用
gh secret set --env ENV_NAME XYGENI_TOKEN
```
要在组织作用域内创建加密 secret（以便该 secret 对所有或部分组织仓库可用），请添加 `--org ORG_NAME`：
```
# GitHub CLI 默认没有 admin:org 权限
gh auth login --scopes "admin:org"
# 设置 secret 仅对私有 repositories 可用
gh secret set --org ORG_NAME XYGENI_TOKEN
# 或者设置 secret 对所有 organization repositories 可用
gh secret set --org ORG_NAME XYGENI_TOKEN --visibility all
# 或者将 secret 的可见性限制为选定的 repos
gh secret set --org ORG_NAME XYGENI_TOKEN --visibility selected --repos repo1,repo2
```
你也可以使用相应的 GitHub 网页，在适当的作用域内将 api token 设置为名为 `XYGENI_TOKEN` 的 secret。
### 在 workflow 中添加调用该 action 的步骤
在 GitHub workflow（`.github/workflows/*.yml`）中，可以在仓库文件上运行 Xygeni scanner，
通常在 `actions/checkout` 检索分支源代码之后运行。
当使用 checkout action 时，`GITHUB_WORKSPACE` 环境变量将包含仓库的默认位置。
你可以使用以下形式配置 GitHub action：
```
on:
workflow_dispatch:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
jobs:
xygeni-scan:
runs-on: ubuntu-latest
name: xygeni-github-action
steps:
# Checkout the repository sources (GITHUB_WORKSPACE)
- name: Checkout
# You may instead pin to an action SHA
uses: actions/checkout@v6
with:
# The default depth of 1 commit is not enough for some scans
fetch-depth: 0
- name: Xygeni-Scanner
uses: xygeni/xygeni-action@v6
id: Xygeni-Scanner
with:
token: ${{ secrets.XYGENI_TOKEN }}
```
其中 `XYGENI_TOKEN` 是保存了 API token 的加密 secret 的名称。
### 参数
只有 API token 是必需的。
某些参数的默认值可以更改。例如，你可以为项目指定特定名称，而不是使用 GitHub 仓库名称 (GITHUB_REPOSITORY)。此外，你可能希望扫描特定的源代码子目录，而不是默认目录。
你可以在[这里](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables)查看更多关于默认 GitHub 环境变量的信息。
该 action 的可用参数如下：
| Parameter | Description | Mandatory | Default value |
|----------------------|---------------------------------------------------------------------------------------|:---------:|----------------------------------|
| token | 用于 Xygeni 平台认证的 API token。 | true | |
| command | scanner 执行的命令。 | false | `scan --never-fail` |
| gh_token | 用于检索仓库信息（针对 misconfigurations 和 compliance）的 GitHub token。 | false | `$GITHUB_TOKEN` |
| xygeni_url | Xygeni API 的 Base URL。 | false | `https://api.xygeni.io` |
| xygeni_dashboard_url | Xygeni Dashboard 的 Base URL。 | false | `https://in.xygeni.io/dashboard` |
仅扫描 `app` 子目录中的硬编码 secret 和 IaC 缺陷，并且仅在发现严重问题时才使构建失败的示例：
```
- name: Xygeni-Scanner
# Recommended: use commit SHA instead
uses: xygeni/xygeni-action@v6
id: Xygeni-Scanner
with:
token: ${{ secrets.XYGENI_TOKEN }}
command: scan -n ${{ github.repository }} -d app --run=secrets,iac --fail-on=critical
```
有关可用的 `command` 选项的完整信息，请参阅 [Xygeni scan command](https://docs.xygeni.io/xygeni-scanner-cli/xygeni-cli-overview/xygeni-cli-operation-modes/single-scan)。
## 安全性
### Checksum 校验
该 action 通过将下载的 scanner 的 SHA-256 checksum 与 [xygeni/xygeni](https://raw.githubusercontent.com/xygeni/xygeni/main/checksum/latest/xygeni-release.zip.sha256) 上发布的值进行比对，自动验证其完整性。如果 checksum 不匹配，该 action 将失败且不会安装 scanner。此验证是强制性的，无法禁用。
Xygeni-action 遵循良好的安全实践，但无法保证 100% 的安全。Xygeni-action 是按**“原样”**提供的，不提供任何**担保**。请自行承担使用风险。
有关如何报告安全问题的更多信息，请参阅我们的[安全文档](SECURITY.md)。
标签：API Token, Cutter, DevSecOps, GitHub Action, Secrets管理, URL发现, Xygeni, 上游代理, 云安全监控, 安全检测, 工作流, 开源框架, 持续集成, 文档安全, 静态分析