这个项目能做什么
# Zentra CLI
Zentra 是一款开源、AI 驱动的应用安全 CLI，专为开发者设计。它通过框架分析、威胁建模、静态分析（SAST）、供应链、API 和基础设施即代码（IaC）扫描器来扫描代码库中的安全风险。它支持本地运行，提供交互式终端界面，也可在 CI 流水线中无头运行。二进制文件名为 `zentra`。
## 功能特性
- **无头 CI 模式**，适用于 GitHub Actions 和 GitLab 合并请求流水线。
- **LLM 驱动的扫描编排**，支持 Anthropic、兼容 OpenAI 的提供商、Claude CLI 及实验性 Codex CLI 提供商。
- **动态浏览器渗透测试模式**，适用于授权目标。
- **多种输出格式**：Markdown、JSON、SARIF 和样式化 HTML，输出至 `.zentra/` 目录。
- **静态加密的凭据存储**（Windows 上使用 DPAPI，Unix 上使用 `0600` 权限文件）。
## 安装
### 快速安装（推荐）
无需 Rust 工具链、仓库克隆或构建步骤。
```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.sh | sh
```
对于 Windows PowerShell：
```powershell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.ps1 | iex"
```
之后打开新的终端窗口，以便 `zentra` 可用。如需手动安装，请从 [Releases 页面](https://github.com/johannus22/zentra/releases) 下载构建版本。
> **Linux 注意事项：** 该二进制在运行时链接 `libdbus` 以访问系统钥匙串。在最小化或无头镜像上，请先安装它（`sudo apt-get install -y libdbus-1-3` 或等效命令）。或者，设置 `ZENTRA_NO_OS_KEYCHAIN=1` 以使用基于加密文件的凭据存储。
### 从源码安装
本地构建并运行：
```bash
cargo build
```
从仓库检出安装二进制：
```bash
cargo install --path .
```
## 使用方法
TUI 是本地配置提供商、启动扫描和查看结果的主要体验。主菜单分组显示静态应用安全测试（SAST）、动态应用安全测试（DAST）和杂项操作。
### 扫描命令
仅运行一个扫描器家族：
```bash
zentra scan --only sast
zentra scan --only supply-chain
zentra scan --only api
zentra scan --only iac
```
使用 `--pack` 为每个扫描器提供经过上下文检查的仓库打包。扫描状态存储于 `.zentra/checkpoint.json` 以支持增量运行。SAST 最多可使用 50 轮 ReAct 提供商；其他扫描器最多使用 30 轮。
本地 `zentra scan` 运行包含一个永久的只读聊天面板。聊天回答有界且经过编辑的扫描和仓库问题，使用只读配置文件（`list_files`、`read_file`、`grep_code` 和有界 Git 命令）。它可以建议类型化的聚焦/重跑或漏洞类别操作，但模型输出或工具调用均无法在本地确认前应用这些操作。确认的操作存储在检查点中，仅在下次扫描时应用。聊天在 `zentra ci` 或其他无头扫描路径中不可用。
### CI 安全扫描
Zentra 包含专用 CI 命令：
```bash
zentra ci
```
`zentra ci` 并非 `zentra scan` 的别名。它检测 GitHub Actions 或 GitLab CI，确认作业在 PR/MR 流水线中运行，运行聚焦安全扫描器（无 TUI），写入 CI 工件，并仅针对达到或超过失败阈值的发现或扫描器/系统失败而失败。
默认情况下，`zentra ci` 会在任何 **严重或高** 级别发现时阻止 PR/MR。中、低和信息级发现会被报告但不会导致作业失败。
#### 失败阈值
设置 `ZENTRA_CI_FAIL_THRESHOLD` 环境变量（取值为 `critical`、`high`、`medium`、`low`、`info` 之一），或使用 `.zentra/config.json` 中的 `fail_threshold` 字段持久化该策略。
GitHub Actions 作业示例：
```yaml
- name: Run Zentra CI
env:
ZENTRA_API_KEY: ${{ secrets.ZENTRA_API_KEY }}
ZENTRA_PROVIDER_MODEL: ${{ vars.ZENTRA_PROVIDER_MODEL }}
ZENTRA_CI_FAIL_THRESHOLD: critical
run: zentra ci
```
#### GitLab CI
GitLab CI 工作流附带第二个作业，用于推送至 `staging` 的流水线。它运行完整仓库扫描，绝不使流水线失败，并创建或更新一个带有 `security` 和 `zentra-triage` 标签的 GitLab Issue。使用具有 `api` 范围的个人访问令牌作为遮蔽的 CI/CD 变量。
CI 工件位于 `.zentra/ci-report.md`、`.zentra/ci-report.json` 和 `.zentra/ci-report.html`。
#### CI 环境变量
| 变量 | 必需 | 说明 |
|----------|----------|-------|
| `ZENTRA_API_KEY` | 是 | 机密——LLM 提供商 API 密钥 |
| `ZENTRA_PROVIDER_BASE_URL` | 是 | 机密或变量——例如 `https://api.anthropic.com` |
| `ZENTRA_PROVIDER_MODEL` | 是 | 变量——例如 `claude-sonnet-5` |
| `ZENTRA_PROVIDER_KIND` | 否 | 默认为 `openai_compat` |
| `ZENTRA_PROVIDER_REASONING_EFFORT` | 否 | 传递给兼容 OpenAI 的提供商 |
| `ZENTRA_PROVIDER_CONTEXT_WINDOW` | 否 | 覆盖提供商的默认上下文窗口 |
| `ZENTRA_CI_FAIL_THRESHOLD` | 否 | 阻止 PR 的最低严重级别 |
如果 `ZENTRA_API_KEY`、`ZENTRA_PROVIDER_BASE_URL` 或 `ZENTRA_PROVIDER_MODEL` 均未设置，`zentra ci` 将回退到通过 `zentra config setup` 配置在 `~/.zentra/config.toml` 中的配置文件。
### 生成 CI 工作流
```bash
zentra init --ci github # 创建 GitHub Actions 工作流
zentra init --ci gitlab # 创建 GitLab CI 作业
```
### 渗透测试模式
Zentra 包含针对实时 Web 目标的授权动态渗透测试模式：
```bash
zentra pentest --url https://target.example --authorized \
--allow-host target.example \
--allow-host api.target.example
```
`--authorized` 标志是必需的，因此意外扫描将默认失败关闭。仅对您拥有或明确获准测试的系统运行此模式。使用 `--exclude-path` 排除路径，使用 `--scope-domain` 允许某个域及其所有子域。
渗透测试模式使用 `zentra/pentest-sandbox:0.1.0` Docker 镜像作为其隔离工具链。设置 `ZENTRA_SANDBOX_IMAGE` 和 `ZENTRA_SANDBOX_VERSION` 以使用自定义镜像。一次渗透测试运行使用三个沙盒代理（侦察、利用、验证），并生成包含 CVSS v3.1 基础向量的报告。
输出目录：
- 在已初始化的项目内：`./.zentra/pentest/<host>/<run-id>/`
- 在项目外：`<Documents>/Zentra/pentest/<host>/<run-id>/`（或配置的 `output_dir`）
### 其他命令
```bash
zentra init # 创建 .zentra/config.json
zentra scan --only sast # 运行一个扫描器家族
zentra ci # 无头 PR/MR CI 扫描
zentra ci --refresh-architecture
zentra ci --full --report-only # 完整扫描而不阻止 staging 流水线
zentra security verify-audit [session]
```
## 安全说明
- Zentra 将提供商凭据存储在项目目录之外加密的机密存储中。DPAPI 保护 Windows 上的数据加密密钥；Unix 使用严格的文件权限和可用的钥匙串后端。
- 文件工具阻止路径遍历并限制文件读取。
- 交互式聊天使用独立的有界只读工具配置文件。
- 默认安全外壳记录防篡改的审计链，门控工具调用，并标记不受信任的工具输出。设置 `ZENTRA_SECURITY=hardened` 以强制响应绑定和注入中止；仅对受信任的本地开发使用 `ZENTRA_SECURITY=off`。
- 使用 `zentra security verify-audit [session]` 验证审计链。
- 当所需二进制或历史不可用时，Git 历史和依赖审计工具会优雅降级。
## 项目结构
- `.zentra/config.json` — 项目配置
- `.zentra/checkpoint.json` — 增量运行的扫描状态
- `.zentra/reports/findings.html` — HTML 报告
- `.zentra/architecture.md` — 框架分析输出，用作 CI 上下文
请勿将机密或扫描状态提交到版本控制中。
评论
0 评分人数达到10人后显示
登录后参与讨论。