Cycode

Cycode CLI 用户指南

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

本指南将介绍安装和使用方法。

目录

1. 先决条件
2. 安装
   1. 安装 Cycode CLI
      1. 使用 Auth 命令
      2. 使用 Configure 命令
      3. 添加到环境变量
         1. 在 Unix/Linux 上
         2. 在 Windows 上
   2. 安装 Pre-Commit Hook
3. Cycode CLI 命令
4. 证书和代理
5. MCP 命令
   1. 启动 MCP 服务
   2. 可用选项
   3. MCP 工具
   4. 使用示例
   5. 高级配置
6. Platform 命令
   1. 发现命令
   2. 示例
   3. 说明和限制
7. AI Guardrails
   1. AI Guardrails 收集的数据
8. Scan 命令
   1. 运行扫描
      1. 选项
         1. 严重性阈值
         2. 监控
         3. Cycode 报告
         4. 软件包漏洞
         5. 许可证合规性
         6. 锁定文件还原
         7. 出错时停止
      2. 代码仓库扫描
         1. 分支选项
      3. 路径扫描
         1. Terraform 计划扫描
      4. 提交历史扫描
         1. 提交范围选项（差异扫描）
      5. Pre-Commit 扫描
         1. 本地差异扫描（IDE 集成）
      6. Pre-Push 扫描
   2. 扫描结果
      1. 显示/隐藏机密信息
      2. 软失败
      3. 扫描结果示例
         1. 机密信息结果示例
         2. IaC 结果示例
         3. SCA 结果示例
         4. SAST 结果示例
      4. 公司自定义修复指南
   3. 忽略扫描结果
      1. 忽略机密值
      2. 忽略机密 SHA 值
      3. 忽略路径
      4. 忽略机密、IaC 或 SCA 规则
      5. 忽略软件包
      6. 通过配置文件忽略
9. Report 命令
   1. 生成 SBOM 报告
10. Import 命令
11. 扫描日志
12. 语法帮助

先决条件

• Cycode CLI 应用要求 Python 版本为 3.10 或更高版本。
• 使用 cycode auth 命令通过 CLI 向 Cycode 进行身份验证
  • 或者，按照服务账户令牌和个人访问令牌页面中所述的步骤，获取 Cycode 客户端 ID 和客户端密钥。

安装

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

说明

以下步骤假设 Python 相关命令使用 python3 和 pip3；不过，根据 Python 环境的配置，某些系统可能使用 python 和 pip 命令。

安装 Cycode CLI

要在本地计算机上安装 Cycode CLI 应用，请执行以下步骤：

1. 打开命令行或终端应用。

2. 执行以下命令之一：

   • 从 PyPI 安装：

     pip3 install cycode
     

   • 从 Homebrew 安装：

     brew install cycode
     

   • 从 GitHub Releases 安装：导航到页面并下载适用于你的操作系统和架构的可执行文件，然后运行以下命令：

   cd /path/to/downloaded/cycode-cli
   chmod +x cycode
   ./cycode
   

3. 最后，对 CLI 进行身份验证。设置 Cycode 客户端 ID 和凭据（客户端密钥或 OIDC ID 令牌）有三种方法：

   • cycode auth（推荐）
   • cycode configure
   • 将其添加到环境变量

使用 Auth 命令

说明

这是设置本地计算机以通过 Cycode CLI 进行身份验证的推荐方法。

1. 在终端/命令行窗口中输入以下命令：

   cycode auth

2. 浏览器窗口将打开，提示你登录 Cycode（如下所示）：

   

3. 在此页面输入登录凭据并登录。

4. 随后，你将转到以下页面，并被要求选择要授权 Cycode 使用的业务组（如适用）：

   

   说明

   这将成为通过 Cycode CLI 进行身份验证的默认方法。

5. 单击 Allow 按钮，即可在所选业务组中授权 Cycode CLI。

   

6. 完成后，如果选择成功，你将看到以下画面：

   

7. 退出浏览器窗口后，你将在终端/命令行窗口中看到以下内容：

   Successfully logged into cycode

使用 Configure 命令

说明

如果你已通过 Linux 或 Windows 环境变量设置 Cycode Client ID 和 Client Secret，这些凭据将优先于此方法。

1. 在终端／命令行窗口中输入以下命令：

   cycode configure
   

