ZeroPathAI/zeropath-cli
GitHub: ZeroPathAI/zeropath-cli
ZeroPath CLI 是一款命令行安全扫描工具，提供代码漏洞检测与容器镜像扫描能力，方便团队将安全审查无缝接入 CI/CD 流水线。
Stars: 7 | Forks: 2
# ZeroPath CLI
ZeroPath CLI 提供对 ZeroPath AI 驱动的安全扫描平台的命令行访问。我们的扫描可检测：
- 身份验证与授权漏洞
- 应用逻辑缺陷
- 依赖问题及过时的包（基于 SCA 可达性）
- 安全配置错误
- 命令注入漏洞
- 文件包含与路径遍历攻击
- 密钥 / 硬编码凭据
- 容器镜像中存在漏洞的 OS 包及基础镜像
- **以及更多**
## 安装说明
### macOS Intel
```
wget https://github.com/ZeroPathAI/zeropath-cli/releases/latest/download/zeropath-macos -O zeropath
chmod +x zeropath
sudo mv zeropath /usr/local/bin/
```
### macOS ARM (Apple Silicon)
```
wget https://github.com/ZeroPathAI/zeropath-cli/releases/latest/download/zeropath-macos-arm64 -O zeropath
chmod +x zeropath
sudo mv zeropath /usr/local/bin/
```
### Linux x64
```
wget https://github.com/ZeroPathAI/zeropath-cli/releases/latest/download/zeropath-linux -O zeropath
chmod +x zeropath
sudo mv zeropath /usr/local/bin/
```
### Windows x64
```
# 使用 PowerShell 下载
Invoke-WebRequest -Uri https://github.com/ZeroPathAI/zeropath-cli/releases/latest/download/zeropath-windows.exe -OutFile zeropath.exe
# 添加到 PATH - 在命令提示符中以管理员身份运行
move zeropath.exe "C:\Windows\System32\"
```
## 使用说明
### 身份验证
使用您的 ZeroPath API 凭据进行身份验证：
```
zeropath auth
```
这会将凭据本地存储在 `~/.config/zeropath/credentials.json` 中。
对于 CI/CD 或其他自动化工作流，您也可以使用环境变量进行身份验证：
```
export ZEROPATH_API_TOKEN_ID=
export ZEROPATH_API_TOKEN_SECRET=
```
当这两个环境变量都被设置时，CLI 会自动使用它们，而无需运行 `zeropath auth`。
### 扫描
#### 本地目录扫描（输出 SARIF）
扫描本地目录并生成 SARIF 报告：
```
zeropath scan
```
#### 仓库扫描（使用现有仓库）
通过 ID 扫描已配置的仓库：
```
zeropath scan --repository-id
# 扫描特定分支
zeropath scan --repository-id --branch
```
#### 仓库扫描（通过 URL）
通过 URL 扫描仓库：
```
# GitHub 仓库
zeropath scan --repository-url https://github.com/owner/repo --vcs github
# GitLab 仓库
zeropath scan --repository-url https://gitlab.com/owner/repo --vcs gitlab
# Bitbucket 仓库
zeropath scan --repository-url https://bitbucket.org/owner/repo --vcs bitbucket
# 通用 Git 仓库
zeropath scan --repository-url https://git.example.com/repo --vcs generic
```
#### 按需代码扫描 Beta
使用 `scan-code` 提交 diff、文件、文件集或代码片段，进行异步安全审查，而无需启动完整的仓库扫描。
```
# 扫描当前 Git working-tree diff
zeropath scan-code --diff
# 扫描暂存的更改
zeropath scan-code --staged
# 扫描单个源文件
zeropath scan-code --file src/api.ts
# 扫描多个源文件
zeropath scan-code --files src/api.ts src/auth.ts
# 从 stdin 读取代码片段
cat route.ts | zeropath scan-code --stdin --language typescript
# 当你不需要关联的仓库上下文时，强制使用 standalone 模式
zeropath scan-code --diff --standalone
```
默认情况下，当恰好有一个可访问的 ZeroPath 仓库匹配时，`scan-code` 会使用您的 Git remote URL 自动应用关联的仓库上下文。如果没有匹配项，它将作为独立扫描运行。使用 `--repository-id` 可强制要求关联的仓库上下文，或使用 `--standalone` 强制进行没有仓库上下文的扫描。
每次调用必须且只能选择一个输入源：`--diff`、`--staged`、`--file`、`--files`、`--snippet` 或 `--stdin`。
#### 容器镜像扫描
扫描容器镜像以查找存在漏洞的 OS 包和依赖，并提供基础镜像升级建议。将 CLI 指向 registry 引用，或者为无法拉取的物理隔离镜像上传本地 tarball。
```
# 从 registry 扫描镜像并等待结果
zeropath container test ghcr.io/acme/api:1.4
# 扫描私有镜像（提供 registry 凭据）
zeropath container test ghcr.io/acme/api:1.4 \
--registry-username --registry-token
# 扫描本地镜像 tarball（物理隔离）：docker save -o api.tar ghcr.io/acme/api:1.4
zeropath container test --file api.tar --name acme-api
# 提交并启用定期重新扫描计划（默认为每天 UTC 03:00）
zeropath container monitor ghcr.io/acme/api:1.4 --schedule "0 3 * * *"
# 将跟踪的镜像链接到仓库（或在不同仓库之间移动）
zeropath container link --repository-id
```
默认情况下，CLI 会自动将扫描的镜像链接到与当前检出项的 Git remote 匹配的 ZeroPath 仓库；传入 `--repository-id` 可显式指定一个仓库，或传入 `--no-auto-repository` 以禁用此功能。与 `scan` 一样，当发现漏洞时，`container test` 会以退出代码 1 退出，因此它可以直接无缝接入 CI pipeline。Tarball 上传 (`--file`) 是一次性的 —— `monitor` 需要一个可以按计划重新拉取的 registry 引用。
#### CI/CD 集成
当发现漏洞时，仓库扫描和按需代码扫描会以退出代码 1 退出，这使其开箱即用地适配 CI：
```
# 扫描仓库（如果发现问题则以退出码 1 退出）
zeropath scan --repository-id
# 扫描特定分支
zeropath scan --repository-id --branch main
# 通过仓库 URL 扫描
zeropath scan --repository-url https://github.com/owner/repo --vcs github
# 仅扫描当前 Git diff 并输出 JSON 结果
zeropath scan-code --diff --json
# 扫描容器镜像（如果发现漏洞则以退出码 1 退出）
zeropath container test ghcr.io/owner/image:tag
```
**退出代码：**
- **0**：未发现漏洞
- **1**：检测到漏洞或命令失败（会导致 CI pipeline 失败）
### 命令选项
#### `zeropath scan` 选项
| 选项 | 描述 |
|--------|-------------|
| `--repository-id ` | 通过 ID 扫描现有仓库 |
| `--repository-url ` | 通过 URL 扫描仓库（需要指定 `--vcs`） |
| `--vcs ` | VCS 提供商：`github`、`gitlab`、`bitbucket` 或 `generic` |
| `--branch ` | 要扫描的分支 |
#### `zeropath scan-code` 选项
| 选项 | 描述 |
|--------|-------------|
| `--diff` | 扫描当前 Git 工作树 diff |
| `--staged` | 扫描当前暂存的 Git diff |
| `--file ` | 扫描单个源文件 |
| `--files ` | 扫描一个或多个源文件 |
| `--snippet ` | 扫描显式提供的代码片段文本；可重复使用以提交多个片段 |
| `--stdin` | 从 stdin 读取代码片段 |
| `--language ` | 用于文件或代码片段输入的语言提示 |
| `--label 标签：AI应用开发, CLI, WiFi技术, 文档结构分析, 请求拦截, 错误基检测, 静态代码分析