Cycode MCP Server

官方

通过SAST、SCA、密钥和IaC扫描，借助Cycode提升开发生命周期中的安全性。

GitHub

文档

Cycode CLI 用户指南

Cycode 命令行界面 (CLI) 是一个可本地安装的应用程序，用于扫描仓库中的密钥、基础设施即代码错误配置、软件组成分析漏洞以及静态应用安全测试问题。

本指南将引导您完成安装和使用。

前提条件

Cycode CLI 应用程序需要 Python 3.9 或更高版本。MCP 命令仅适用于 Python 3.10 及以上版本。如果您使用的是较早的 Python 版本，此命令将不可用。
使用 cycode auth 命令通过 CLI 向 Cycode 进行身份验证
- 或者，您可以按照服务账户令牌和个人访问令牌页面中详述的步骤获取 Cycode 客户端 ID 和客户端密钥，这些页面包含获取这些值的详细信息。

安装

以下安装步骤适用于 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 客户端 ID 和凭据（客户端密钥或 OIDC ID 令牌）：
- cycode auth（推荐）
- cycode configure
- 将它们添加到您的环境变量中

使用 Auth 命令

[!NOTE] 这是为本地机器设置 Cycode CLI 身份验证的推荐方法。

在终端/命令行窗口中键入以下命令：

cycode auth
将出现一个浏览器窗口，要求您登录 Cycode（如下所示）：
在此页面上输入您的登录凭据并登录。
您最终将被带到以下页面，系统会要求您选择要授权 Cycode 的业务组（如果适用）：

[!NOTE] 这将是使用 Cycode CLI 进行身份验证的默认方法。
单击允许按钮以授权 Cycode CLI 访问选定的业务组。
完成后，如果选择成功，您将看到以下屏幕：
在终端/命令行屏幕中，退出浏览器窗口时您将看到以下内容：

Successfully logged into cycode

使用 Configure 命令

[!NOTE] 如果您已经通过 Linux 或 Windows 环境变量设置了 Cycode 客户端 ID 和客户端密钥，那么这些凭据将优先于此方法。