2. 输入 Cycode API URL 值（留空则使用默认值）。

   Cycode API URL [https://api.cycode.com]: https://api.onpremise.com

3. 输入 Cycode APP URL 值（留空则使用默认值）。

   Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com

4. 输入 Cycode Client ID 值。

   Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d

5. 输入 Cycode Client Secret 值（如果计划使用 OIDC ID 令牌，则跳过此步骤）。

   Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e

6. 输入 Cycode OIDC ID 令牌值（可选）。

   Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

7. 如果成功输入这些值，你将看到以下消息：

   Successfully configured CLI credentials!

   或／以及

   Successfully configured Cycode URLs!

进入用户文件夹下的 .cycode 文件夹，即可在该文件夹中的 credentials.yaml 文件里找到已创建的凭据。 URL 则保存在该文件夹中的 config.yaml 文件里。

添加到环境变量

在 Unix/Linux 上：

export CYCODE_CLIENT_ID={your Cycode ID}

以及

export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

如果你的组织使用 OIDC 身份验证，也可以改为提供 ID 令牌（或在此基础上额外提供）：

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

在 Windows 上

1. 在控制面板中，导航至 System 菜单：

   

2. 接着，点击 Advanced system settings：

   

3. 在打开的 System Properties 窗口中，点击 Environment Variables 按钮：

   

4. 创建 CYCODE_CLIENT_ID 和 CYCODE_CLIENT_SECRET 变量，并分别将其值设为对应的 ID 和 Secret Key。如果通过 OIDC 进行身份验证，也请添加 CYCODE_ID_TOKEN，并将其值设为 OIDC ID 令牌：

   

5. 将 cycode.exe 添加到路径中以完成安装。

安装 Pre-Commit Hook

你可以在本地仓库中设置 Cycode 的 pre-commit 和 pre-push hook，这样 Cycode CLI 应用就能在你将代码提交或推送到代码库之前，自动识别代码中的问题。

说明

IaC 扫描不支持 pre-commit 和 pre-push hook。

按照以下步骤安装 pre-commit hook：

安装 Pre-Commit 钩子

1. 安装 pre-commit 框架（必须安装 Python 3.10 或更高版本）：

   pip3 install pre-commit
   

2. 导航到要配置的本地 Git 仓库的顶层目录。

3. 在仓库的顶层目录中创建一个名为 .pre-commit-config.yaml（包含开头的 .）的新 YAML 文件，并写入以下内容：

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

4. 根据具体需求修改所创建的文件。使用钩子 ID cycode 启用 Secrets 扫描。使用钩子 ID cycode-sca 启用 SCA 扫描。使用钩子 ID cycode-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]
   

5. 安装 Cycode 的钩子：

   pre-commit install
   

   钩子安装成功后会显示消息：Pre-commit installed at .git/hooks/pre-commit。

6. 保持 pre-commit 钩子为最新版本：

   pre-commit autoupdate
   

   它会自动将 .pre-commit-config.yaml 中的 rev 更新为 Cycode CLI 的最新可用版本。

说明

在执行 git commit 命令时触发。 钩子仅会扫描已暂存待提交的文件。

安装 Pre-Push 钩子

如需在 pre-commit 钩子之外安装 pre-push 钩子，或改为安装 pre-push 钩子：

1. 将 pre-push 钩子添加到 .pre-commit-config.yaml 文件中：

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

2. 安装 pre-push 钩子：

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

3. 如需同时使用 pre-commit 和 pre-push 钩子，请使用：

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

说明

pre-push 钩子会在执行 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 状态并退出。

证书和代理

默认情况下，Cycode CLI 会使用随 CLI 提供的 CA 证书包验证 HTTPS 连接。

如果你的组织使用会检查 HTTPS 流量的代理，或者使用自带 CA 的本地部署版本，你有两个选项。

选项 1 — 使用机器上已安装的证书。 如果你的 CA 位于机器的证书存储区中（受管理设备通常如此），可选择启用：

export CYCODE_CLI_ENABLE_TRUSTSTORE=1

随后，CLI 会使用 Windows 证书存储区、macOS Keychain，或 Linux 上的系统 CA 目录进行验证，无需配置证书路径。

重要

这是有意设计为默认不启用的。信任机器证书存储区，就意味着信任其中的每个根证书，包括由管理员或恶意软件安装的证书。只有确认信任机器的证书存储区时，才启用此选项。

选项 2 — 指定 CA 证书包文件。 无需选择启用：

环境变量	说明
REQUESTS_CA_BUNDLE	要信任的 CA 证书包文件路径（.pem 或 .crt）。
CURL_CA_BUNDLE	REQUESTS_CA_BUNDLE 的别名；仅当后者未设置时生效。

两个选项可以组合使用：设置 CYCODE_CLI_ENABLE_TRUSTSTORE=1 时，REQUESTS_CA_BUNDLE 中的证书会与机器证书存储区中的证书一并受信任，而不是替代它们。

提示

运行任何命令时添加 -v，即可查看正在使用的信任来源，例如 cycode -v status。

