Cycode

官方

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

GitHub

你可以用 Cycode MCP 做什么？

扫描仓库路径中的硬编码密钥 — 让助手对本地目录运行 cycode_secret_scan，以检测暴露的凭据。
检查依赖项中的已知漏洞 — 对项目路径触发 cycode_sca_scan，以识别存在漏洞或不合规的开源包。
审计基础设施即代码文件中的错误配置 — 在 Terraform 或 CloudFormation 目录上使用 cycode_iac_scan，以揭示风险设置。
审查源代码中的安全缺陷 — 对代码库运行 cycode_sast_scan，以发现代码层面的弱点和质量问题。
验证 CLI 身份验证和版本状态 — 调用 cycode_status 以确认与 Cycode 的连接以及当前激活的版本。

文档

Cycode CLI 用户指南

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

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

前提条件

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

安装

以下安装步骤适用于 Windows 和 UNIX/Linux 操作系统。

[!NOTE] 以下步骤假设使用 python3 和 pip3 来执行 Python 相关命令；但某些系统可能使用 python 和 pip 命令，具体取决于您的 Python 环境配置。

安装 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 扫描。

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

安装预提交钩子

安装 pre-commit 框架（必须安装 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 引擎处理文件发现和过滤，就像 cycode scan -t <type> path ./src 从 CLI 执行的操作一样。
files （备选） — 将文件路径映射到其完整字符串内容的字典。仅在文件不在磁盘上时使用（例如尚未保存的内存中编辑）。

[!TIP] 尽可能使用 paths。将大文件（如 package-lock.json）作为内联内容传递可能会超出 token 限制并减慢 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 传输类型的信息。

配置示例

将 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 中，有一个 mcp 对象，包含嵌套的 servers 子对象，而不是独立的 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 设置中的 allowedTools 列表（~/.claude/settings.json）：

{
  "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 配置

平台命令 [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

平台示例

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

平台注意事项与限制

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

AI Guardrails [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`）。默认为两者都执行。
`--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 参数。

例如，以下命令将扫描仓库中严重级别为 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 日志部分。如果你在命令中包含了 --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`
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>`

预推送扫描

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

[!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 扫描命令的目录中。

[!WARNING]

无效文件：如果 .cycodeignore 文件包含语法错误，CLI 扫描将失败并返回错误。

忽略路径与忽略违规：此文件用于排除路径。这与 CLI 忽略特定违规的能力不同（例如，使用 --ignore-violation 标志）。

支持的扫描器

SAST
IaC（即将推出）
SCA（即将推出）

扫描结果

每次扫描完成后都会显示一条消息，说明是否发现了任何问题。

如果未发现问题，扫描将以以下成功消息结束：

Good job! No issues were found!!! 👏👏👏

如果发现问题，则会在完成时显示违规卡片。在这种情况下，您应该检查相关文件中结果消息突出显示的特定行。实施解决该问题所需的任何更改，然后再次执行扫描。

显示/隐藏机密

在以下示例中，在子文件夹 cli 中的文件 secret_test 中发现了机密。消息的第二部分显示了机密出现的特定行，在本例中是一个分配给 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 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，其中~表示用户s home directory, for example, /Users/name`（在macOS上）。

可以使用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]`	业务影响	否	中等

例如：
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