在终端/命令行窗口中键入以下命令：
```
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 客户端 ID 值。

Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
输入您的 Cycode 客户端密钥值（如果计划使用 OIDC ID 令牌，则跳过）。

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
输入您的 Cycode OIDC ID 令牌值（可选）。

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 令牌：

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

在 Windows 上

从控制面板，导航到系统菜单：
接下来，单击高级系统设置：
在打开的系统属性窗口中，单击环境变量按钮：
创建 CYCODE_CLIENT_ID 和 CYCODE_CLIENT_SECRET 变量，其值分别与您的 ID 和密钥匹配。如果您通过 OIDC 进行身份验证，也请添加 CYCODE_ID_TOKEN 以及您的 OIDC ID 令牌值：
将 cycode.exe 插入路径以完成安装。

安装预提交钩子

Cycode 的预提交和预推送钩子可以在您的本地仓库中设置，以便 Cycode CLI 应用程序在您提交或推送代码到代码库之前自动识别代码中的任何问题。

[!NOTE] 预提交和预推送钩子不适用于 IaC 扫描。

执行以下步骤以安装预提交钩子：

安装预提交钩子

安装预提交框架（必须安装 Python 3.9 或更高版本）：
```
pip3 install pre-commit
```
导航到您要配置的本地 Git 仓库的顶级目录。
在仓库的顶级目录中创建一个名为 .pre-commit-config.yaml 的新 YAML 文件（包含开头的 .），其中包含以下内容：
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode
        stages: [pre-commit]
```
根据您的特定需求修改创建的文件。使用钩子 ID cycode 启用密钥扫描。使用钩子 ID cycode-sca 启用 SCA 扫描。使用钩子 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]
```
安装 Cycode 的钩子：
```
pre-commit install
```
钩子安装成功将显示消息：Pre-commit installed at .git/hooks/pre-commit。
保持预提交钩子为最新：
```
pre-commit autoupdate
```
它会自动将 .pre-commit-config.yaml 中的 rev 更新到 Cycode CLI 的最新可用版本。

[!NOTE] 触发器在 git commit 命令时发生。钩子仅对已暂存提交的文件触发。

安装预推送钩子

要额外安装或代替预提交钩子安装预推送钩子：

将预推送钩子添加到您的 .pre-commit-config.yaml 文件中：

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

安装预推送钩子：

pre-commit install --hook-type pre-push

对于预提交和预推送钩子两者，使用：

pre-commit install
pre-commit install --hook-type pre-push

[!NOTE] 预推送钩子在 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 客户端 ID。
`--client-secret TEXT`	为此特定扫描执行指定 Cycode 客户端密钥。
`--id-token TEXT`	为此特定扫描执行指定 Cycode OIDC ID 令牌。
`--install-completion`	为当前 shell 安装补全功能。
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	显示指定 shell 的补全功能，以便复制或自定义安装。
`-h`, `--help`	显示给定命令的选项。
命令	描述
-------------------------------------------	----------------------------------------------------------------------------------------------------------------------------------------------
auth	验证您的机器，将 CLI 与您的 Cycode 账户关联。
configure	用于配置 CLI 客户端身份验证的初始命令。
ignore	忽略特定的值、路径或规则 ID。
mcp	启动模型上下文协议 (MCP) 服务器，使 AI 能够集成 Cycode 扫描功能。
scan	扫描内容中的 Secrets/IaC/SCA/SAST 违规。您需要指定要执行的扫描类型：commit-history/path/repository 等。
report	生成报告。您需要指定要执行的报告类型，如 SBOM。
status	显示 CLI 状态并退出。

MCP 命令 [实验性]

[!WARNING] MCP 命令仅适用于 Python 3.10 及以上版本。如果您使用的是更早的 Python 版本，此命令将不可用。

模型上下文协议 (MCP) 命令允许您启动一个 MCP 服务器，将 Cycode 的扫描能力暴露给 AI 系统和应用程序。这使得 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" 数组。

使用示例

基本命令示例

使用默认设置（stdio 传输）启动 MCP 服务器：

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 传输类型的更多信息。

配置示例

将 MCP 与 Cursor/VS Code/Claude Desktop 等一起使用 (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"
    }
  }
}

高级配置

自定义证书和超时（代理环境）

如果您的组织使用企业代理或自定义 CA 捆绑包进行 HTTPS 检查，您需要告诉 Cycode CLI（以及底层的 Python TLS 堆栈）在哪里可以找到受信任的证书捆绑包。如果扫描被中断，您还可以增加 MCP 工具调用超时时间。

环境变量	描述
`REQUESTS_CA_BUNDLE`	自定义 CA 捆绑包文件的路径（`.pem` 或 `.crt`）。由 `requests` 库用于 Cycode CLI 进行的所有 HTTPS 调用。
`SSL_CERT_FILE`	自定义 CA 捆绑包文件的路径。由 Python 的底层 `ssl` 模块使用。将此与 `REQUESTS_CA_BUNDLE` 一起设置以获得全面覆盖。
`MCP_TOOL_TIMEOUT`	MCP 客户端（如 Claude 和 GitHub Copilot）等待工具调用完成的超时时间（以秒为单位）。如果长时间运行的扫描在完成前被中断，请增加此值。

[!TIP] 将 REQUESTS_CA_BUNDLE 和 SSL_CERT_FILE 设置为相同的 CA 捆绑包路径。REQUESTS_CA_BUNDLE 覆盖 HTTP 层；SSL_CERT_FILE 覆盖较低级别的 TLS 层。仅使用其中一个在某些环境中仍可能导致证书错误。

带有自定义证书和更长超时时间的 mcp.json 配置示例：

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
        "SSL_CERT_FILE": "/path/to/your/corporate-ca-bundle.pem",
        "MCP_TOOL_TIMEOUT": "1800"
      }
    }
  }
}

[!NOTE] MCP 服务器需要正确的 Cycode CLI 身份验证才能运行。在启动 MCP 服务器之前，请确保您已使用 cycode auth 进行身份验证或配置了您的凭据。

为子代理预授权工具（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>

OpenAPI 规范在首次使用时从 Cycode API 获取，并缓存在 ~/.cycode/openapi-spec.json 中，有效期为 24 小时。不相关的命令（cycode scan、cycode status 等）不会触发获取。

[!NOTE] 您必须经过身份验证（cycode auth 或 CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET 环境变量），cycode platform 才能发现并运行命令。其他 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

Platform 示例

# 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'

Platform 说明与限制

目前仅限只读。 此 beta 版本中仅公开 GET 端点。
规范驱动。 向 API 添加新端点会在下次刷新缓存时自动显示。
无捆绑规范。 安装后（或 24 小时缓存过期后）的第一次 cycode platform 调用会执行网络获取。在慢速连接上，第一次调用可能需要几秒钟；后续调用在缓存过期前几乎即时完成。
使用 CYCODE_SPEC_CACHE_TTL=<seconds> 覆盖缓存 TTL。

Scan 命令

运行扫描

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`）。默认两者都执行。
`--monitor`	指定后，扫描结果将记录在 Cycode 中。
`--cycode-report`	在控制台输出中显示指向 Cycode 平台中扫描报告的链接。
`--no-restore`	指定后，Cycode 将不会运行恢复命令。这将仅扫描直接依赖项！
`--stop-on-error`	如果发生任何文件收集或依赖项恢复失败，则中止扫描，而不是跳过失败的文件并继续。
`--gradle-all-sub-projects`	为所有子项目运行 gradle 恢复命令。这应从以下位置运行
`--maven-settings-file`	仅适用于 Maven，允许在扫描依赖项时使用自定义的 settings.xml 文件
`--help`	显示给定命令的选项。