注意：

• 在 Windows 上，如果未设置 REQUESTS_CA_BUNDLE 或 CURL_CA_BUNDLE，CLI 一直会回退到系统证书存储区。此行为没有变化。
• 代理本身通过标准环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 配置。

MCP 命令 [实验功能]

Model Context Protocol（MCP）命令可启动 MCP 服务，向 AI 系统和应用程序提供 Cycode 的扫描功能。这样，AI 模型便可以通过标准化协议与 Cycode CLI 工具交互。

提示

为获得最佳体验，请使用 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（备用）——将文件路径映射到完整字符串内容的字典。仅当文件不在磁盘上时使用此模式（例如，尚未保存的内存中编辑）。

提示

请尽可能使用 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 传输类型的更多信息。

配置示例

在 Cursor/VS Code/Claude Desktop 等应用中使用 MCP（mcp.json）

说明

对于 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 以使用机器上已有的证书，也可以设置 REQUESTS_CA_BUNDLE 并指向 CA 捆绑文件。

使用自定义 CA 捆绑文件和较长超时时间的 mcp.json 配置示例：

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

说明

MCP 服务需要正确的 Cycode CLI 身份验证才能正常工作。请确保已使用 cycode auth 完成身份验证，或在启动 MCP 服务前配置好凭据。

为子 Agent 预先授权工具（Claude Code）

当 Claude Code 将工作委派给后台子 Agent（例如并行运行扫描）时，这些子 Agent 无法显示交互式权限提示。如果 Cycode 工具尚未获准使用，扫描将在子 Agent 环境中静默失败。

若要预先授权 Cycode MCP 工具，使其在所有环境（包括子 Agent）中都能正常工作，请将它们添加到 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 将不再提示批准，并且它们也能在子 Agent 中正常工作。

MCP 故障排除

如果 MCP 服务出现问题，可以启用调试日志以获取有关运行情况的详细信息。启用调试日志有两种方法：

1. 使用 -v 或 --verbose 标志：

cycode -v mcp

2. 使用 CYCODE_CLI_VERBOSE 环境变量：

CYCODE_CLI_VERBOSE=1 cycode mcp

调试日志会显示以下详细信息：

• 服务启动和配置
• 连接尝试和状态
• 工具执行和结果
• 发生的错误或警告

这些信息有助于：

• 诊断连接问题
• 了解特定工具无法正常工作的原因
• 找出身份验证问题
• 调试传输方式相关的问题

MCP 配置

Platform 命令 [BETA]

警告

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 等）不会触发获取操作。

说明

必须完成身份验证（使用 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'

平台说明与限制

• 目前为只读。 此测试版仅开放 GET 端点。
• 由规范驱动。 向 API 添加新端点后，下次刷新缓存时会自动将其公开。
• 不附带规范文件。 安装后（或 24 小时缓存过期后）首次调用 cycode platform 时，会从网络获取规范文件。网络连接较慢时，首次调用可能需要几秒；在缓存过期前，后续调用几乎会立即完成。
• 使用 CYCODE_SPEC_CACHE_TTL=<seconds> 覆盖缓存 TTL。

AI Guardrails [BETA]

AI Guardrails 会在受支持的 AI 编码 Agent（Claude Code、Cursor、Copilot、Codex）中安装钩子，在提示词、Agent 读取的文件以及 MCP 工具参数到达模型之前，扫描其中是否包含机密信息。

AI Guardrails 收集的数据

扫描在服务端进行，因此扫描的内容会离开本机：提示词文本、Agent 读取的文件内容以及 MCP 工具参数都会发送到你的 Cycode 租户，以检查其中是否包含机密信息。

每个事件还会附带开发者和机器的相关信息，以便将发现项归因到对应的设备和用户。其中部分信息属于个人数据：

• 设备标识符 — 机器的主机名和硬件序列号。
• 用户标识符 — 登录 AI 编码 Agent 的用户邮箱地址，以及本地操作系统用户名。
• 环境详情 — 操作系统及版本、AI Agent、其版本和正在使用的模型、Agent 的 MCP 配置文件内容，以及已启用的插件。

硬件序列号会缓存在本地临时文件中，只有运行该命令的用户可以读取，因此重复调用钩子时不会重新查询硬件。

如果你的环境不接受收集这些数据，请勿安装 Guardrails 钩子 （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）。默认扫描全部类型。
--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。

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

cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase

监控选项

说明

此选项仅适用于 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 标志，扫描结果后会在终端中显示指向特定报告的直接链接。

警告

你必须拥有 Cycode 中的 owner 或 admin 角色才能查看此页面。

报告页面大致如下：

