Cycode
官方通过SAST、SCA、密钥和IaC扫描，借助Cycode提升开发生命周期中的安全性。
你可以用 Cycode MCP 做什么？
- 扫描机密信息 — 使用
cycode_secret_scan请求助手扫描文件或目录中的硬编码机密信息。 - 扫描 SCA 问题 — 通过
cycode_sca_scan请求软件成分分析扫描，以检查漏洞和许可证问题。 - 扫描 IaC 配置错误 — 使用
cycode_iac_scan让助手检查基础设施即代码中的配置错误。 - 扫描 SAST 问题 — 使用
cycode_sast_scan运行静态应用程序安全测试扫描，以检查代码质量和安全缺陷。 - 检查 CLI 状态 — 通过
cycode_status查询 Cycode CLI 版本、身份验证状态和配置详情。
文档
Cycode CLI 用户指南
Cycode 命令行界面 (CLI) 是一款可在本地安装的应用程序，可扫描您的代码仓库，查找机密信息、基础设施即代码配置错误、软件成分分析漏洞以及静态应用程序安全测试问题。
本指南将介绍安装和使用方法。
目录
先决条件
- Cycode CLI 应用程序需要 Python 3.10 或更高版本。
- 使用
cycode auth命令 通过 CLI 向 Cycode 进行身份验证
安装
以下安装步骤适用于 Windows 和 UNIX / Linux 操作系统。
[!NOTE] 以下步骤假设 Python 相关命令使用
python3和pip3；不过，根据 Python 环境的配置，某些系统可能会改用python和pip命令。
安装 Cycode CLI
要在本地计算机上安装 Cycode CLI 应用程序，请执行以下步骤：
-
打开命令行或终端应用程序。
-
执行以下命令之一：
-
从 PyPI 安装：
pip3 install cycode -
从 Homebrew 安装：
brew install cycode -
从 GitHub Releases 安装：前往页面，下载适用于您的操作系统和架构的可执行文件，然后运行以下命令：
cd /path/to/downloaded/cycode-cli chmod +x cycode ./cycode -
-
最后，对 CLI 进行身份验证。设置 Cycode client ID 和凭据（client secret 或 OIDC ID token）有三种方法：
- cycode auth（推荐）
- cycode configure
- 将其添加到环境变量
使用 Auth 命令
[!NOTE] 推荐使用此方法设置本地计算机，以便通过 Cycode CLI 进行身份验证。
-
在终端/命令行窗口中输入以下命令：
cycode auth -
系统会打开浏览器窗口，提示您登录 Cycode（如下所示）：
-
在此页面输入登录凭据并登录。
-
随后，系统会跳转到以下页面，要求您选择要授权 Cycode 使用的业务组（如适用）：
[!NOTE] 这将成为 Cycode CLI 的默认身份验证方式。
-
单击 Allow 按钮，授权 Cycode CLI 使用所选业务组。
-
完成后，如果选择成功，您将看到以下屏幕：
-
关闭浏览器窗口后，您将在终端/命令行窗口中看到以下内容：
Successfully logged into cycode
使用 Configure 命令
[!NOTE] 如果您已通过 Linux 或 Windows 环境变量设置 Cycode Client ID 和 Client Secret，这些凭据的优先级将高于此方法。
-
在终端/命令行窗口中输入以下命令：
cycode configure -
输入 Cycode API URL 值（留空则使用默认值）。
Cycode API URL [https://api.cycode.com]: https://api.onpremise.com -
输入 Cycode APP URL 值（留空则使用默认值）。
Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com -
输入 Cycode Client ID 值。
Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d -
输入 Cycode Client Secret 值（如果计划使用 OIDC ID token，则跳过）。
Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e -
输入 Cycode OIDC ID Token 值（可选）。
Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... -
如果成功输入这些值，您将看到以下消息：
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 上
-
在控制面板中，导航到“系统”菜单：
-
接下来，单击“高级系统设置”：
-
在打开的“系统属性”窗口中，单击“环境变量”按钮：
-
创建
CYCODE_CLIENT_ID和CYCODE_CLIENT_SECRET变量，并分别将其值设为您的 ID 和 Secret Key。如果通过 OIDC 进行身份验证，还要添加CYCODE_ID_TOKEN，并将其值设为您的 OIDC ID token：
-
将
cycode.exe添加到路径中以完成安装。
安装 Pre-Commit Hook
您可以在本地代码仓库中设置 Cycode 的 pre-commit 和 pre-push hook，以便 Cycode CLI 应用程序在您将代码提交或推送到代码库之前自动识别其中的问题。
[!NOTE] IaC 扫描不支持 pre-commit 和 pre-push hook。
请执行以下步骤安装 pre-commit hook：
安装 Pre-Commit Hook
-
安装 pre-commit 框架（必须安装 Python 3.10 或更高版本）：
pip3 install pre-commit -
导航到要配置的本地 Git 代码仓库的顶层目录。
-
在代码仓库的顶层目录中创建一个名为
.pre-commit-config.yaml的新 YAML 文件（包含开头的.），并在其中添加以下内容：repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode stages: [pre-commit] -
根据具体需求修改创建的文件。使用 hook ID
cycode启用机密信息扫描。使用 hook IDcycode-sca启用 SCA 扫描。使用 hook IDcycode-sast启用 SAST 扫描。若要启用所有扫描类型，请使用以下配置：repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode stages: [pre-commit] - id: cycode-sca stages: [pre-commit] - id: cycode-sast stages: [pre-commit] -
安装 Cycode 的 hook：
pre-commit installhook 安装成功后，将显示以下消息：
Pre-commit installed at .git/hooks/pre-commit。 -
保持 pre-commit hook 为最新版本：
pre-commit autoupdate这会自动将
.pre-commit-config.yaml中的rev更新为最新可用的 Cycode CLI 版本。
[!NOTE] 在执行
git commit命令时触发。 Hook 仅针对已暂存以供提交的文件触发。
安装 Pre-Push Hook
若要在安装 pre-commit hook 的同时或替代它安装 pre-push hook：
-
将 pre-push hook 添加到您的
.pre-commit-config.yaml文件中：repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode-pre-push stages: [pre-push] -
安装 pre-push hook：
pre-commit install --hook-type pre-push -
同时使用 pre-commit 和 pre-push hook 时，请使用：
pre-commit install pre-commit install --hook-type pre-push
[!NOTE] Pre-push hook 会在执行
git 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 | 对机器进行身份验证，将 CLI 与您的 Cycode 账户关联。 |
| configure | 用于配置 CLI 客户端身份验证的初始命令。 |
| ignore | 忽略特定值、路径或规则 ID。 |
| mcp | 启动 Model Context Protocol (MCP) 服务器，以便将 AI 与 Cycode 扫描功能集成。 |
| scan | 扫描内容，查找 Secrets/IaC/SCA/SAST 违规。您需要指定要执行的扫描类型：commit-history/path/repository 等。 |
| report | 生成报告。您需要指定要生成的报告类型，例如 SBOM。 |
| status | 显示 CLI 状态并退出。 |
证书和代理
默认情况下，Cycode CLI 会使用随 CLI 一同提供的 CA 证书包验证 HTTPS 连接。
如果您的组织使用会检查 HTTPS 流量的代理，或者使用具有自有 CA 的本地部署，您有两种选择。
选项 1 — 使用机器上已安装的证书。 如果您的 CA 位于机器证书存储区中（受管设备通常如此），请选择启用：
export CYCODE_CLI_ENABLE_TRUSTSTORE=1
随后，CLI 会使用 Windows 证书存储区、macOS Keychain 或 Linux 上的系统 CA 目录进行验证，无需配置证书路径。
[!IMPORTANT] 此功能默认不启用，这是有意为之。信任机器存储区意味着信任该机器上的所有根证书，包括管理员或恶意软件安装的证书。只有在确认信任机器的证书存储区时才启用此功能。
选项 2 — 指定 CA 证书包文件。 无需选择启用：
| 环境变量 | 描述 |
|---|---|
REQUESTS_CA_BUNDLE | 要信任的 CA 证书包文件（.pem 或 .crt）的路径。 |
CURL_CA_BUNDLE | REQUESTS_CA_BUNDLE 的别名；仅当后者未设置时才会使用。 |
这两个选项可以组合使用：设置 CYCODE_CLI_ENABLE_TRUSTSTORE=1 后，除机器存储区中的证书外，还会信任
REQUESTS_CA_BUNDLE 中的证书。
[!TIP] 使用
-v运行任意命令，即可查看当前使用的信任来源，例如cycode -v status。
注意：
- 在 Windows 上，如果未设置
REQUESTS_CA_BUNDLE或CURL_CA_BUNDLE，CLI 一直会回退到系统证书存储区。此行为保持不变。 - 代理本身通过标准的
HTTP_PROXY、HTTPS_PROXY和NO_PROXY环境变量进行配置。
MCP 命令 [EXPERIMENT]
Model Context Protocol (MCP) 命令可启动 MCP 服务器，向 AI 系统和应用程序提供 Cycode 的扫描功能。这样，AI 模型便可通过标准化协议与 Cycode CLI 工具交互。
[!TIP] 为获得最佳体验，请使用
pip install cycode或brew install cycode在系统上全局安装 Cycode CLI，然后使用cycode auth完成一次身份验证。完成全局安装和身份验证后，您无需在 MCP 配置文件中设置CYCODE_CLIENT_ID和CYCODE_CLIENT_SECRET环境变量。
启动 MCP 服务器
使用以下命令启动 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 | 扫描基础设施即代码 (IaC) 配置错误 |
cycode_sast_scan | 扫描静态应用程序安全测试 (SAST) 问题，包括代码质量和安全缺陷 |
cycode_status | 获取 Cycode CLI 版本、身份验证状态和配置信息 |
每个扫描工具接受两种互斥的输入模式：
paths（首选） — 一个或多个磁盘上存在的文件或目录路径。目录会递归扫描。Cycode 引擎负责发现和筛选文件，与 CLI 中的cycode scan -t <type> path ./src一样。files（备用） — 将文件路径映射到其完整字符串内容的字典。仅当文件在磁盘上不可用时才使用此模式（例如，尚未保存的内存中编辑内容）。
[!TIP] 尽可能使用
paths。将大型文件（例如package-lock.json）作为内联内容传递，可能会超出令牌限制并拖慢 AI 客户端。使用paths时，Cycode 引擎会直接从磁盘读取文件。
所有扫描工具都会返回一个 JSON 对象，其中包含 "summary" 字段，用于显示易读的违规数量（例如 "Cycode found 3 violations: 1 CRITICAL, 2 HIGH."），此外还包含完整的 "detections" 数组。
使用示例
基本命令示例
使用默认设置启动 MCP 服务器（stdio 传输）：
cycode mcp
使用显式指定的 stdio 传输启动 MCP 服务器：
cycode mcp -t stdio
使用服务器发送事件 (SSE) 传输启动 MCP 服务器：
cycode mcp -t sse -p 8080
使用流式 HTTP 传输并指定自定义主机和端口启动 MCP 服务器：
cycode mcp -t streamable-http -H 0.0.0.0 -p 9000
在 MCP 协议规范 – 传输 中了解有关 MCP 传输类型的更多信息。
配置示例
在 Cursor/VS Code/Claude Desktop 等工具中使用 MCP (mcp.json)
[!NOTE] 对于 EU Cycode 环境，请确保在环境变量中设置相应的
CYCODE_API_URL和CYCODE_APP_URL值（例如https://api.eu.cycode.com和https://app.eu.cycode.com）。
按照本指南在 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 传输（服务器发送事件）：
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
使用自定义端口的 SSE 传输：
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8080/sse"
}
}
}
流式 HTTP 传输：
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}
在后台运行 MCP 服务器
SSE 传输（先启动服务器，再配置客户端）：
# Start the MCP server in the background
cycode mcp -t sse -p 8000 &
# Configure in mcp.json
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
流式 HTTP 传输：
# Start the MCP server in the background
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &
# Configure in mcp.json
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.2:9000/mcp"
}
}
}
高级配置
超时和自定义证书（代理环境）
如果 MCP 客户端提前终止长时间运行的扫描，请增加工具调用超时时间。
| 环境变量 | 描述 |
|---|---|
MCP_TOOL_TIMEOUT | MCP 客户端（例如 Claude 和 GitHub Copilot）等待工具调用完成的超时时间（秒）。如果长时间运行的扫描尚未完成就被中断，请增大此值。 |
在企业代理后运行时，请在 MCP 服务器的 env 块中设置证书变量。有关可用选项，请参阅
证书和代理：可以设置
CYCODE_CLI_ENABLE_TRUSTSTORE=1，使用机器上已有的证书；也可以设置指向 CA 证书包文件的
REQUESTS_CA_BUNDLE。
以下是使用自定义 CA 证书包并设置较长超时时间的 mcp.json 配置示例：
{
"mcpServers": {
"cycode": {
"command": "cycode",
"args": ["mcp"],
"env": {
"REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
"MCP_TOOL_TIMEOUT": "1800"
}
}
}
}
[!NOTE] MCP 服务器需要正确配置 Cycode CLI 身份验证才能运行。请确保已使用
cycode auth完成身份验证，或在启动 MCP 服务器前配置好凭据。
为子代理预先授权工具（Claude Code）
当 Claude Code 将工作委派给后台子代理时（例如并行运行扫描），这些子代理无法显示交互式权限提示。如果 Cycode 工具尚未预先批准，扫描将在子代理上下文中静默失败。
若要预先授权 Cycode MCP 工具，使其在包括子代理在内的所有上下文中都能正常工作，请将这些工具添加到 Claude Code 设置（~/.claude/settings.json）中的 allowedTools 列表：
{
"allowedTools": [
"mcp__cycode__cycode_secret_scan",
"mcp__cycode__cycode_sca_scan",
"mcp__cycode__cycode_iac_scan",
"mcp__cycode__cycode_sast_scan",
"mcp__cycode__cycode_status"
]
}
添加后，调用这些工具时 Claude Code 不会再提示批准，并且这些工具可在子代理中正常工作。
MCP 故障排除
如果 MCP 服务器出现问题，可以启用调试日志以获取更详细的信息。启用调试日志有两种方式：
- 使用
-v或--verbose标志：
cycode -v mcp
- 使用
CYCODE_CLI_VERBOSE环境变量：
CYCODE_CLI_VERBOSE=1 cycode mcp
调试日志会显示以下详细信息：
- 服务器启动和配置
- 连接尝试和状态
- 工具执行和结果
- 发生的任何错误或警告
这些信息有助于：
- 诊断连接问题
- 了解特定工具无法正常工作的原因
- 识别身份验证问题
- 调试特定传输方式的问题
MCP 配置
Platform 命令 [BETA]
[!WARNING]
platform命令处于 beta 阶段。命令、参数和输出格式会根据 Cycode API 规范动态生成，可能在不同版本之间发生变化，恕不另行通知。目前请勿在生产自动化中依赖这些内容。
cycode platform 命令将 Cycode 平台的读取 API 暴露为 CLI 命令。它按资源对端点进行分组（例如 projects、violations、workflows），并将每个端点的参数转换为类型化 CLI 参数和 --option 标志。
cycode platform projects list --page-size 50
cycode platform violations count
cycode platform workflows view <workflow-id>
首次使用时，系统会从 Cycode API 获取 OpenAPI 规范，并将其缓存到 ~/.cycode/openapi-spec.json，缓存有效期为 24 小时。无关命令（cycode scan、cycode status 等）不会触发获取操作。
[!NOTE]
cycode platform要发现并运行命令，必须通过cycode auth或CYCODE_CLIENT_ID/CYCODE_CLIENT_SECRET环境变量进行身份验证。其他 Cycode CLI 命令无需身份验证。
发现命令
由于命令是根据规范生成的，因此可用命令的权威来源是 --help：
cycode platform --help # list all resource groups
cycode platform projects --help # list actions on a resource
cycode platform projects list --help # list options/arguments for an action
平台示例
# List projects with pagination
cycode platform projects list --page-size 25
# View a single project by ID
cycode platform projects view <project-id>
# Count violations across the tenant
cycode platform violations count
# Filter using query parameters (see `--help` for what each endpoint supports)
cycode platform violations list --severity CRITICAL
默认情况下，所有输出均为 JSON 格式 — 可通过 jq 进行临时筛选：
cycode platform projects list --page-size 100 | jq '.items[].name'
平台说明与限制
- 目前为只读。 此测试版仅公开
GET端点。 - 由规范驱动。 向 API 添加新端点后，下次刷新缓存时，该端点会自动显示。
- 不附带规范文件。 安装后（或 24 小时缓存过期后）首次调用
cycode platform时会从网络获取数据。在连接较慢的情况下，首次调用可能需要几秒钟；在缓存过期前，后续调用几乎会立即完成。 - 使用
CYCODE_SPEC_CACHE_TTL=<seconds>覆盖缓存 TTL。
AI 防护措施 [BETA]
AI Guardrails 会在受支持的 AI 编码代理（Claude Code、Cursor、Copilot、Codex）中安装钩子，以便在提示词、代理读取的文件以及 MCP 工具参数到达模型之前扫描其中的机密信息。
AI Guardrails 收集的数据
扫描在服务器端进行，因此被扫描的内容会离开本机：提示词文本、代理读取的文件内容以及 MCP 工具参数都会发送到你的 Cycode 租户，以检查其中是否包含机密信息。
每个事件还会附带开发者和机器的相关信息，以便将发现的问题归因到相应的设备和用户。其中部分信息属于个人数据：
- 设备标识符 — 机器的主机名和硬件序列号。
- 用户标识符 — 登录 AI 编码代理的用户电子邮件地址，以及本地操作系统用户名。
- 环境详情 — 操作系统及其版本、AI 代理、代理版本和所用模型、代理 MCP 配置文件的内容，以及已启用的插件。
硬件序列号会缓存在本地临时文件中，且只有运行该命令的用户可以读取，因此重复调用钩子时不会重新查询硬件信息。
如果你的环境不允许收集这些数据，请勿安装防护措施钩子（cycode ai-guardrails uninstall 会移除已安装的钩子）。
扫描命令
运行扫描
Cycode CLI 应用提供多种扫描类型，你可以选择最适合当前情况的选项。以下是目前可用的选项和命令：
| 选项 | 说明 |
|---|---|
-t, --scan-type [secret|iac|sca|sast] | 指定要执行的扫描类型（secret/iac/sca/sast），默认值为 secret。 |
--show-secret BOOLEAN | 以纯文本形式显示机密信息。详情请参阅显示/隐藏机密信息部分。 |
--soft-fail BOOLEAN | 运行扫描但不使其失败，始终返回非错误状态代码。详情请参阅软失败部分。 |
--severity-threshold [INFO|LOW|MEDIUM|HIGH|CRITICAL] | 仅显示指定级别或更高级别的违规项。 |
--sca-scan | 指定要执行的 SCA 扫描（package-vulnerabilities/license-compliance/unmaintained-packages/malicious-packages）。默认值为全部。 |
--monitor | 指定后，扫描结果将记录在 Cycode 中。 |
--cycode-report | 在控制台输出中显示 Cycode 平台上扫描报告的链接。 |
--no-restore | 指定后，Cycode 不会运行 restore 命令。此时只会扫描直接依赖项！ |
--stop-on-error | 如果文件收集或依赖项还原失败，则中止扫描，而不是跳过失败的文件并继续。 |
--gradle-all-sub-projects | 为所有子项目运行 gradle restore 命令。应从 |
--maven-settings-file | 仅适用于 Maven；扫描依赖项时允许使用自定义 settings.xml 文件 |
--help | 显示给定命令的选项。 |
| 命令 | 说明 |
|---|---|
| commit-history | 扫描提交历史记录，或对特定提交之间的差异执行扫描 |
| path | 扫描命令中提供的路径下的文件 |
| pre-commit | 扫描尚未提交的内容；也支持通过标志进行本地差异扫描（适用于 IDE） |
| repository | 扫描 Git 仓库及其历史记录 |
选项
严重性选项
若要将扫描结果限制为特定严重性阈值，可在扫描命令中添加参数 --severity-threshold。
例如，以下命令会扫描仓库中严重性为 Medium 或更高的策略违规项：
cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase
监控选项
[!NOTE] 此选项仅适用于 SCA 扫描。
若要将 SCA 类型扫描中发现的、与 SCA 策略相关的扫描结果推送到 Cycode，请在扫描命令中添加参数 --monitor。
例如，以下命令会扫描仓库中的 SCA 策略违规项，并将其推送到 Cycode 平台：
cycode scan -t sca --monitor repository ~/home/git/codebase
Cycode 报告选项
使用 Cycode CLI 执行的每次扫描都会自动生成报告，并将结果发送到 Cycode。这些结果会关联到 Cycode 平台中的相关策略（例如，仓库扫描对应的 SCA 策略）。
若要在扫描完成后于 CLI 输出中打印 Cycode 报告的直接 URL，请在扫描命令中添加参数 --cycode-report。
cycode scan --cycode-report repository ~/home/git/codebase
CLI 的所有扫描结果都会显示在 Cycode 的 CLI Logs 部分。如果在命令中加入了 --cycode-report 标志，扫描结果之后会在终端中显示特定报告的直接链接。
[!WARNING] 你必须在 Cycode 中拥有
owner或admin角色才能查看此页面。
报告页面大致如下所示：
软件包漏洞选项
[!NOTE] 此选项仅适用于 SCA 扫描。
若要扫描本地仓库中特定的软件包漏洞，请在 -t sca 或 --scan-type sca 选项后添加参数 --sca-scan package-vulnerabilities。
在前面的示例中，如果只想对软件包漏洞运行 SCA 扫描，可以执行以下命令：
cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase
许可证合规性选项
[!NOTE] 此选项仅适用于 SCA 扫描。
若要扫描本地仓库中的特定分支，请添加参数 --sca-scan license-compliance，后跟要扫描的分支名称。
在前面的示例中，如果只想扫描名为 dev 的分支，可以执行以下命令：
cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev
未维护软件包选项
[!NOTE] 此选项仅适用于 SCA 扫描。
若要仅扫描未维护的软件包（其 OpenSSF Scorecard Maintained 检查结果较低，表示近期提交和问题活动很少或没有），请在 -t sca 或 --scan-type sca 选项后添加参数 --sca-scan unmaintained-packages。
[!NOTE] 是否报告未维护的软件包由组织策略控制。此选项会缩小扫描报告的范围；它无法启用租户中已关闭的策略。
在前面的示例中，如果只想对未维护的软件包运行 SCA 扫描，可以执行以下命令：
cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase
恶意软件包选项
[!NOTE] 此选项仅适用于 SCA 扫描。
若要仅扫描恶意软件包（安全公告已将其认定为恶意软件，而非仅存在漏洞的依赖项），请在 -t sca 或 --scan-type sca 选项后添加参数 --sca-scan malicious-packages。
恶意软件包违规项始终报告为 Critical，且不带 CVSS 分数或修复版本：唯一的补救措施是移除该依赖项。
[!NOTE] 是否报告恶意软件包由组织策略控制。此选项会缩小扫描报告的范围；它无法启用租户中已关闭的策略。
在前面的示例中，如果只想对恶意软件包运行 SCA 扫描，可以执行以下命令：
cycode scan -t sca --sca-scan malicious-packages repository ~/home/git/codebase
锁文件还原选项
[!NOTE] 此选项仅适用于 SCA 扫描。
运行 SCA 扫描时，Cycode CLI 会自动尝试为找到的每个受支持清单文件还原（生成）依赖项锁文件。这样便可扫描传递依赖项，而不仅仅是清单中直接列出的依赖项。若要跳过此步骤并仅扫描直接依赖项，请使用 --no-restore 标志。
以下生态系统支持自动还原锁文件：
| 生态系统 | 清单文件 | 生成的锁文件 | 调用的工具（锁文件不存在时） |
|---|---|---|---|
| npm | package.json | package-lock.json | npm install --package-lock-only --ignore-scripts --no-audit |
| Yarn | package.json | yarn.lock | yarn install --ignore-scripts |
| pnpm | package.json | pnpm-lock.yaml | pnpm install --ignore-scripts |
| Deno | deno.json / deno.jsonc | deno.lock | (仅读取现有锁文件) |
| Go | go.mod | go.mod.graph | go list -m -json all + go mod graph |
| Maven | pom.xml | bcde.mvndeps | mvn dependency:tree |
| Gradle | build.gradle / build.gradle.kts | gradle-dependencies-generated.txt | gradle dependencies -q --console plain |
| SBT | build.sbt | build.sbt.lock | sbt dependencyLockWrite |
| NuGet | *.csproj | packages.lock.json | dotnet restore --use-lock-file |
| Ruby | Gemfile | Gemfile.lock | bundle --quiet |
| Poetry | pyproject.toml | poetry.lock | poetry lock |
| pip | pyproject.toml / requirements.txt | pylock.toml | pip lock . / pip lock -r requirements.txt -o pylock.toml |
| Pipenv | Pipfile | Pipfile.lock | pipenv lock |
| PHP Composer | composer.json | composer.lock | composer update --no-cache --no-install --no-scripts --ignore-platform-reqs |
如果清单旁边已存在锁文件，Cycode 会直接读取该文件，而不会运行任何安装命令。
**SBT 前置条件：**必须安装 sbt-dependency-lock 插件。将以下行添加到 project/plugins.sbt：
addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "1.5.1")
出错时停止选项
默认情况下，即使无法读取文件（例如，由于权限错误）或在 SCA 扫描期间无法生成依赖项锁定文件，Cycode 也会继续扫描。失败的项目会被跳过并显示警告，扫描会继续处理其余文件。
使用 --stop-on-error 更改此行为：扫描会在首次发生此类故障时立即中止并报告错误。
cycode scan -t sca --stop-on-error path ~/home/git/codebase
这在 CI 流水线中很有用，因为静默失败会导致扫描结果不完整。触发 --stop-on-error 时，你可以修复根本问题；如果是 SCA 还原失败，则可以添加 --no-restore，跳过锁定文件生成，仅扫描直接依赖项。
使用 --stop-on-error 时，CLI 会通过退出代码区分扫描错误和策略违规：
| 退出代码 | 含义 |
|---|---|
0 | 扫描完成，未发现违规 |
1 | 扫描完成，发现违规 |
2 | 扫描因错误而中止（仅当设置了 --stop-on-error 时） |
仓库扫描
仓库扫描会检查整个本地仓库，查找任何暴露的机密或不安全的错误配置。这种更全面的扫描类型会检查所有内容：仓库的当前状态及其提交历史。它不仅会查找当前在仓库中暴露的机密，也会查找之前删除的机密。
要执行完整的仓库扫描，请运行以下命令：
cycode scan repository {{path}}
例如，如果要扫描存储在 ~/home/git/codebase 中的仓库，可以运行以下命令：
cycode scan repository ~/home/git/codebase
此命令可使用以下选项：
| 选项 | 说明 |
|---|---|
-b, --branch TEXT | 要扫描的分支；如果未设置，则扫描默认分支 |
分支选项
要扫描本地仓库中的特定分支，请添加参数 -b（也可以使用 --branch），然后指定要扫描的分支名称。
沿用前面的示例，如果只想扫描名为 dev 的分支，可以运行以下命令：
cycode scan repository ~/home/git/codebase -b dev
路径扫描
路径扫描会检查特定的本地目录及其所有内容，而不是仅关注 GIT 仓库。
要执行目录扫描，请运行以下命令：
cycode scan path {{path}}
例如，假设你要扫描位于 ~/home/git/codebase 的目录。此时可以运行以下命令：
cycode scan path ~/home/git/codebase
Terraform 计划扫描
Cycode CLI 支持 Terraform 计划扫描（支持 Terraform 0.12 及更高版本）
Terraform 计划文件必须为 JSON 格式（扩展名为 .json）
如果你只有配置文件，可以按以下步骤生成计划：
-
初始化包含 Terraform 配置文件的工作目录：
terraform init -
创建 Terraform 执行计划并保存二进制输出：
terraform plan -out={tfplan_output} -
将二进制输出文件转换为可读的 JSON：
terraform show -json {tfplan_output} > {tfplan}.json -
使用 Cycode CLI 扫描你的
{tfplan}.json：cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json
提交历史扫描
[!NOTE] IaC 扫描不支持提交历史扫描。
提交历史扫描命令提供两项主要功能：
- 完整历史扫描：分析仓库历史记录中的所有提交
- 差异扫描：仅扫描特定提交之间的更改
机密扫描可以分析仓库历史记录中的所有提交，因为引入后又被删除的机密仍可能泄露或暴露。对于 SCA 和 SAST 扫描，提交历史命令侧重于扫描提交之间的差异/更改，因此非常适合拉取请求审查和增量扫描。
提交历史扫描会检查 Git 仓库的提交历史，可用于全面的历史分析，也可用于针对特定更改进行差异扫描。
要执行提交历史扫描，请运行以下命令：
cycode scan commit-history {{path}}
例如，假设你要扫描存储在 ~/home/git/codebase 中的仓库的提交历史。此时可以运行以下命令：
cycode scan commit-history ~/home/git/codebase
此命令可使用以下选项：
| 选项 | 说明 |
|---|---|
-r, --commit-range TEXT | 扫描此 git 仓库中的提交范围；默认情况下，cycode 会扫描所有提交历史（例如：HEAD~1） |
提交范围选项（差异扫描）
提交范围选项可启用差异扫描——仅扫描特定提交之间的更改，而不是整个仓库历史记录。 这在以下场景中特别有用：
- 拉取请求验证：仅扫描 PR 中引入的更改
- 增量 CI/CD 扫描：关注近期更改，而不是整个代码库
- 功能分支审查：将更改与 main/master 分支进行比较
- 性能优化：通过将范围限制为相关更改来加快扫描速度
提交范围语法
--commit-range（-r）选项支持标准 Git 修订版本语法：
| 语法 | 说明 | 示例 |
|---|---|---|
commit1..commit2 | 从 commit1 到 commit2 的更改 | abc123..def456 |
commit1...commit2 | commit2 中有而 commit1 中没有的更改 | main...feature-branch |
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
[!TIP] 对于 CI/CD 流水线，可以使用
${{ github.event.pull_request.base.sha }}..${{ github.sha }}（GitHub Actions）或$CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA（GitLab CI）等环境变量，仅扫描 PR/MR 更改。
提交前扫描
提交前扫描会在你向仓库提交更改之前自动识别问题。无需手动运行此扫描；请按照本指南“安装”部分中的说明配置提交前钩子。
安装提交前钩子后，有时你可能希望在某次提交期间跳过扫描。为此，请将以下内容添加到你的 git 命令中，以便在单次提交时跳过扫描：
SKIP=cycode git commit -m <your commit message>`
此命令可使用以下选项：
| 选项 | 说明 |
|---|---|
-b, --base-ref TEXT | 用于比较差异的 Git 引用（提交、分支或标签）；默认为 HEAD，与提交前钩子的行为一致 |
--include-unstaged | 同时扫描已跟踪文件中尚未暂存的更改，而不仅仅是已暂存的内容；默认关闭 |
--path PATH | 可选的路径，用于限定差异扫描范围；可重复指定；默认扫描整个工作目录 |
本地差异扫描（IDE 集成）
--base-ref 和 --include-unstaged 可将 pre-commit 转变为通用的本地差异扫描：将任意提交（默认为 HEAD）与当前工作目录进行比较，包括尚未暂存的编辑内容。此功能面向 IDE 插件和其他工具，让你在工作时获得持续的实时反馈，而不是使用 Git 钩子流程。结合 --include-unstaged 后，--path 可让 IDE 将扫描范围限定为编辑器中当前打开的文件。
[!NOTE] IaC 扫描不支持本地差异扫描（通过这些标志启用）。
将当前所有已更改内容（已暂存 + 未暂存）与上一次提交进行比较：
cycode scan pre-commit --include-unstaged
将更改与特定提交或分支进行比较：
cycode scan pre-commit --include-unstaged --base-ref main
仅扫描特定文件（例如 IDE 中当前打开的文件）：
cycode scan pre-commit --include-unstaged --path src/app.py
推送前扫描
推送前扫描会在你将更改推送到远程仓库之前自动识别问题。此钩子在客户端运行，仅扫描即将推送的提交，因此可以高效地在问题到达远程仓库之前将其发现。
[!NOTE] IaC 扫描不支持推送前钩子。
推送前钩子与 pre-commit 框架集成，可配置为在任何 git push 操作之前运行。
安装推送前钩子
要使用 pre-commit 框架设置推送前钩子：
-
安装 pre-commit 框架（如果尚未安装）：
pip3 install pre-commit -
创建或更新你的
.pre-commit-config.yaml文件，以包含推送前钩子：repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode-pre-push stages: [pre-push] -
对于多种扫描类型，请使用以下配置：
repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode-pre-push # Secrets scan stages: [pre-push] - id: cycode-sca-pre-push # SCA scan stages: [pre-push] - id: cycode-sast-pre-push # SAST scan stages: [pre-push] -
安装推送前钩子：
pre-commit install --hook-type pre-push安装成功后会显示以下消息：
Pre-push installed at .git/hooks/pre-push。 -
保持推送前钩子为最新版本：
pre-commit autoupdate
推送前扫描的工作方式
此钩子会逐个扫描正在推送的每个提交，因此即使某个提交中添加的机密在后续提交中被删除，也仍会被发现。通过 pre-commit 框架安装时，推送范围由该框架提供：对于现有分支，范围是远程分支之后的新提交；对于新分支，范围是尚未推送到远程的提交（推送到空远程仓库时则为所有提交）。如果从手写的 .git/hooks/pre-push 运行，范围会从 git 的钩子输入中读取；对于新分支，则从其与默认分支的合并基点开始扫描（见下文）。
没有需要扫描内容的推送（例如标签、分支删除和已同步的推送）会直接通过，不执行扫描。如果钩子无法确定正在推送的内容，则会失败并阻止推送，而不是静默放行。
Cycode 推送前钩子会设置 always_run: true 和 pass_filenames: false，因为扫描范围是正在推送的提交，而不是文件列表。如果未设置 always_run，当正在推送的提交合计没有更改文件时（例如某个提交中添加机密、下一个提交中又将其删除），pre-commit 框架会跳过该钩子。如果未设置 pass_filenames: false，框架会传入扫描不会使用的已更改文件名；对于大型推送，还会将这些文件分批处理，并对每批运行一次完整扫描。如果你自行定义钩子（例如定义为 repo: local 钩子），请设置这两个选项。
智能检测默认分支
从手写钩子运行时，推送前扫描会按以下优先级顺序检测用于计算合并基点的默认分支：
- 环境变量：
CYCODE_DEFAULT_BRANCH- 允许手动覆盖 - Git 远程 HEAD：使用
git symbolic-ref refs/remotes/origin/HEAD检测实际的远程默认分支 - Git 远程信息：如果 symbolic-ref 失败，则回退到
git remote show origin - 硬编码回退值：使用常见的默认分支名称（origin/main、origin/master、main、master）
设置自定义默认分支：
export CYCODE_DEFAULT_BRANCH=origin/develop
此智能检测可确保无论您的仓库使用 main、master、develop 还是其他默认分支名称，pre-push hook 都能正常工作。
跳过 Pre-Push 扫描
若要跳过某次特定推送操作的 pre-push 扫描，请使用：
SKIP=cycode-pre-push git push
或者跳过所有 pre-push hooks：
git push --no-verify
[!TIP] pre-push hook 会在
git push命令上触发，并且只扫描即将推送的提交，因此比扫描整个仓库更高效。
从扫描中排除路径
您可以使用 .cycodeignore 文件，告知 Cycode CLI 在扫描时排除哪些文件和目录。
它的工作方式与 .gitignore 文件相同。这有助于您专注于相关代码，并防止某些路径在本地触发违规。
工作原理
- 在工作文件夹中创建名为
.cycodeignore的文件。 - 使用与
.gitignore相同的模式，列出要排除的文件和目录。 - 将此文件放在您计划运行 cycode scan 命令的目录中。
[!WARNING]
- 无效文件：如果
.cycodeignore文件包含语法错误，CLI 扫描将失败并返回错误。- 忽略路径与违规：此文件用于排除路径。这与 CLI 忽略特定违规的功能不同（例如，使用 --ignore-violation 标志）。
支持的扫描器
- SAST
- IaC（即将推出）
- SCA（即将推出）
扫描结果
每次扫描完成后，都会显示一条消息，说明是否发现问题。
如果未发现问题，扫描结束时会显示以下成功消息：
Good job! No issues were found!!! 👏👏👏
如果发现问题，完成后会显示违规卡片。此时，您应检查相关文件中结果消息标出的具体行。实施解决问题所需的更改，然后重新执行扫描。
显示/隐藏机密
在以下示例中，文件 secret_test 中发现了一个机密，该文件位于子文件夹 cli 中。消息的第二部分显示了机密所在的具体行；在此示例中，它是分配给 googleApiKey 的值。
请注意，示例中实际机密值已被遮蔽，大部分内容被星号替代。扫描默认会遮蔽机密，但您也可以选择关闭此功能，以查看完整机密（前提是您查看扫描结果的计算机足够安全，不会被他人窥视）。
若要关闭机密遮蔽，请在任何类型的扫描中添加 --show-secret 参数。
以下示例中，Path Scan 针对 cli 子目录执行，并启用了完整显示所发现机密的选项：
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 门户在相关策略中设置自定义修复指南，您将看到“公司指南”字段，其中包含您添加的修复指南。请注意，如果您尚未添加任何公司指南，此字段将不会显示在 CLI 工具中。
忽略扫描结果
您可以添加忽略规则，以忽略特定机密值、特定 SHA512 值、特定路径，以及特定 Cycode 机密和 IaC 规则 ID。这样，扫描就不会针对这些值发出警报。忽略规则会写入并保存在本地的 ./.cycode/config.yaml 文件中。
[!WARNING] 添加要忽略的值时应谨慎考虑这些值、路径和策略，以确保扫描仍能发现真正的问题。
以下是 cycode ignore 命令可用的选项：
| 选项 | 说明 |
|---|---|
--by-value TEXT | 扫描机密时忽略特定值。详情请参阅忽略机密值。 |
--by-sha TEXT | 扫描机密时忽略字符串的特定 SHA512 表示形式。详情请参阅忽略机密 SHA 值。 |
--by-path TEXT | 避免扫描特定路径。必须指定扫描类型。详情请参阅忽略路径。 |
--by-rule TEXT | 忽略扫描特定机密规则 ID/IaC 规则 ID/SCA 规则 ID。详情请参阅忽略机密或 IaC 规则。 |
--by-package TEXT | 运行 SCA 扫描时忽略特定软件包版本。预期模式 - name@version。详情请参阅忽略软件包。 |
--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 标志。此操作会在今后的所有扫描中忽略给定的机密值。使用以下命令添加要忽略的机密值：
cycode 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 值。
忽略路径
若要在机密、IaC 或 SCA 扫描中忽略特定路径，需要将 --by-path 标志与 -t, --scan-type 标志配合使用（必须指定扫描类型）。此操作会在今后所有指定类型的扫描中忽略给定路径。使用以下命令添加要忽略的路径：
cycode ignore -t {{scan-type}} --by-path {{path}}
在本节顶部的示例中，忽略机密扫描中特定路径的命令如下：
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 值替换为您的路径值。
忽略机密、IaC、SCA 或 SAST 规则
若要忽略特定机密、IaC、SCA 或 SAST 规则，需要将 --by-rule 标志与 -t, --scan-type 标志配合使用（必须指定扫描类型）。此操作会在今后的所有扫描中忽略给定的规则 ID 值。使用以下命令添加要忽略的规则 ID 值：
cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}
在本节顶部的示例中，忽略特定机密规则 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。
忽略软件包
[!NOTE] 此选项仅适用于 SCA 扫描。
若要在 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 home directory, for example, /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。
[!WARNING] “按值忽略”的值不会以纯文本形式存储！ CLI 存储的是这些值的 sha256 哈希。 手动修改配置文件时，应填写字符串的哈希值。
实际的 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
报告命令
生成 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 报告 |
存储库
要为存储库 URI 创建 SBOM 报告：
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <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 <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>
例如：
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project
path 子命令支持以下其他选项：
| 选项 | 说明 |
|---|---|
--no-restore | 跳过锁文件还原，仅扫描直接依赖项。详情请参阅锁文件还原选项。 |
--gradle-all-sub-projects | 对所有子项目运行 Gradle 还原命令（在多项目 Gradle 构建的根目录中使用）。 |
--maven-settings-file | 仅适用于 Maven，允许在构建依赖关系树时使用自定义的 settings.xml 文件。 |
导入命令
导入 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 中。您可以在“设置”>“CLI 日志”下查看日志。
语法帮助
您可以随时向任何命令添加 --help 参数，以查看帮助消息，其中会显示可用选项及其语法。
要查看常规帮助，只需输入以下命令：
cycode --help
要查看扫描选项，请输入：
cycode scan --help
要查看特定扫描类型的可用选项，请输入：
cycode scan {{option}} --help
例如，要查看路径扫描的可用选项，请输入：
cycode scan path --help
要查看忽略扫描功能的可用选项，请使用以下命令：
cycode ignore --help
要查看报告的可用选项，请使用以下命令：
cycode report --help
要查看特定报告类型的可用选项，请输入：
cycode scan {{option}} --help