cycodehq/cycode-cli
GitHub: cycodehq/cycode-cli
一款集成 SAST、SCA、Secrets 和 IaC 扫描能力的命令行安全工具，帮助开发团队在编码阶段就发现并修复安全隐患。
Stars: 96 | Forks: 65
# Cycode CLI 用户指南
Cycode 命令行接口 (CLI) 是一款可本地安装的应用程序，用于扫描您的代码仓库以查找机密信息、基础设施即代码 配置错误、软件组成分析 (SCA) 漏洞以及静态应用安全测试 (SAST) 问题。
本指南将引导您完成安装和使用。
# 目录
1. [前置条件](#prerequisites)
2. [安装](#installation)
1. [安装 Cycode CLI](#install-cycode-cli)
1. [使用 Auth 命令](#using-the-auth-command)
2. [使用 Configure 命令](#using-the-configure-command)
3. [添加到环境变量](#add-to-environment-variables)
1. [在 Unix/Linux 上](#on-unixlinux)
2. [在 Windows 上](#on-windows)
2. [安装 Pre-Commit Hook](#install-pre-commit-hook)
3. [Cycode CLI 命令](#cycode-cli-commands)
4. [MCP 命令](#mcp-command-experiment)
1. [启动 MCP Server](#starting-the-mcp-server)
2. [可用选项](#available-options)
3. [MCP 工具](#mcp-tools)
4. [用法示例](#usage-examples)
5. [Scan 命令](#scan-command)
1. [运行扫描](#running-a-scan)
1. [选项](#options)
1. [严重性阈值](#severity-option)
2. [监控](#monitor-option)
3. [Cycode 报告](#cycode-report-option)
4. [包漏洞](#package-vulnerabilities-option)
5. [许可证合规性](#license-compliance-option)
6. [Lock Restore](#lock-restore-option)
2. [Repository 扫描](#repository-scan)
1. [Branch 选项](#branch-option)
3. [Path 扫描](#path-scan)
1. [Terraform Plan 扫描](#terraform-plan-scan)
4. [Commit History 扫描](#commit-history-scan)
1. [Commit Range 选项 (差异扫描)](#commit-range-option-diff-scanning)
5. [Pre-Commit 扫描](#pre-commit-scan)
6. [Pre-Push 扫描](#pre-push-scan)
2. [扫描结果](#scan-results)
1. [显示/隐藏机密信息](#showhide-secrets)
2. [软失败](#soft-fail)
3. [扫描结果示例](#example-scan-results)
1. [Secrets 结果示例](#secrets-result-example)
2. [IaC 结果示例](#iac-result-example)
3. [SCA 结果示例](#sca-result-example)
4. [SAST 结果示例](#sast-result-example)
4. [公司自定义修复指南](#company-custom-remediation-guidelines)
3. [忽略扫描结果](#ignoring-scan-results)
1. [忽略机密值](#ignoring-a-secret-value)
2. [忽略机密 SHA 值](#ignoring-a-secret-sha-value)
3. [忽略路径](#ignoring-a-path)
4. [忽略 Secret, IaC 或 SCA 规则](#ignoring-a-secret-iac-sca-or-sast-rule)
5. [忽略包](#ignoring-a-package)
6. [通过配置文件忽略](#ignoring-via-a-config-file)
6. [Report 命令](#report-command)
1. [生成 SBOM 报告](#generating-sbom-report)
7. [Import 命令](#import-command)
8. [扫描日志](#scan-logs)
9. [语法帮助](#syntax-help)
# 前置条件
- Cycode CLI 应用程序需要 Python 3.9 或更高版本。MCP 命令仅适用于 Python 3.10 及更高版本。如果您使用的是较早的 Python 版本，此命令将不可用。
- 使用 [`cycode auth` 命令](#using-the-auth-command) 通过 CLI 向 Cycode 进行身份验证
- 或者，您可以按照 [Service Account Token](https://docs.cycode.com/docs/en/service-accounts) 和 [Personal Access Token](https://docs.cycode.com/v1/docs/managing-personal-access-tokens) 页面中详述的步骤获取 Cycode Client ID 和 Client Secret Key，这些页面包含获取这些值的详细信息。
# 安装
以下安装步骤适用于 Windows 和 UNIX / Linux 操作系统。
## 安装 Cycode CLI
要在本地计算机上安装 Cycode CLI 应用程序，请执行以下步骤：
1. 打开您的命令行或终端应用程序。
2. 执行以下命令之一：
- 从 [PyPI](https://pypi.org/project/cycode/) 安装：
pip3 install cycode
- 从 [Homebrew](https://formulae.brew.sh/formula/cycode) 安装：
brew install cycode
- 从 [GitHub Releases](https://github.com/cycodehq/cycode-cli/releases) 安装，导航并下载适合您操作系统和架构的可执行文件，然后运行以下命令：
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
3. 最后对 CLI 进行身份验证。有三种方法可以设置 Cycode client ID 和凭据 (client secret 或 OIDC ID token)：
- [cycode auth](#using-the-auth-command) (**推荐**)
- [cycode configure](#using-the-configure-command)
- 将它们添加到您的 [环境变量](#add-to-environment-variables)
### 使用 Auth 命令
1. 在您的终端/命令行窗口中输入以下命令：
`cycode auth`
2. 将出现一个浏览器窗口，要求您登录 Cycode（如下所示）：
3. 在此页面上输入您的登录凭据并登录。
4. 您最终将被带到下面的页面，在该页面中，系统会要求您选择要授权 Cycode 使用的业务组（如果适用）：
5. 点击 **Allow** 按钮以授权 Cycode CLI 访问所选业务组。
6. 完成后，如果选择成功，您将看到以下屏幕：
7. 在终端/命令行屏幕中，当您退出浏览器窗口时，将看到以下内容：
`Successfully logged into cycode`
### 使用 Configure 命令
1. 在您的终端/命令行窗口中输入以下命令：
cycode configure
2. 输入您的 Cycode API URL 值（您可以留空以使用默认值）。
`Cycode API URL [https://api.cycode.com]: https://api.onpremise.com`
3. 输入您的 Cycode APP URL 值（您可以留空以使用默认值）。
`Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com`
4. 输入您的 Cycode Client ID 值。
`Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d`
5. 输入您的 Cycode Client Secret 值（如果您计划使用 OIDC ID token，请跳过）。
`Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e`
6. 输入您的 Cycode OIDC ID Token 值（可选）。
`Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...`
7. 如果值输入成功，您将看到以下消息：
`Successfully configured CLI credentials!`
或/和
`Successfully configured Cycode URLs!`
如果您进入用户文件夹下的 `.cycode` 文件夹，您会发现这些凭据已创建并放置在该文件夹的 `credentials.yaml` 文件中。
URL 放置在该文件夹的 `config.yaml` 文件中。
### 添加到环境变量
#### 在 Unix/Linux 上：
```
export CYCODE_CLIENT_ID={your Cycode ID}
```
以及
```
export CYCODE_CLIENT_SECRET={your Cycode Secret Key}
```
如果您的组织使用 OIDC 身份验证，您可以（或者额外）提供 ID token：
```
export CYCODE_ID_TOKEN={your Cycode OIDC ID token}
```
#### 在 Windows 上
1. 从控制面板导航到系统菜单：
2. 接下来，点击高级系统设置：
3. 在打开的系统属性窗口中，点击环境变量按钮：
4. 创建 `CYCODE_CLIENT_ID` 和 `CYCODE_CLIENT_SECRET` 变量，其值分别与您的 ID 和 Secret Key 匹配。如果您通过 OIDC 进行身份验证，请同时添加 `CYCODE_ID_TOKEN` 及您的 OIDC ID token 值：
5. 将 `cycode.exe` 插入路径以完成安装。
## 安装 Pre-Commit Hook
Cycode 的 pre-commit 和 pre-push hooks 可以在您的本地代码仓库中设置，以便 Cycode CLI 应用程序在您将代码提交或推送到代码库之前自动识别代码中的任何问题。
请执行以下步骤来安装 pre-commit hook：
### 安装 Pre-Commit Hook
1. 安装 pre-commit 框架（必须安装 Python 3.9 或更高版本）：
pip3 install pre-commit
2. 导航到您希望配置的本地 Git 仓库的顶级目录。
3. 在仓库的顶级目录中创建一个名为 `.pre-commit-config.yaml`（包含开头的 `.`）的新 YAML 文件，其中包含以下内容：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode
stages: [pre-commit]
4. 根据您的特定需求修改创建的文件。使用 hook ID `cycode` 启用 Secrets 扫描。使用 hook ID `cycode-sca` 启用 SCA 扫描。使用 hook ID `cycode-sast` 启用 SAST 扫描。如果要启用所有扫描类型，请使用以下配置：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode
stages: [pre-commit]
- id: cycode-sca
stages: [pre-commit]
- id: cycode-sast
stages: [pre-commit]
5. 安装 Cycode 的 hook：
pre-commit install
成功安装 hook 将导致消息：`Pre-commit installed at .git/hooks/pre-commit`。
6. 保持 pre-commit hook 为最新版本：
pre-commit autoupdate
它将自动把 `.pre-commit-config.yaml` 中的 `rev` 提升到 Cycode CLI 的最新可用版本。
### 安装 Pre-Push Hook
要安装 pre-push hook 以替代或补充 pre-commit hook：
1. 将 pre-push hooks 添加到您的 `.pre-commit-config.yaml` 文件中：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode-pre-push
stages: [pre-push]
2. 安装 pre-push hook：
pre-commit install --hook-type pre-push
3. 要同时使用 pre-commit 和 pre-push hooks，请使用：
pre-commit install
pre-commit install --hook-type pre-push
# Cycode CLI 命令
以下是 Cycode CLI 应用程序可用的选项和命令：
| 选项 | 描述 |
|---|---|
| `-v`, `--verbose` | 显示详细日志。 |
| `--no-progress-meter` | 不显示进度条。 |
| `--no-update-notifier` | 不检查 CLI 更新。 |
| `-o`, `--output [rich\|text\|json\|table]` | 指定输出类型。默认为 `rich`。 |
| `--client-id TEXT` | 为此特定扫描执行指定 Cycode client ID。 |
| `--client-secret TEXT` | 为此特定扫描执行指定 Cycode client secret。 |
| `--id-token TEXT` | 为此特定扫描执行指定 Cycode OIDC ID token。 |
| `--install-completion` | 为当前 shell 安装补全。 |
| `--show-completion [bash\|zsh\|fish\|powershell\|pwsh]` | 显示指定 shell 的补全，以复制或自定义安装。 |
| `-h`, `--help` | 显示给定命令的选项。 |
| 命令 | 描述 |
|---|---|
| [auth](#using-the-auth-command) | 验证机器以将 CLI 与您的 Cycode 帐户关联。 |
| [configure](#using-the-configure-command) | 配置 CLI 客户端身份验证的初始命令。 |
| [ignore](#ignoring-scan-results) | 忽略特定值、路径或规则 ID。 |
| [mcp](#mcp-command-experiment) | 启动 Model Context Protocol (MCP) 服务器，以启用与 Cycode 扫描功能的 AI 集成。 |
| [scan](#running-a-scan) | 扫描内容是否存在 Secrets/IaC/SCA/SAST 违规。您需要指定要执行的扫描类型：commit-history/path/repository 等。 |
| [report](#report-command) | 生成报告。您需要指定要执行的报告类型，如 SBOM。 |
| status | 显示 CLI 状态并退出。 |
# MCP 命令 \[实验性\]
Model Context Protocol (MCP) 命令允许您启动一个 MCP 服务器，将 Cycode 的扫描功能公开给 AI 系统和应用程序。这使得 AI 模型能够通过标准化协议与 Cycode CLI 工具进行交互。
[](https://cursor.com/en/install-mcp?name=cycode&config=eyJjb21tYW5kIjoidXZ4IGN5Y29kZSBtY3AiLCJlbnYiOnsiQ1lDT0RFX0NMSUVOVF9JRCI6InlvdXItY3ljb2RlLWlkIiwiQ1lDT0RFX0NMSUVOVF9TRUNSRVQiOiJ5b3VyLWN5Y29kZS1zZWNyZXQta2V5IiwiQ1lDT0RFX0FQSV9VUkwiOiJodHRwczovL2FwaS5jeWNvZGUuY29tIiwiQ1lDT0RFX0FQUF9VUkwiOiJodHRwczovL2FwcC5jeWNvZGUuY29tIn19)
## 启动 MCP Server
要启动 MCP 服务器，请使用以下命令：
```
cycode mcp
```
默认情况下，这会使用 `stdio` 传输启动服务器，这适用于可以生成子进程的本地集成和 AI 应用程序。
### 可用选项
| 选项 | 描述 |
|---|---|
| `-t, --transport` | MCP 服务器的传输类型：`stdio`、`sse` 或 `streamable-http`（默认：`stdio`） |
| `-H, --host` | 绑定服务器的主机地址（仅用于非 stdio 传输）（默认：`127.0.0.1`） |
| `-p, --port` | 绑定服务器的端口号（仅用于非 stdio 传输）（默认：`8000`） |
| `--help` | 显示帮助消息和可用选项 |
### MCP 工具
MCP 服务器提供以下供 AI 系统使用的工具：
| 工具名称 | 描述 |
|---|---|
| `cycode_secret_scan` | 扫描文件中的硬编码机密 |
| `cycode_sca_scan` | 扫描文件中的软件组成分析 (SCA) - 漏洞和许可证问题 |
| `cycode_iac_scan` | 扫描文件中的基础设施即代码 配置错误 |
| `cycode_sast_scan` | 扫描文件中的静态应用安全测试 (SAST) - 代码质量和安全缺陷 |
| `cycode_status` | 获取 Cycode CLI 版本、身份验证状态和配置信息 |
### 用法示例
#### 基本命令示例
使用默认设置（stdio 传输）启动 MCP 服务器：
```
cycode mcp
```
使用显式 stdio 传输启动 MCP 服务器：
```
cycode mcp -t stdio
```
使用 Server-Sent Events (SSE) 传输启动 MCP 服务器：
```
cycode mcp -t sse -p 8080
```
在自定义主机和端口上使用 streamable HTTP 传输启动 MCP 服务器：
```
cycode mcp -t streamable-http -H 0.0.0.0 -p 9000
```
在 [MCP Protocol Specification – Transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) 中了解更多关于 MCP 传输类型的信息。
#### 配置示例
##### 在 Cursor/VS Code/Claude Desktop 等工具中使用 MCP (mcp.json)
请按照 [此指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) 在您的 **VS Code/GitHub Copilot** 中配置 MCP 服务器。请记住，在 `settings.json` 中，有一个包含嵌套 `servers` 子对象的 `mcp` 对象，而不是独立的 `mcpServers` 对象。
对于 **stdio 传输**（直接执行）：
```
{
"mcpServers": {
"cycode": {
"command": "cycode",
"args": ["mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
```
对于使用 `pipx` 安装的 **stdio 传输**：
```
{
"mcpServers": {
"cycode": {
"command": "pipx",
"args": ["run", "cycode", "mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
```
对于使用 `uvx` 安装的 **stdio 传输**：
```
{
"mcpServers": {
"cycode": {
"command": "uvx",
"args": ["cycode", "mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
```
对于 **SSE 传输** (Server-Sent Events)：
```
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
```
对于自定义端口上的 **SSE 传输**：
```
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8080/sse"
}
}
}
```
对于 **streamable HTTP 传输**：
```
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}
```
##### 在后台运行 MCP Server
对于 **SSE 传输**（先启动服务器，然后配置客户端）：
```
# 在后台启动 MCP server
cycode mcp -t sse -p 8000 &
# 在 mcp.json 中配置
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
```
对于 **streamable HTTP 传输**：
```
# 在后台启动 MCP server
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &
# 在 mcp.json 中配置
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.2:9000/mcp"
}
}
}
```
### MCP 故障排除
如果您在使用 MCP 服务器时遇到问题，可以启用调试日志记录以获取有关正在发生的情况的更详细信息。有两种方法可以启用调试日志记录：
1. 使用 `-v` 或 `--verbose` 标志：
```
cycode -v mcp
```
2. 使用 `CYCODE_CLI_VERBOSE` 环境变量：
```
CYCODE_CLI_VERBOSE=1 cycode mcp
```
调试日志将显示有关以下内容的详细信息：
- 服务器启动和配置
- 连接尝试和状态
- 工具执行和结果
- 发生的任何错误或警告
此信息在以下情况下可能会有所帮助：
- 诊断连接问题
- 了解某些工具为何不起作用
- 识别身份验证问题
- 调试特定于传输的问题
# Scan 命令
## 运行扫描
Cycode CLI 应用程序提供多种类型的扫描，以便您可以选择最适合您情况的选项。以下是当前可用的选项和命令：
| 选项 | 描述 |
|---|---|
| `-t, --scan-type [secret\|iac\|sca\|sast]` | 指定您希望执行的扫描（`secret`/`iac`/`sca`/`sast`），默认为 `secret`。 |
| `--show-secret BOOLEAN` | 以明文形式显示机密。有关更多详细信息，请参阅 [显示/隐藏机密信息](#showhide-secrets) 部分。 |
| `--soft-fail BOOLEAN` | 运行扫描而不失败，始终返回非错误状态代码。有关更多详细信息，请参阅 [软失败](#soft-fail) 部分。 |
| `--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]` | 仅显示达到或超过指定级别的违规。 |
| `--sca-scan` | 指定您希望执行的 SCA 扫描（`package-vulnerabilities`/`license-compliance`）。默认为两者。 |
| `--monitor` | 指定时，扫描结果将记录在 Cycode 中。 |
| `--cycode-report` | 在控制台输出中显示指向 Cycode 平台中扫描报告的链接。 |
| `--no-restore` | 指定时，Cycode 将不会运行 restore 命令。这将仅扫描直接依赖项！ |
| `--gradle-all-sub-projects` | 为所有子项目运行 gradle restore 命令。这应该从...运行 |
| `--maven-settings-file` | 仅适用于 Maven，允许在扫描依赖项时使用自定义 [settings.xml](https://maven.apache.org/settings.html) 文件 |
| `--help` | 显示给定命令的选项。 |
| 命令 | 描述 |
|---|---|
| [commit-history](#commit-history-scan) | 扫描提交历史或在特定提交之间执行差异扫描 |
| [path](#path-scan) | 扫描命令中提供的路径中的文件 |
| [pre-commit](#pre-commit-scan) | 使用此命令扫描尚未提交的内容 |
| [repository](#repository-scan) | 扫描 git 仓库及其历史 |
### 选项
#### Severity 选项
要将扫描结果限制为特定严重性阈值，可以将参数 `--severity-threshold` 添加到扫描命令中。
例如，以下命令将扫描仓库中严重性为 Medium 或更高的策略违规：
`cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase`
#### Monitor 选项
要将绑定到 SCA 类型扫描中发现的 [SCA 策略](https://docs.cycode.com/docs/sca-policies) 的扫描结果推送到 Cycode，请将参数 `--monitor` 添加到扫描命令中。
例如，以下命令将扫描仓库中的 SCA 策略违规并将其推送到 Cycode 平台：
`cycode scan -t sca --monitor repository ~/home/git/codebase`
#### Cycode Report 选项
对于使用 Cycode CLI 执行的每次扫描，都会自动生成报告并将其结果发送到 Cycode。这些结果与 Cycode 平台内的相关策略（例如，用于 Repository 扫描的 [SCA 策略]( {tfplan}.json`
4. 使用 Cycode CLI 扫描您的 `{tfplan}.json`：
`cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json`
### Commit History 扫描
commit history 扫描命令提供两个主要功能：
1. **完整历史扫描**：分析仓库历史中的所有提交
2. **差异扫描**：仅扫描特定提交之间的更改
机密扫描可以分析仓库历史中的所有提交，因为引入并随后删除的机密仍然可能被泄露或暴露。对于 SCA 和 SAST 扫描，commit history 命令侧重于扫描提交之间的差异/更改，使其非常适合 pull request 审查和增量扫描。
commit history 扫描检查您的 Git 仓库的提交历史记录，既可用于全面的历史分析，也可用于针对特定更改的有针对性的差异扫描。
要执行 commit history 扫描，请执行以下命令：
`cycode scan commit-history {{path}}`
例如，考虑一种场景，您希望扫描存储在 `~/home/git/codebase` 中的仓库的提交历史。然后您可以执行以下命令：
`cycode scan commit-history ~/home/git/codebase`
此命令可以使用以下选项：
| 选项 | 描述 |
|---|---|
| `-r, --commit-range TEXT` | 扫描此 git 仓库中的提交范围，默认情况下 cycode 扫描所有提交历史（示例：HEAD~1） |
#### Commit Range 选项（差异扫描）
commit range 选项启用 **差异扫描** – 仅扫描特定提交之间的更改，而不是整个仓库历史。
这对于以下情况特别有用：
- **Pull request 验证**：仅扫描 PR 中引入的更改
- **增量 CI/CD 扫描**：关注最近的更改而不是整个代码库
- **功能分支审查**：将更改与 main/master 分支进行比较
- **性能优化**：通过将范围限制为相关更改来加快扫描速度
#### Commit Range 语法
`--commit-range` (`-r`) 选项支持标准 Git 修订语法：
| 语法 | 描述 | 示例 |
|---|---|---|
| `commit1..commit2` | 从 commit1 到 commit2 的更改 | `abc123..def456` |
| `commit1...commit2` | commit2 中有但 commit1 中没有的更改 | `main...feature-branch` |
| `commit` | 从 commit 到 HEAD 的更改 | `HEAD~1` |
| `branch1..branch2` | 从 branch1 到 branch2 的更改 | `main..feature-branch` |
#### 差异扫描示例
**扫描最后一次提交中的更改：**
```
cycode scan commit-history -r HEAD~1 ~/home/git/codebase
```
**扫描两个特定提交之间的更改：**
```
cycode scan commit-history -r abc123..def456 ~/home/git/codebase
```
**扫描您的功能分支与 main 相比的更改：**
```
cycode scan commit-history -r main..HEAD ~/home/git/codebase
```
**扫描 main 和功能分支之间的更改：**
```
cycode scan commit-history -r main..feature-branch ~/home/git/codebase
```
**扫描最后 3 次提交中的所有更改：**
```
cycode scan commit-history -r HEAD~3..HEAD ~/home/git/codebase
```
### Pre-Commit 扫描
pre-commit 扫描会在您将更改提交到仓库之前自动识别任何问题。无需手动执行此扫描；请按照本指南安装部分中的详述配置 pre-commit hook。
安装 pre-commit hook 后，您可能偶尔希望跳过特定提交期间的扫描。为此，请将以下内容添加到您的 `git` 命令中，以跳过单次提交的扫描：
```
SKIP=cycode git commit -m `
```
### Pre-Push 扫描
pre-push 扫描会在您将更改推送到远程仓库之前自动识别任何问题。此 hook 在客户端运行，仅扫描即将被推送的提交，使其能够高效地在问题到达远程仓库之前捕获它们。
pre-push hook 与 pre-commit 框架集成，并且可以配置为在任何 `git push` 操作之前运行。
#### 安装 Pre-Push Hook
要使用 pre-commit 框架设置 pre-push hook：
1. 安装 pre-commit 框架（如果尚未安装）：
pip3 install pre-commit
2. 创建或更新您的 `.pre-commit-config.yaml` 文件以包含 pre-push hooks：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode-pre-push
stages: [pre-push]
3. 对于多种扫描类型，请使用以下配置：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode-pre-push # Secrets 扫描
stages: [pre-push]
- id: cycode-sca-pre-push # SCA 扫描
stages: [pre-push]
- id: cycode-sast-pre-push # SAST 扫描
stages: [pre-push]
4. 安装 pre-push hook：
pre-commit install --hook-type pre-push
成功安装将导致消息：`Pre-push installed at .git/hooks/pre-push`。
5. 保持 pre-push hook 为最新版本：
pre-commit autoupdate
#### Pre-Push 扫描的工作原理
pre-push hook：
- 接收有关正在推送的提交的信息
- 计算适当的提交范围进行扫描
- 对于新分支：扫描与默认分支的合并基点以来的所有提交
- 对于现有分支：仅扫描自上次推送以来的新提交
- 运行与其他 Cycode 扫描模式相同的全面扫描
#### 智能默认分支检测
pre-push hook 使用以下优先顺序智能检测默认分支以进行合并基点计算：
1. **环境变量**：`CYCODE_DEFAULT_BRANCH` - 允许手动覆盖
2. **Git Remote HEAD**：使用 `git symbolic-ref refs/remotes/origin/HEAD` 检测实际的远程默认分支
3. **Git Remote Info**：如果 symbolic-ref 失败，则回退到 `git remote show origin`
4. **硬编码回退**：使用常见的默认分支名称（origin/main, origin/master, main, master）
**设置自定义默认分支：**
```
export CYCODE_DEFAULT_BRANCH=origin/develop
```
这种智能检测确保 pre-push hook 无论您的仓库使用 `main`、`master`、`develop` 还是任何其他默认分支名称都能正常工作。
#### 跳过 Pre-Push 扫描
要跳过特定推送操作的 pre-push 扫描，请使用：
```
SKIP=cycode-pre-push git push
```
或者跳过所有 pre-push hooks：
```
git push --no-verify
```
## 从扫描中排除路径
您可以使用 `.cycodeignore` 文件告诉 Cycode CLI 从扫描中排除哪些文件和目录。
它的工作原理类似于 `.gitignore` 文件。这有助于您将扫描集中在相关代码上，并防止某些路径在本地触发违规。
### 工作原理
1. 在您的工作文件夹中创建一个名为 `.cycodeignore` 的文件。
2. 列出要排除的文件和目录，使用与 `.gitignore` 相同的模式。
3. 将此文件放在您计划运行 cycode scan 命令的目录中。
### 支持的扫描器
- SAST
- IaC（即将推出）
- SCA（即将推出）
## 扫描结果
每次扫描完成时都会显示一条消息，说明是否发现了任何问题。
如果未发现任何问题，扫描将以以下成功消息结束：
`Good job! No issues were found!!! 👏👏👏`
如果发现问题，则完成时会显示违规卡片。在这种情况下，您应该检查结果消息突出显示的特定行的相关文件。实施解决该问题所需的任何更改，然后再次执行扫描。
### 显示/隐藏机密信息
在 [下面的示例](#secrets-result-example) 中，在位于子文件夹 `cli` 的文件 `secret_test` 中发现了一个机密。消息的第二部分显示机密出现的特定行，在这种情况下是分配给 `googleApiKey` 的值。
请注意该示例如何掩盖实际的机密值，将大部分机密替换为星号。扫描默认会掩盖机密，但您可以选择禁用此功能以查看完整的机密（假设您查看扫描结果的机器足够安全，防止窥探）。
要禁用机密混淆，请将 `--show-secret` 参数添加到任何类型的扫描中。
在以下示例中，对 `cli` 子目录执行了 Path Scan，并启用了完整显示发现的任何机密的选项：
`cycode scan --show-secret path ./cli`
结果将不会被混淆。
### 软失败
在正常操作中，当扫描结果中发现问题时，CLI 将返回退出代码 `1`。根据您的 CI/CD 设置，这通常会导致整体失败。如果您不希望发生这种情况，可以使用软失败功能。
通过将 `--soft-fail` 选项添加到任何类型的扫描中，无论是否发现任何结果，退出代码都将被强制为 `0`。
### 扫描结果示例
#### Secrets 结果示例
```
╭─────────────────────────────────────────────────────────────── Hardcoded generic-password is used ───────────────────────────────────────────────────────────────╮
│ Violation 12 of 12 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 34 }; │ │
│ │ In file /Users/cycodemacuser/NodeGoat/test/s │ │ 35 │ │
│ │ ecurity/profile-test.js │ │ 36 var sutUserName = "user1"; │ │
│ │ Secret SHA b4ea3116d868b7c982ee6812cce61727856b │ │ ❱ 37 var sutUserPassword = "Us*****23"; │ │
│ │ 802b3063cd5aebe7d796988552e0 │ │ 38 │ │
│ │ Rule ID 68b6a876-4890-4e62-9531-0e687223579f │ │ 39 chrome.setDefaultService(service); │ │
│ ╰────────────────────────────────────────────────────╯ │ 40 │ │
│ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ A generic secret or password is an authentication token used to access a computer or application and is assigned to a password variable. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
#### IaC 结果示例
```
╭──────────── Enable Content Encoding through the attribute 'MinimumCompressionSize'. This value should be greater than -1 and smaller than 10485760. ─────────────╮
│ Violation 45 of 110 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 20 BinaryMediaTypes: │ │
│ │ In file ...ads-copy/iac/cft/api-gateway/ap │ │ 21 - !Ref binaryMediaType1 │ │
│ │ i-gateway-rest-api/deploy.yml │ │ 22 - !Ref binaryMediaType2 │ │
│ │ IaC Provider CloudFormation │ │ ❱ 23 MinimumCompressionSize: -1 │ │
│ │ Rule ID 33c4b90c-3270-4337-a075-d3109c141b │ │ 24 EndpointConfiguration: │ │
│ │ 53 │ │ 25 Types: │ │
│ ╰────────────────────────────────────────────────────╯ │ 26 - EDGE │ │
│ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ This policy validates the proper configuration of content encoding in AWS API Gateway. Specifically, the policy checks for the attribute │ │
│ │ 'minimum_compression_size' in API Gateway REST APIs. Correct configuration of this attribute is important for enabling content encoding of API responses for │ │
│ │ improved API performance and reduced payload sizes. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
#### SCA 结果示例
```
╭─────────────────────────────────────────────────────── [CVE-2019-10795] Prototype Pollution in undefsafe ────────────────────────────────────────────────────────╮
│ Violation 172 of 195 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 26758 "integrity": "sha1-5z3T17DXxe2G+6xrCufYxqadUPo=", │ │
│ │ In file /Users/cycodemacuser/Node │ │ 26759 "dev": true │ │
│ │ Goat/package-lock.json │ │ 26760 }, │ │
│ │ CVEs CVE-2019-10795 │ │ ❱ 26761 "undefsafe": { │ │
│ │ Package undefsafe │ │ 26762 "version": "2.0.2", │ │
│ │ Version 2.0.2 │ │ 26763 "resolved": "https://registry.npmjs.org/undefsafe/-/undefsafe-2.0.2.tgz", │ │
│ │ First patched version Not fixed │ │ 26764 "integrity": "sha1-Il9rngM3Zj4Njnz9aG/Cg2zKznY=", │ │
│ │ Dependency path nodemon 1.19.1 -> │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │ undefsafe 2.0.2 │ │
│ │ Rule ID 9c6a8911-e071-4616-86db-4 │ │
│ │ 943f2e1df81 │ │
│ ╰────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ undefsafe before 2.0.3 is vulnerable to Prototype Pollution. The 'a' function could be tricked into adding or modifying properties of Object.prototype using │ │
│ │ a __proto__ payload. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
#### SAST 结果示例
```
╭───────────────────────────────────────────── [CWE-208: Observable Timing Discrepancy] Observable Timing Discrepancy ─────────────────────────────────────────────╮
│ Violation 24 of 49 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 173 " including numbers, lowercase and uppercase letters."; │ │
│ │ In file /Users/cycodemacuser/NodeGoat/app │ │ 174 return false; │ │
│ │ /routes/session.js │ │ 175 } │ │
│ │ CWE CWE-208 │ │ ❱ 176 if (password !== verify) { │ │
│ │ Subcategory Security │ │ 177 errors.verifyError = "Password must match"; │ │
│ │ Language js │ │ 178 return false; │ │
│ │ Security Tool Bearer (Powered by Cycode) │ │ 179 } │ │
│ │ Rule ID 19fbca07-a8e7-4fa6-92ac-a36d15509 │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │ fa9 │ │
│ ╰────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Observable Timing Discrepancy occurs when the time it takes for certain operations to complete can be measured and observed by attackers. This vulnerability │ │
│ │ is particularly concerning when operations involve sensitive information, such as password checks or secret comparisons. If attackers can analyze how long │ │
│ │ these operations take, they might be able to deduce confidential details, putting your data at risk. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
### 公司自定义修复指南
如果您的公司已通过 Cycode 门户在相关策略中设置了自定义修复指南，您将看到“Company Guidelines”字段，其中包含您添加的修复指南。请注意，如果您尚未添加任何公司指南，此字段将不会出现在 CLI 工具中。
## 忽略扫描结果
可以添加忽略规则以忽略特定的机密值、特定的 SHA512 值、特定路径和特定的 Cycode secret 和 IaC 规则 ID。这将导致扫描不提醒这些值。忽略规则被写入并保存在本地的 `./.cycode/config.yaml` 文件中。
以下是 `cycode ignore` 命令可用的选项：
| 选项 | 描述 |
|---|---|
| `--by-value TEXT` | 扫描机密时忽略特定值。有关更多详细信息，请参阅 [忽略机密值](#ignoring-a-secret-value)。 |
| `--by-sha TEXT` | 扫描机密时忽略字符串的特定 SHA512 表示形式。有关更多详细信息，请参阅 [忽略机密 SHA 值](#ignoring-a-secret-sha-value)。 |
| `--by-path TEXT` | 避免扫描特定路径。需要指定扫描类型。有关更多详细信息，请参阅 [忽略路径](#ignoring-a-path)。 |
| `--by-rule TEXT` | 忽略扫描特定的机密规则 ID/IaC 规则 ID/SCA 规则 ID。有关更多详细信息，请参阅 [忽略 Secret 或 Iac 规则](#ignoring-a-secret-iac-sca-or-sast-rule)。 |
| `--by-package TEXT` | 运行 SCA 扫描时忽略扫描特定的包版本。预期模式 - `name@version`。有关更多详细信息，请参阅 [忽略包](#ignoring-a-package)。 |
| `--by-cve TEXT` | 运行 SCA 扫描时忽略扫描特定的 CVE。预期模式：CVE-YYYY-NNN。 |
| `-t, --scan-type [secret\|iac\|sca\|sast]` | 指定您希望执行的扫描（`secret`/`iac`/`sca`/`sast`）。默认值为 `secret`。 |
| `-g, --global` | 添加忽略规则并在全局 `.cycode` 配置文件中更新它。 |
### 忽略机密值
要忽略特定的机密值，您需要使用 `--by-value` 标志。这将忽略所有未来扫描中的给定机密值。使用以下命令添加要忽略的机密值：
`code ignore --by-value {{secret-value}}`
在本节顶部的示例中，忽略特定机密值的命令如下：
`cycode ignore --by-value h3110w0r1d!@#$350`
在上面的示例中，将 `h3110w0r1d!@#$350` 值替换为您的未掩码机密值。有关如何在扫描结果中查看机密值的详细信息，请参阅 Cycode 扫描选项。
### 忽略机密 SHA 值
要忽略特定的机密 SHA 值，您需要使用 `--by-sha` 标志。这将忽略所有未来扫描中的给定机密 SHA 值。使用以下命令添加要忽略的机密 SHA 值：
`cycode ignore --by-sha {{secret-sha-value}}`
在本节顶部的示例中，忽略特定机密 SHA 值的命令如下：
`cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0`
在上面的示例中，将 `a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0` 值替换为您的机密 SHA 值。
### 忽略路径
要忽略 secret、IaC 或 SCA 扫描的特定路径，您需要结合使用 `--by-path` 标志和 `-t, --scan-type` 标志（您必须指定扫描类型）。这将忽略给定扫描类型的所有未来扫描中的给定路径。使用以下命令添加要忽略的路径：
`cycode ignore -t {{scan-type}} --by-path {{path}}`
在本节顶部的示例中，忽略 secret 特定路径的命令如下：
`cycode ignore -t secret --by-path ~/home/my-repo/config`
在上面的示例中，将 `~/home/my-repo/config` 值替换为您的路径值。
在本节顶部的示例中，忽略 IaC 扫描特定路径的命令如下：
`cycode ignore -t iac --by-path ~/home/my-repo/config`
在上面的示例中，将 `~/home/my-repo/config` 值替换为您的路径值。
在本节顶部的示例中，忽略 SCA 扫描特定路径的命令如下：
`cycode ignore -t sca --by-path ~/home/my-repo/config`
在上面的示例中，将 `~/home/my-repo/config` 值替换为您的路径值。
### 忽略 Secret, IaC, SCA 或 SAST 规则
要忽略特定的 secret、IaC、SCA 或 SAST 规则，您需要结合使用 `--by-rule` 标志和 `-t, --scan-type` 标志（您必须指定扫描类型）。这将忽略所有未来扫描中的给定规则 ID 值。使用以下命令添加要忽略的规则 ID 值：
`cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}`
在本节顶部的示例中，忽略特定 secret 规则 ID 的命令如下：
`cycode ignore -t secret --by-rule ce3a4de0-9dfc-448b-a004-c538cf8b4710`
在上面的示例中，将 `ce3a4de0-9dfc-448b-a004-c538cf8b4710` 值替换为您要忽略的规则 ID。
在本节顶部的示例中，忽略特定 IaC 规则 ID 的命令如下：
`cycode ignore -t iac --by-rule bdaa88e2-5e7c-46ff-ac2a-29721418c59c`
在上面的示例中，将 `bdaa88e2-5e7c-46ff-ac2a-29721418c59c` 值替换为您要忽略的规则 ID。
在本节顶部的示例中，忽略特定 SCA 规则 ID 的命令如下：
`cycode ignore -t sca --by-rule dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b`
在上面的示例中，将 `dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b` 值替换为您要忽略的规则 ID。
### 忽略包
要忽略 SCA 扫描中的特定包，您需要结合使用 `--by-package` 标志和 `-t, --scan-type` 标志（您必须指定 `sca` 扫描类型）。这将使用 `{{package_name}}@{{package_version}}` 格式忽略所有未来扫描中的给定包。使用以下命令添加要忽略的包和版本：
`cycode ignore --scan-type sca --by-package {{package_name}}@{{package_version}}`
或
`cycode ignore -t sca --by-package {{package_name}}@{{package_version}}`
在下面的示例中，忽略特定 SCA 包的命令如下：
`cycode ignore --scan-type sca --by-package pyyaml@5.3.1`
在上面的示例中，将 `pyyaml` 替换为包名称，并将 `5.3.1` 替换为您要忽略的包版本。
### 通过配置文件忽略
应用的忽略规则存储在名为 `config.yaml` 的配置文件中。
此文件可以轻松在开发人员之间共享，甚至可以提交到远程 Git。
这些文件始终位于 `.cycode` 文件夹中。
该文件夹以点 (.) 开头，您应该启用显示隐藏文件才能看到它。
#### 配置文件的路径
默认情况下，所有 `cycode ignore` 命令都将忽略规则保存到运行 CLI 的当前目录。
示例：从 `/Users/name/projects/backend` 运行忽略 CLI 命令将在 `/Users/name/projects/backend/.cycode` 中创建 `config.yaml`
```
➜ backend pwd
/Users/name/projects/backend
➜ backend cycode ignore --by-value test-value
➜ backend tree -a
.
└── .cycode
└── config.yaml
2 directories, 1 file
```
第二种选择是将忽略规则保存到全局配置文件。
全局配置的路径是 `~/.cycode/config.yaml`，
其中 `~` 表示用户的主目录，例如 macOS 上的 `/Users/name`。
可以使用 `cycode ignore` 命令的 `-g` 标志执行保存到全局空间。
例如：`cycode ignore -g --by-value test-value`。
#### 正确的工作目录
将 `.cycode` 文件夹放置在同一个地方并从同一个地方运行 CLI 非常重要。
在不同的环境（如 CI/CD (GitHub Actions, Jenkins 等)）中工作时，您应该仔细检查它。
您可以将 `.cycode` 文件夹提交到仓库的根目录。在这种情况下，您必须从仓库根目录运行 CLI 扫描。如果这不符合您的要求，您可以暂时将 `.cycode` 文件夹复制到您想要的任何位置，并从此文件夹执行 CLI 扫描。
#### 配置中的结构忽略规则
了解 CLI 如何存储忽略规则非常重要，以便能够读取这些配置文件甚至在没有 CLI 的情况下修改它们。
抽象 YAML 结构：
```
exclusions:
{scanTypeName}:
{ignoringType}:
- someIgnoringValue1
- someIgnoringValue2
```
`scanTypeName` 的可能值：`iac`、`sca`、`sast`、`secret`。
`ignoringType` 的可能值：`paths`、`values`、`rules`、`packages`、`shas`、`cves`。
真实 `config.yaml` 示例：
```
exclusions:
iac:
rules:
- bdaa88e2-5e7c-46ff-ac2a-29721418c59c
sca:
packages:
- pyyaml@5.3.1
secret:
paths:
- /Users/name/projects/build
rules:
- ce3a4de0-9dfc-448b-a004-c538cf8b4710
shas:
- a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
values:
- a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
- 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752
```
# Report 命令
## 生成 SBOM 报告
软件物料清单 (SBOM) 是参与应用程序开发和交付的所有组成组件和软件依赖项的清单。
使用此命令，您可以为本地项目或仓库 URI 创建 SBOM 报告。
此命令可以使用以下选项：
| 选项 | 描述 | 必需 | 默认值 |
|---|---|---|---|
| `-f, --format [spdx-2.2\|spdx-2.3\|cyclonedx-1.4]` | SBOM 格式 | 是 | |
| `-o, --output-format [JSON]` | 指定输出文件格式 | 否 | json |
| `--output-file PATH` | 输出文件 | 否 | 自动生成的文件名，保存到当前目录 |
| `--include-vulnerabilities` | 包含漏洞 | 否 | False |
| `--include-dev-dependencies` | 包含开发依赖项 | 否 | False |
此命令可以使用以下命令：
| 命令 | 描述 |
|---|---|
| `path` | 为命令中提供的路径生成 SBOM 报告 |
| `repository-url` | 为命令中提供的仓库 URI 生成 SBOM 报告 |
### Repository
要为仓库 URI 创建 SBOM 报告：\
`cycode report sbom --format --include-vulnerabilities --include-dev-dependencies --output-file repository_url `
例如：\
`cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq/cycode-cli.git`
### 本地项目
要为路径创建 SBOM 报告：\
`cycode report sbom --format --include-vulnerabilities --include-dev-dependencies --output-file path `
例如：\
`cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project`
`path` 子命令支持以下附加选项：
| 选项 | 描述 |
|---|---|
| `--no-restore` | 跳过 lockfile 恢复并仅扫描直接依赖项。有关详细信息，请参阅 [Lock Restore 选项](#lock-restore-option)。 |
| `--gradle-all-sub-projects` | 为所有子项目运行 Gradle restore 命令（从多项目 Gradle 构建的根目录使用）。 |
| `--maven-settings-file` | 仅适用于 Maven，允许在构建依赖项树时使用自定义 [settings.xml](https://maven.apache.org/settings.html) 文件。 |
# Import 命令
## 导入 SBOM
软件物料清单 (SBOM) 是参与应用程序开发和交付的所有组成组件和软件依赖项的清单。
使用此命令，您可以将文件系统中的 SBOM 文件导入 Cycode。
此命令可以使用以下选项：
| 选项 | 描述 | 必需 | 默认值 |
|---|---|---|---|
| `-n, --name TEXT` | SBOM 的显示名称 | 是 | |
| `-v, --vendor TEXT` | 提供 SBOM 的实体名称 | 是 | |
| `-l, --label TEXT` | 将标签附加到 SBOM | 否 | |
| `-o, --owner TEXT` | 作为此 SBOM 联系点的 Cycode 用户的电子邮件地址 | 否 | |
| `-b, --business-impact [High \| Medium \| Low]` | 业务影响 | 否 | Medium |
例如：\
`cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner example@cycode.com /path/to/local/project`
# 扫描日志
所有 CLI 扫描都记录在 Cycode 中。可以在 Settings > CLI Logs 下找到日志。
# 语法帮助
您可以随时向任何命令添加 `--help` 参数以查看帮助消息，该消息将显示可用选项及其语法。
要查看一般帮助，只需输入命令：
`cycode --help`
要查看扫描选项，请输入：
`cycode scan --help`
要查看特定扫描类型可用的选项，请输入：
`cycode scan {{option}} --help`
例如，要查看 Path Scan 可用的选项，您需要输入：
`cycode scan path --help`
要查看忽略扫描功能可用的选项，请使用以下命令：
`cycode ignore --help`
要查看报告可用的选项，请使用以下命令：
`cycode report --help`
要查看特定报告类型可用的选项，请输入：
`cycode scan {{option}} --help`
3. 在此页面上输入您的登录凭据并登录。
4. 您最终将被带到下面的页面，在该页面中，系统会要求您选择要授权 Cycode 使用的业务组（如果适用）：
5. 点击 **Allow** 按钮以授权 Cycode CLI 访问所选业务组。
6. 完成后，如果选择成功，您将看到以下屏幕：
7. 在终端/命令行屏幕中，当您退出浏览器窗口时，将看到以下内容：
`Successfully logged into cycode`
### 使用 Configure 命令
1. 在您的终端/命令行窗口中输入以下命令：
cycode configure
2. 输入您的 Cycode API URL 值（您可以留空以使用默认值）。
`Cycode API URL [https://api.cycode.com]: https://api.onpremise.com`
3. 输入您的 Cycode APP URL 值（您可以留空以使用默认值）。
`Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com`
4. 输入您的 Cycode Client ID 值。
`Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d`
5. 输入您的 Cycode Client Secret 值（如果您计划使用 OIDC ID token，请跳过）。
`Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e`
6. 输入您的 Cycode OIDC ID Token 值（可选）。
`Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...`
7. 如果值输入成功，您将看到以下消息：
`Successfully configured CLI credentials!`
或/和
`Successfully configured Cycode URLs!`
如果您进入用户文件夹下的 `.cycode` 文件夹，您会发现这些凭据已创建并放置在该文件夹的 `credentials.yaml` 文件中。
URL 放置在该文件夹的 `config.yaml` 文件中。
### 添加到环境变量
#### 在 Unix/Linux 上：
```
export CYCODE_CLIENT_ID={your Cycode ID}
```
以及
```
export CYCODE_CLIENT_SECRET={your Cycode Secret Key}
```
如果您的组织使用 OIDC 身份验证，您可以（或者额外）提供 ID token：
```
export CYCODE_ID_TOKEN={your Cycode OIDC ID token}
```
#### 在 Windows 上
1. 从控制面板导航到系统菜单：
2. 接下来，点击高级系统设置：
3. 在打开的系统属性窗口中，点击环境变量按钮：
4. 创建 `CYCODE_CLIENT_ID` 和 `CYCODE_CLIENT_SECRET` 变量，其值分别与您的 ID 和 Secret Key 匹配。如果您通过 OIDC 进行身份验证，请同时添加 `CYCODE_ID_TOKEN` 及您的 OIDC ID token 值：
5. 将 `cycode.exe` 插入路径以完成安装。
## 安装 Pre-Commit Hook
Cycode 的 pre-commit 和 pre-push hooks 可以在您的本地代码仓库中设置，以便 Cycode CLI 应用程序在您将代码提交或推送到代码库之前自动识别代码中的任何问题。
请执行以下步骤来安装 pre-commit hook：
### 安装 Pre-Commit Hook
1. 安装 pre-commit 框架（必须安装 Python 3.9 或更高版本）：
pip3 install pre-commit
2. 导航到您希望配置的本地 Git 仓库的顶级目录。
3. 在仓库的顶级目录中创建一个名为 `.pre-commit-config.yaml`（包含开头的 `.`）的新 YAML 文件，其中包含以下内容：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode
stages: [pre-commit]
4. 根据您的特定需求修改创建的文件。使用 hook ID `cycode` 启用 Secrets 扫描。使用 hook ID `cycode-sca` 启用 SCA 扫描。使用 hook ID `cycode-sast` 启用 SAST 扫描。如果要启用所有扫描类型，请使用以下配置：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode
stages: [pre-commit]
- id: cycode-sca
stages: [pre-commit]
- id: cycode-sast
stages: [pre-commit]
5. 安装 Cycode 的 hook：
pre-commit install
成功安装 hook 将导致消息：`Pre-commit installed at .git/hooks/pre-commit`。
6. 保持 pre-commit hook 为最新版本：
pre-commit autoupdate
它将自动把 `.pre-commit-config.yaml` 中的 `rev` 提升到 Cycode CLI 的最新可用版本。
### 安装 Pre-Push Hook
要安装 pre-push hook 以替代或补充 pre-commit hook：
1. 将 pre-push hooks 添加到您的 `.pre-commit-config.yaml` 文件中：
repos:
- repo: https://github.com/cycodehq/cycode-cli
rev: v3.5.0
hooks:
- id: cycode-pre-push
stages: [pre-push]
2. 安装 pre-push hook：
pre-commit install --hook-type pre-push
3. 要同时使用 pre-commit 和 pre-push hooks，请使用：
pre-commit install
pre-commit install --hook-type pre-push
# Cycode CLI 命令
以下是 Cycode CLI 应用程序可用的选项和命令：
| 选项 | 描述 |
|---|---|
| `-v`, `--verbose` | 显示详细日志。 |
| `--no-progress-meter` | 不显示进度条。 |
| `--no-update-notifier` | 不检查 CLI 更新。 |
| `-o`, `--output [rich\|text\|json\|table]` | 指定输出类型。默认为 `rich`。 |
| `--client-id TEXT` | 为此特定扫描执行指定 Cycode client ID。 |
| `--client-secret TEXT` | 为此特定扫描执行指定 Cycode client secret。 |
| `--id-token TEXT` | 为此特定扫描执行指定 Cycode OIDC ID token。 |
| `--install-completion` | 为当前 shell 安装补全。 |
| `--show-completion [bash\|zsh\|fish\|powershell\|pwsh]` | 显示指定 shell 的补全，以复制或自定义安装。 |
| `-h`, `--help` | 显示给定命令的选项。 |
| 命令 | 描述 |
|---|---|
| [auth](#using-the-auth-command) | 验证机器以将 CLI 与您的 Cycode 帐户关联。 |
| [configure](#using-the-configure-command) | 配置 CLI 客户端身份验证的初始命令。 |
| [ignore](#ignoring-scan-results) | 忽略特定值、路径或规则 ID。 |
| [mcp](#mcp-command-experiment) | 启动 Model Context Protocol (MCP) 服务器，以启用与 Cycode 扫描功能的 AI 集成。 |
| [scan](#running-a-scan) | 扫描内容是否存在 Secrets/IaC/SCA/SAST 违规。您需要指定要执行的扫描类型：commit-history/path/repository 等。 |
| [report](#report-command) | 生成报告。您需要指定要执行的报告类型，如 SBOM。 |
| status | 显示 CLI 状态并退出。 |
# MCP 命令 \[实验性\]
Model Context Protocol (MCP) 命令允许您启动一个 MCP 服务器，将 Cycode 的扫描功能公开给 AI 系统和应用程序。这使得 AI 模型能够通过标准化协议与 Cycode CLI 工具进行交互。
[](https://cursor.com/en/install-mcp?name=cycode&config=eyJjb21tYW5kIjoidXZ4IGN5Y29kZSBtY3AiLCJlbnYiOnsiQ1lDT0RFX0NMSUVOVF9JRCI6InlvdXItY3ljb2RlLWlkIiwiQ1lDT0RFX0NMSUVOVF9TRUNSRVQiOiJ5b3VyLWN5Y29kZS1zZWNyZXQta2V5IiwiQ1lDT0RFX0FQSV9VUkwiOiJodHRwczovL2FwaS5jeWNvZGUuY29tIiwiQ1lDT0RFX0FQUF9VUkwiOiJodHRwczovL2FwcC5jeWNvZGUuY29tIn19)
## 启动 MCP Server
要启动 MCP 服务器，请使用以下命令：
```
cycode mcp
```
默认情况下，这会使用 `stdio` 传输启动服务器，这适用于可以生成子进程的本地集成和 AI 应用程序。
### 可用选项
| 选项 | 描述 |
|---|---|
| `-t, --transport` | MCP 服务器的传输类型：`stdio`、`sse` 或 `streamable-http`（默认：`stdio`） |
| `-H, --host` | 绑定服务器的主机地址（仅用于非 stdio 传输）（默认：`127.0.0.1`） |
| `-p, --port` | 绑定服务器的端口号（仅用于非 stdio 传输）（默认：`8000`） |
| `--help` | 显示帮助消息和可用选项 |
### MCP 工具
MCP 服务器提供以下供 AI 系统使用的工具：
| 工具名称 | 描述 |
|---|---|
| `cycode_secret_scan` | 扫描文件中的硬编码机密 |
| `cycode_sca_scan` | 扫描文件中的软件组成分析 (SCA) - 漏洞和许可证问题 |
| `cycode_iac_scan` | 扫描文件中的基础设施即代码 配置错误 |
| `cycode_sast_scan` | 扫描文件中的静态应用安全测试 (SAST) - 代码质量和安全缺陷 |
| `cycode_status` | 获取 Cycode CLI 版本、身份验证状态和配置信息 |
### 用法示例
#### 基本命令示例
使用默认设置（stdio 传输）启动 MCP 服务器：
```
cycode mcp
```
使用显式 stdio 传输启动 MCP 服务器：
```
cycode mcp -t stdio
```
使用 Server-Sent Events (SSE) 传输启动 MCP 服务器：
```
cycode mcp -t sse -p 8080
```
在自定义主机和端口上使用 streamable HTTP 传输启动 MCP 服务器：
```
cycode mcp -t streamable-http -H 0.0.0.0 -p 9000
```
在 [MCP Protocol Specification – Transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) 中了解更多关于 MCP 传输类型的信息。
#### 配置示例
##### 在 Cursor/VS Code/Claude Desktop 等工具中使用 MCP (mcp.json)
请按照 [此指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) 在您的 **VS Code/GitHub Copilot** 中配置 MCP 服务器。请记住，在 `settings.json` 中，有一个包含嵌套 `servers` 子对象的 `mcp` 对象，而不是独立的 `mcpServers` 对象。
对于 **stdio 传输**（直接执行）：
```
{
"mcpServers": {
"cycode": {
"command": "cycode",
"args": ["mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
```
对于使用 `pipx` 安装的 **stdio 传输**：
```
{
"mcpServers": {
"cycode": {
"command": "pipx",
"args": ["run", "cycode", "mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
```
对于使用 `uvx` 安装的 **stdio 传输**：
```
{
"mcpServers": {
"cycode": {
"command": "uvx",
"args": ["cycode", "mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
```
对于 **SSE 传输** (Server-Sent Events)：
```
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
```
对于自定义端口上的 **SSE 传输**：
```
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8080/sse"
}
}
}
```
对于 **streamable HTTP 传输**：
```
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}
```
##### 在后台运行 MCP Server
对于 **SSE 传输**（先启动服务器，然后配置客户端）：
```
# 在后台启动 MCP server
cycode mcp -t sse -p 8000 &
# 在 mcp.json 中配置
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
```
对于 **streamable HTTP 传输**：
```
# 在后台启动 MCP server
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &
# 在 mcp.json 中配置
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.2:9000/mcp"
}
}
}
```
### MCP 故障排除
如果您在使用 MCP 服务器时遇到问题，可以启用调试日志记录以获取有关正在发生的情况的更详细信息。有两种方法可以启用调试日志记录：
1. 使用 `-v` 或 `--verbose` 标志：
```
cycode -v mcp
```
2. 使用 `CYCODE_CLI_VERBOSE` 环境变量：
```
CYCODE_CLI_VERBOSE=1 cycode mcp
```
调试日志将显示有关以下内容的详细信息：
- 服务器启动和配置
- 连接尝试和状态
- 工具执行和结果
- 发生的任何错误或警告
此信息在以下情况下可能会有所帮助：
- 诊断连接问题
- 了解某些工具为何不起作用
- 识别身份验证问题
- 调试特定于传输的问题
# Scan 命令
## 运行扫描
Cycode CLI 应用程序提供多种类型的扫描，以便您可以选择最适合您情况的选项。以下是当前可用的选项和命令：
| 选项 | 描述 |
|---|---|
| `-t, --scan-type [secret\|iac\|sca\|sast]` | 指定您希望执行的扫描（`secret`/`iac`/`sca`/`sast`），默认为 `secret`。 |
| `--show-secret BOOLEAN` | 以明文形式显示机密。有关更多详细信息，请参阅 [显示/隐藏机密信息](#showhide-secrets) 部分。 |
| `--soft-fail BOOLEAN` | 运行扫描而不失败，始终返回非错误状态代码。有关更多详细信息，请参阅 [软失败](#soft-fail) 部分。 |
| `--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]` | 仅显示达到或超过指定级别的违规。 |
| `--sca-scan` | 指定您希望执行的 SCA 扫描（`package-vulnerabilities`/`license-compliance`）。默认为两者。 |
| `--monitor` | 指定时，扫描结果将记录在 Cycode 中。 |
| `--cycode-report` | 在控制台输出中显示指向 Cycode 平台中扫描报告的链接。 |
| `--no-restore` | 指定时，Cycode 将不会运行 restore 命令。这将仅扫描直接依赖项！ |
| `--gradle-all-sub-projects` | 为所有子项目运行 gradle restore 命令。这应该从...运行 |
| `--maven-settings-file` | 仅适用于 Maven，允许在扫描依赖项时使用自定义 [settings.xml](https://maven.apache.org/settings.html) 文件 |
| `--help` | 显示给定命令的选项。 |
| 命令 | 描述 |
|---|---|
| [commit-history](#commit-history-scan) | 扫描提交历史或在特定提交之间执行差异扫描 |
| [path](#path-scan) | 扫描命令中提供的路径中的文件 |
| [pre-commit](#pre-commit-scan) | 使用此命令扫描尚未提交的内容 |
| [repository](#repository-scan) | 扫描 git 仓库及其历史 |
### 选项
#### Severity 选项
要将扫描结果限制为特定严重性阈值，可以将参数 `--severity-threshold` 添加到扫描命令中。
例如，以下命令将扫描仓库中严重性为 Medium 或更高的策略违规：
`cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase`
#### Monitor 选项
要将绑定到 SCA 类型扫描中发现的 [SCA 策略](https://docs.cycode.com/docs/sca-policies) 的扫描结果推送到 Cycode，请将参数 `--monitor` 添加到扫描命令中。
例如，以下命令将扫描仓库中的 SCA 策略违规并将其推送到 Cycode 平台：
`cycode scan -t sca --monitor repository ~/home/git/codebase`
#### Cycode Report 选项
对于使用 Cycode CLI 执行的每次扫描，都会自动生成报告并将其结果发送到 Cycode。这些结果与 Cycode 平台内的相关策略（例如，用于 Repository 扫描的 [SCA 策略](标签：CI/CD安全, CLI应用, DevSecOps, EC2, Google AI, IaC, Llama, Pre-Commit Hook, Python库, SAST, Secrets Detection, StruQ, Terraform安全, 上游代理, 命令行界面, 图计算, 安全左移, 开源组件漏洞, 盲注攻击, 网络安全, 网络安全研究, 逆向工具, 配置错误检测, 隐私保护