命令	描述
commit-history	扫描提交历史或在特定提交之间执行差异扫描
path	扫描命令中提供的路径中的文件
pre-commit	使用此命令扫描尚未提交的内容
repository	扫描 git 仓库，包括其历史记录

选项

严重性选项

要将扫描结果限制在特定的严重性阈值，可以将参数 --severity-threshold 添加到扫描命令中。

例如，以下命令将扫描仓库中严重性为“中”或更高的策略违规项：

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 日志部分。如果您在命令中包含了 --cycode-report 标志，则扫描结果之后，指向特定报告的直接链接将显示在您的终端中。

[!WARNING] 您必须拥有 Cycode 中的 owner 或 admin 角色才能查看此页面。

cli-report

报告页面将类似于以下内容：

包漏洞选项

[!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 扫描。

运行 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`
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`	从 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>`

预推送扫描

预推送扫描会在你将更改推送到远程仓库之前自动识别任何问题。此钩子在客户端运行，仅扫描即将推送的提交，从而在问题到达远程仓库之前高效地捕获它们。

[!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.5.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

对于多种扫描类型，请使用此配置：

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.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
```

预推送扫描的工作原理

预推送钩子：

接收有关正在推送哪些提交的信息
计算要扫描的适当提交范围
对于新分支：扫描从与默认分支的合并基础开始的所有提交
对于现有分支：仅扫描自上次推送以来的新提交
运行与其他 Cycode 扫描模式相同的全面扫描

智能默认分支检测

预推送钩子使用以下优先级顺序智能检测默认分支以进行合并基础计算：

环境变量：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 还是任何其他默认分支名称，都能正常工作。

跳过预推送扫描

要跳过特定推送操作的预推送扫描，请使用：

SKIP=cycode-pre-push git push

或跳过所有预推送钩子：

git push --no-verify

[!TIP] 预推送钩子在 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 参数。

在以下示例中，对 cli 子目录执行了路径扫描，并启用了完整显示任何已发现密钥的选项：

cycode scan --show-secret path ./cli

这样，结果将不会被混淆。

软失败

在正常操作中，当扫描结果中发现问题时，CLI 将返回退出代码 1。根据你的 CI/CD 设置，这通常会导致整体失败。如果你不希望发生这种情况，可以使用软失败功能。

通过在任何类型的扫描中添加 --soft-fail 选项，无论是否发现任何结果，退出代码都将强制为 0。

扫描结果示例

密钥结果示例

╭─────────────────────────────────────────────────────────────── 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 [email protected]

在上面的示例中，将 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:
    - [email protected]
  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 报告

仓库

为仓库 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 文件。

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 [email protected] /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