软件包漏洞选项

说明

此选项仅适用于 SCA 扫描。

若要扫描本地仓库中特定的软件包漏洞，请在 -t sca 或 --scan-type sca 选项后添加参数 --sca-scan package-vulnerabilities。

在前面的示例中，如果只想针对软件包漏洞运行 SCA 扫描，可以执行以下命令：

cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase

许可证合规性选项

说明

此选项仅适用于 SCA 扫描。

若要扫描本地仓库的特定分支，请添加参数 --sca-scan license-compliance，并在后面指定要扫描的分支名称。

在前面的示例中，如果只想扫描名为 dev 的分支，可以执行以下命令：

cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev

不再维护的软件包选项

说明

此选项仅适用于 SCA 扫描。

若要仅扫描不再维护的软件包（其 OpenSSF Scorecard 的 Maintained 检查得分较低，表示近期提交和问题活动很少或没有），请在 -t sca 或 --scan-type sca 选项后添加参数 --sca-scan unmaintained-packages。

说明

是否报告不再维护的软件包由你组织的策略决定。此选项会缩小扫描报告的范围，但无法启用对你的租户已关闭的策略。

在前面的示例中，如果只想针对不再维护的软件包运行 SCA 扫描，可以执行以下命令：

cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase

锁文件还原选项

说明

此选项仅适用于 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）

如果只有配置文件，可以按以下步骤生成计划：

1. 初始化包含 Terraform 配置文件的工作目录：

   terraform init

2. 创建 Terraform 执行计划并保存二进制输出：

   terraform plan -out={tfplan_output}

3. 将二进制输出文件转换为可读的 JSON：

   terraform show -json {tfplan_output} > {tfplan}.json

4. 使用 Cycode CLI 扫描 {tfplan}.json：

   cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json

提交历史扫描

说明

IaC 扫描不支持提交历史扫描。

提交历史扫描命令提供两项主要功能：

1. 完整历史扫描：分析仓库历史记录中的所有提交
2. 差异扫描：仅扫描特定提交之间的更改

机密扫描可以分析仓库历史记录中的所有提交，因为引入后又被删除的机密仍可能已泄露或暴露。对于 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

提示

对于 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 将扫描范围限定为编辑器中当前打开的文件。

说明

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

推送前扫描

推送前扫描会在你将更改推送到远程仓库之前自动识别问题。此钩子在客户端运行，只扫描即将推送的提交，因此能高效地在问题到达远程仓库前将其发现。

说明

IaC 扫描不支持推送前钩子。

推送前钩子与 pre-commit 框架集成，可配置为在任何 git push 操作之前运行。

安装推送前钩子

使用 pre-commit 框架设置推送前钩子：

1. 安装 pre-commit 框架（如果尚未安装）：

   pip3 install pre-commit
   

2. 创建或更新 .pre-commit-config.yaml 文件，将推送前钩子添加到其中：

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

3. 对于多种扫描类型，请使用以下配置：

   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]
   

4. 安装推送前钩子：

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

   安装成功后会显示消息：Pre-push installed at .git/hooks/pre-push。

5. 更新推送前钩子：

   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 钩子），请设置这两个选项。

智能检测默认分支

从手写钩子运行时，推送前扫描会按以下优先级检测用于计算合并基点的默认分支：

1. 环境变量：CYCODE_DEFAULT_BRANCH — 可用于手动覆盖
2. Git 远程 HEAD：使用 git symbolic-ref refs/remotes/origin/HEAD 检测实际的远程默认分支
3. Git 远程信息：如果 symbolic-ref 失败，则回退到 git remote show origin
4. 硬编码回退值：使用常见的默认分支名称（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

提示

推送前钩子会在执行 git push 命令时触发，只扫描即将推送的提交，因此比扫描整个仓库更高效。

从扫描中排除路径

你可以使用 .cycodeignore 文件，告知 Cycode CLI 在扫描时排除哪些文件和目录。 它的工作方式与 .gitignore 文件相同。这样可以让扫描聚焦于相关代码，并防止特定路径在本地触发违规。

工作原理

1. 在工作文件夹中创建名为 .cycodeignore 的文件。
2. 使用与 .gitignore 相同的模式，列出要排除的文件和目录。
3. 将此文件放在计划运行 cycode scan 命令的目录中。

警告

• 无效文件：如果 .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 文件中。

警告

添加要忽略的值时，应仔细考虑相关值、路径和策略，确保扫描能够发现真正的阳性结果。

以下是 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。

忽略软件包

说明

此选项仅适用于 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/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。

警告

“按值忽略”的值不会以纯文本形式存储！ 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

报告命令

生成 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 [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